Inicio API e integraciones | Claves, endpoints y webhooks Cómo enviar un mensaje proactivo por WhatsApp vía API

Cómo enviar un mensaje proactivo por WhatsApp vía API

Última actualización el Sep 23, 2026

La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. Si este artículo y la referencia no coinciden, vale lo que dice la referencia.

Cuándo usar

  • Quieres iniciar una conversación de WhatsApp por API desde un sistema externo
  • Necesitas disparar plantillas aprobadas por Meta con variables dinámicas
  • Necesitas entender el comportamiento esperado del ticket creado por esta API

Requisitos previos

Sobre este artículo

Este endpoint crea una conversación proactiva por WhatsApp usando una plantilla previamente configurada. Los parámetros de la plantilla son dinámicos y varían según la configuración de la plantilla.

Comportamiento de creación del ticket

Como el sistema no sabe qué agente debe recibirlo, el mensaje no nace asignado. Por eso el globo aparece verde (mensajes automáticos), en lugar de naranja.

  • Genera un nuevo ticket — excepto si la bandeja está configurada con conversación única (lock to single conversation), en cuyo caso el mensaje se agrega a la conversación existente del contacto

  • El ticket nace con estado abierto

Si el cliente tiene dos tickets abiertos, los nuevos mensajes enviados por el cliente siempre se dirigirán al ticket más reciente.

Endpoint

POST https://cloudchat.cloudhumans.com/api/v1/accounts/{account_id}/conversations/create_proactive_whatsapp_conversation

Headers

Header Valor
content-type application/json
api_access_token Clave de acceso de la API

Parámetros del body

Parámetro Obligatorio Descripción
inbox_id Sí ID de la bandeja por la que se enviará el mensaje
phone_number Sí Número del destinatario en formato E.164
template_name Sí Nombre exacto de la plantilla aprobada
labels No Array de strings con etiquetas a aplicar a la conversación creada — ver la sección Aplicando etiquetas (labels) abajo
header_attachment No URL del adjunto, si la plantilla admite multimedia en el encabezado
button_param_# No Variables de botones — reemplaza # por el índice (0 a N)
Variables de la plantilla Sí, si la plantilla tiene variables Un campo para cada variable, con su nombre exacto, en la raíz del JSON (ver abajo)

Sobre las variables dinámicas

Cada variable de la plantilla se convierte en un campo en la raíz del JSON, junto a inbox_id, phone_number y template_name, con el nombre exacto de la variable:

  • Plantilla con variables con nombre, como Hola {{cliente}}, tu factura de {{monto}} vence mañana: envía los campos "cliente" y "monto".

  • Plantilla con variables numeradas, como Hola {{1}}, tu factura de {{2}} vence mañana: envía los campos "1" y "2".

Si falta alguna variable, la API rechaza la solicitud con el error missing params. Los campos que no corresponden a ninguna variable se ignoran. Los nombres de variable con punto o tilde (como {{contact.name}} o {{horário}}) no son aceptados por Meta como variable.

Ejemplo de solicitud

curl --location 'https://cloudchat.cloudhumans.com/api/v1/accounts/ACCOUNT_ID/conversations/create_proactive_whatsapp_conversation' \
  --header 'content-type: application/json' \
  --header 'api_access_token: ACCESS_TOKEN' \
  --data '{
    "inbox_id": "INBOX_ID",
    "phone_number": "+5511999998888",
    "template_name": "recordatorio_pago",
    "labels": ["campana-x", "vip"],
    "header_attachment": "ATTACHMENT_URL",
    "button_param_0": "BUTTON PARAMETER",
    "button_param_1": "ANOTHER BUTTON PARAMETER",
    "cliente": "Juan",
    "monto": "$120.00"
  }'

Dónde encontrar los parámetros

  • account_id — en el panel administrativo de la cuenta

  • inbox_id — ID de la bandeja de entrada configurada (https://cloudchat.cloudhumans.com/app/accounts/{account_id}/settings/inboxes/{inbox_id})

  • api_access_token — genéralo en el panel de configuración de API

  • Variables dinámicas — consulta la configuración de la plantilla en el panel administrativo. Estos parámetros van en la raíz del payload.

Asegúrate de que el número de teléfono esté en formato E.164, con el código de país.

Aplicando etiquetas (labels) a la conversación creada

El parámetro opcional labels recibe un array de strings con los títulos de las etiquetas a aplicar a la conversación creada por el disparo — sin necesidad de una segunda llamada a la API de labels.

"labels": ["campana-x", "vip"]

Comportamiento:

  • Los títulos se normalizan: se eliminan los espacios en los extremos, se convierten a minúsculas y se deduplican.

  • Las etiquetas se agregan a la conversación (nunca reemplazan etiquetas existentes) — en bandejas con conversación única, las etiquetas de disparos anteriores y las aplicadas por agentes se preservan.

  • Si la etiqueta todavía no existe en la cuenta, se crea automáticamente (y comienza a aparecer en los filtros del panel) — siempre que el token utilizado sea de un administrador o CX Engineer. Con token de agente (no admin), solo se aplican etiquetas ya existentes en la cuenta; los títulos nuevos se ignoran silenciosamente.

  • Omitir el parámetro (o enviar un array vacío) mantiene el comportamiento anterior — no se aplica ninguna etiqueta.

Límite de solicitudes (rate limit)

Este endpoint acepta como máximo 200 solicitudes por minuto.

Por encima de ese límite, la API responde HTTP 429 y la solicitud no se procesa (el mensaje no se envía). La respuesta incluye los siguientes headers:

Header Descripción
Retry-After Segundos hasta que la ventana permita nuevas solicitudes
X-RateLimit-Limit Límite de solicitudes de la ventana (200)
X-RateLimit-Remaining Solicitudes restantes en la ventana actual

Ejemplo de respuesta al exceder el límite:

{
  "error": "Rate limit exceeded. Retry later.",
  "retry_after": 42
}

Si tu integración dispara mensajes en lote, maneja la respuesta 429 reenviando la solicitud después del tiempo indicado en Retry-After. Sin este manejo, los envíos que excedan el límite se perderán.

Observaciones