/conversation/*) la reciben en el
cuerpo del request bajo el objeto conversation.
Identificar una conversación
El objetoconversation acepta uno de cuatro identificadores, más channel
(obligatorio), la clave pública del canal objetivo. El resolver
evalúa en este orden: uuid → whatsapp_user_id → username → phone:
whatsapp_user_id busca por igualdad exacta y username por igualdad
case-insensitive (ignora mayúsculas); phone se normaliza a dígitos.
Cuando el contacto tiene BSUID, phone y
whatsapp_user_id identifican valores distintos (ver Note).
string
Clave estable de una conversación que ya conoces (por ejemplo, persistida de
una integración previa). El camino más directo, aunque puede quedar obsoleto si
dos conversaciones del mismo contacto se unifican — ver la nota de unificación
más abajo.
string
El BSUID del contacto (identidad opaca de Meta). Resuelve por igualdad exacta
contra el BSUID guardado; si no resuelve, el endpoint responde
404 sin caer a
phone. Identificador recomendado de aquí en adelante.string
Username público de WhatsApp del contacto, con o sin
@ inicial y sin
distinguir mayúsculas. Resolución best-effort contra el último username
observado por la plataforma (el usuario puede cambiar su handle); si varios
contactos lo comparten, el endpoint responde 409 (USERNAME_AMBIGUOUS).string
Número en formato E.164 (
+5215512345678). Se normaliza a dígitos antes del
lookup. Útil cuando solo tienes el teléfono.string
requerido
Clave pública del canal — cópiala del dashboard en Configuración → Canales
(campo Clave de canal), o lístalas con
GET /channels. Obligatorio en todo
request: fija el canal objetivo. No distingue mayúsculas/minúsculas (se
normaliza en el servidor). No identifica por sí solo. En las vías por contacto
(phone, username, whatsapp_user_id) restringe la resolución al canal
indicado; con uuid el motor lo ignora, pero el contrato igual lo exige.
Desambigua el canal, no el contacto: si varios contactos comparten
phone o username, esa ambigüedad se resuelve con whatsapp_user_id o
uuid. En las vías por contacto, si envías una clave que no existe, la API
responde 404 (CHANNEL_NOT_FOUND).phone y whatsapp_user_id son identificadores distintos: phone es el
teléfono (wa_id sin +) y whatsapp_user_id es el BSUID del contacto. Coinciden
solo mientras el contacto no tiene BSUID. En las respuestas, whatsapp_user_id
devuelve el BSUID real cuando existe, con fallback al teléfono para que siempre
haya un valor resoluble. Cuidado en el round-trip: si el contacto aún no tiene
BSUID, este campo trae el teléfono; reenvíalo entonces como phone, no como
whatsapp_user_id — el resolver matchea whatsapp_user_id por igualdad exacta y
daría 404.Cuando un mismo contacto quedó registrado dos veces por identidad (por ejemplo,
primero solo con su teléfono y luego con su BSUID), las dos conversaciones se
unifican automáticamente en una sola: todo el historial pasa a la
sobreviviente. El
uuid de la conversación absorbida deja de resolver y responde
404; el teléfono y el BSUID migran a la sobreviviente. Si guardaste un uuid y
empieza a dar 404, vuelve a resolver la conversación por phone o
whatsapp_user_id.Leer una conversación
Te diriges a una conversación con una de las referencias de arriba: la API pública no ofrece un listado para enumerarlas. Esas referencias salen de tu propio inbound —elphone o el whatsapp_user_id del contacto que te
escribió— o de un uuid que hayas persistido.
Con esa referencia, GET /conversation devuelve su estado (conversation_info
y contact_info) y GET /conversation/messages su historial. El shape completo
y los parámetros están en Conversación e hilo.
La ventana de 24h
Es el concepto central de WhatsApp y decide qué puedes enviar.1
El contacto te escribe
WhatsApp abre una ventana de 24 horas. Cada nuevo mensaje del contacto
reinicia el contador.
2
Ventana abierta
Puedes enviar mensajes libres: texto, media y respuestas rápidas.
3
Pasan 24h sin respuesta
La ventana se cierra. El único mensaje permitido es una plantilla
aprobada por Meta.
4
Enviar una plantilla reabre la ventana
Vuelves a poder enviar mensajes libres.
Consultar el estado de la ventana
Antes de enviar un mensaje libre, puedes verificar si la ventana está abierta conPOST /conversation/status:
conversation.uuid (la clave estable de la conversación),
window.status (open o closed), window.expires_at (timestamp ISO de cierre
de la ventana; null si el contacto nunca escribió) y window.hours_remaining,
además del estado de asignación, buzón, tags e inbox_status de la conversación.
Úsalo para decidir entre un mensaje libre y una plantilla.
Leer el hilo
El hilo se pagina hacia atrás en el tiempo: la primera llamada trae los
items más recientes y
next_cursor avanza hacia los más antiguos.direction y author), qué
pasó (event), con qué contenido (content_type y body) y cuándo
(sent_at). Leídos en orden, se ven como la conversación real:
type distingue las dos clases de item: message es contenido que viajó
por WhatsApp (trae content_type y status), y event es algo que ocurrió en
el historial —una nota de contexto, un dato del contacto actualizado, una
conversión— sin contenido enviado.
El orden dentro de cada página es cronológico, y sent_at es la clave para
ordenar el hilo completo a medida que paginas hacia atrás.
Próximos pasos
Enviar mensajes
Texto, media, respuestas rápidas y plantillas.
Plantillas
Cómo enviar plantillas con la ventana de 24h cerrada.