Disparar mensaje proactivo por API (WhatsApp y Widget Web)

Cuándo usar

• Cuando un sistema externo (tu backend, CRM, automatización de marketing) necesita iniciar una conversación con un contacto específico — sin que un agente la abra manualmente.

• Para avisos transaccionales y proactivos por contacto: confirmación de pedido, recordatorio de pago, actualización de estado, reanudación del carrito.

• En dos canales, con la misma autenticación (api_access_token):

  • WhatsApp — envía un mensaje de plantilla aprobado al teléfono del contacto.

  • Widget Web de área autenticada (HMAC) — muestra un mensaje que aparece cuando el contacto vuelve a estar autenticado en el chat de tu sitio/app.

Requisitos previos

• Un Token de Acceso API de Cloud Chat (disponible en tu perfil, en Perfil → Configuraciones → Access Token). Debe estar en el encabezado api_access_token.

• El account_id de tu cuenta (aparece en la URL de Cloud Chat).

• La dirección de tu instancia de Cloud Chat, que es el dominio que aparece en el navegador cuando accedes a la plataforma (ej.: cloudchat5.cloudhumans.com). Las llamadas deben dirigirse a esa dirección. Una dirección de otra instancia responde con 401.

• El token vale sólo para la instancia en la que fue generado. Si generas uno nuevo, el anterior deja de funcionar inmediatamente, así que actualiza en todos los sistemas que lo usan.

• Para WhatsApp: una bandeja de entrada de WhatsApp conectada + una plantilla aprobada por Meta.

• Para Widget Web: una bandeja de entrada de Widget Web con HMAC obligatorio (área autenticada / identidad verificada) + un contacto identificable.

Cómo funciona

Autenticación

Los dos endpoints usan el mismo encabezado. Nunca expongas el token en el front-end — estos disparos son servidor a servidor.

api_access_token: TU_API_ACCESS_TOKEN
Content-Type: application/json

WhatsApp: disparo por plantilla

Envía (push) un mensaje activo — llega al WhatsApp del contacto en el momento. Como es WhatsApp, el contenido tiene que ser una plantilla aprobada.

POST https://{TU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_whatsapp_conversation

{TU_DOMINIO} es la dirección de tu instancia (ej.: cloudchat5.cloudhumans.com).

{
  "inbox_id": 123,
  "phone_number": "+5511999998888",
  "template_name": "lembrete_pago",
  "labels": ["campaña-x", "vip"],
  "cliente": "Juan",
  "valor": "R$ 120,00"
}

• inbox_id — la bandeja de WhatsApp desde la cual se envía el mensaje.

• phone_number — teléfono del contacto en formato internacional E.164 (con + y código del país, ej.: +5511999998888).

• template_name — nombre de la plantilla aprobada.

• Variables de la plantilla — cada variable debe enviarse como un campo al nivel raíz del cuerpo (hermano de inbox_id/phone_number/template_name), con el nombre de la variable de la plantilla. Ej.: una plantilla con las variables cliente y valor debe recibir los campos "cliente" y "valor". Si la plantilla usa variables numeradas ({{1}}, {{2}}), los campos son "1" y "2". No pongas estos campos dentro de un objeto template_params.

• labels (opcional) — arreglo de cadenas con títulos de etiquetas a aplicar en la conversación creada (ej.: ["campaña-x", "vip"]). Los títulos se normalizan en minúsculas y las etiquetas se agregan sin eliminar las existentes. Las etiquetas nuevas se crean automáticamente en la cuenta solo si el token tiene permisos de administrador o CX Engineer; con token de agente, los títulos inexistentes son ignorados. Detalles en Cómo enviar mensaje proactivo por WhatsApp vía API.

WhatsApp: límite de solicitudes

El endpoint de WhatsApp acepta hasta 200 solicitudes por minuto por clave de API. Por encima de eso, la respuesta es 429 con el encabezado Retry-After (segundos hasta liberar). Espera ese tiempo antes de reintentar y, en lotes grandes, distribuye los envíos a lo largo de los minutos. Una solicitud que recibe 429 no fue procesada, así que reenviarla no duplica el mensaje. El cuerpo de la respuesta, otros encabezados y cómo se cuenta el límite están en Cuáles son los límites de solicitud (rate limits) de las rutas de la API de Cloud Chat?.

Widget Web (área autenticada): disparo por contacto

Muestra un mensaje que aparece de forma pasiva: el widget no envía push — el mensaje aparece en la próxima vez que el contacto abra el chat autenticado en el área logada. Puedes disparar incluso a quienes todavía no abrieron el chat (identificando mediante identifier).

POST https://{TU_DOMINIO}/api/v1/accounts/{ACCOUNT_ID}/conversations/create_proactive_web_widget_conversation

{
  "inbox_id": 456,
  "identifier": "usuario-42",
  "content": "¡Hola Juan! Vi que tu plan vence mañana. ¿Puedo ayudarte a renovarlo?",
  "idempotency_key": "renovacion-usuario-42-2026-06-28"
}

• inbox_id — la bandeja del Web Widget (HMAC obligatorio).

• Identificación del contacto — envía exactamente uno de estos:

  • identifier — tu identificador estable del usuario. Crea el contacto si aún no existe.

  • email — usa un contacto ya identificable con ese email.

  • contact_id — el ID del contacto en Cloud Chat.

• content — el texto libre del mensaje (no necesita plantilla).

• idempotency_key (opcional) — consulta abajo.

• contact_attributes (opcional) — atributos/nombre para enriquecer el contacto en la creación.

Widget Web: formato del identificador

El identifier necesita ser exactamente igual al valor que tu app usa para generar el HMAC en el SDK del widget para ese usuario. Si difieren (ej.: tú disparas "42", pero el widget envía "usuario-42"), Cloud Chat tratará como contactos diferentes y el mensaje no aparecerá para el usuario.

• identifier — cadena estable (el mismo del HMAC). Se recomienda usar el ID del usuario en tu sistema.

• email — un email válido de un contacto ya identificable.

Widget Web: múltiples bandejas y contactos sin teléfono

• Múltiples bandejas de Web Widget. El identifier identifica al contacto en toda la cuenta, por lo que el mismo usuario puede ser alcanzado en diferentes bandejas (ej.: productos o áreas logadas distintas) usando el mismo identifier. El disparo siempre ocurre por bandeja (inbox_id): cada bandeja mantiene su propia conversación/sesión con el contacto. Para hablar con el usuario en dos áreas, envía un mensaje a cada inbox_id.

• Cuando no hay número de teléfono. A diferencia de WhatsApp (donde el número es la identidad), en el Web Widget el contacto se identifica por identifier/email y no necesita tener teléfono. Los contactos sin número son completamente soportados — el teléfono no es relevante en este canal.

Idempotencia (Web Widget)

Reenvíos son seguros si utilizas idempotency_key. La misma clave, dentro de 24 horas, devuelve la misma conversación, en lugar de crear una copia duplicada — útil para intentos de reenvío. Reutilizar la misma clave para un contacto diferente es rechazado (error idempotency_key_contact_mismatch).

Principales errores

Observaciones

• WhatsApp = activo (push, vía plantilla); Widget Web = pasivo (texto libre, en la próxima sesión autenticada). Elige el canal según el tipo de entrega deseada.

• El disparo es por contacto en ambos canales (uno a uno), no una campaña masiva.

• La conversación creada queda fuera de la cola/SLA de los agentes hasta que el contacto participe — no cuenta como atención activa mientras nadie responda.

• Mantén el api_access_token sólo en el servidor.