Saltar al contenido principal
Una conversación es el hilo de WhatsApp entre tu negocio y un contacto. Casi todos los endpoints de envío y de acciones (/conversation/*) la reciben en el cuerpo del request bajo el objeto conversation.

​
Identificar una conversación

El objeto conversation acepta uno de cuatro identificadores. 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).
​
uuid
string
El UUID de un GET /conversations. El camino más directo y estable (puede quedar obsoleto si dos conversaciones del mismo contacto se unifican — ver la nota de unificación más abajo).
​
whatsapp_user_id
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.
​
username
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).
​
phone
string
Número en formato E.164 (+5215512345678). Se normaliza a dígitos antes del lookup. Útil cuando solo tienes el teléfono.
El teléfono puede estar duplicado entre contactos (números reciclados o identidades separadas que comparten número): en ese caso la API responde 409 (PHONE_NUMBER_AMBIGUOUS) en vez de adivinar — identifica la conversación por whatsapp_user_id o uuid. Además, whatsapp_user_id puede cambiar si el usuario re-registra su cuenta de WhatsApp (rotación de identidad del lado de Meta). Usa el uuid como clave estable en tu sistema y whatsapp_user_id como identificador de resolución preferente.
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.

​
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 quick replies.
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.
Enviar texto, media o quick reply con la ventana cerrada falla con WINDOW_CLOSED (422). Envía una plantilla primero para reabrirla.

​
Consultar el estado de la ventana

Antes de enviar un mensaje libre, puedes verificar si la ventana está abierta con POST /conversation/status:
La respuesta incluye window.status (open o closed) 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.

​
Próximos pasos

Enviar mensajes

Texto, media, quick replies y plantillas.

Plantillas

Cómo enviar plantillas con la ventana de 24h cerrada.