API - Enviar Mensaje Proactiva por WhatsApp

Este artículo es la referencia rápida del endpoint de WhatsApp. La guía completa, con Web Widget y etiquetas, está en Disparar mensaje proactivo por API (WhatsApp y Web Widget).

Descripción

Este endpoint permite crear una conversación proactiva por WhatsApp utilizando una plantilla previamente configurada. Los parámetros de la plantilla son dinámicos y pueden variar según la configuración de la plantilla utilizada.

Endpoint

URL:

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

Headers:

• content-type: application/json

• api_access_token: Clave de acceso de la API.

Parámetros

Parámetro en la Ruta

account_id

• Tipo: String

• Obligatorio: Sí

• Descripción: ID de la cuenta en el sistema.

Parámetros en el Cuerpo

1. inbox_id

   • Tipo: String

   • Obligatorio: Sí

   • Descripción: ID de la bandeja de entrada a la que se enviará el mensaje.

2. phone_number

   • Tipo: String

   • Obligatorio: Sí

   • Descripción: Número de teléfono del destinatario, incluyendo el código del país.

3. template_name

   • Tipo: String

   • Obligatorio: Sí

   • Descripción: Nombre de la plantilla configurada en el sistema.

4. Parámetros Dinámicos de la Plantilla

   • Tipo: Variados

   • Obligatorio: Sí, si la plantilla tiene variables (todas son obligatorias)

   • Descripción: Un campo para cada variable de la plantilla, con su nombre exacto (ver abajo).

5. labels

   • Tipo: Array de strings

   • Obligatorio: No

   • Descripción: Títulos de las etiquetas a aplicar en la conversación creada. Detalles en la guía completa.

Sobre los Parámetros Dinámicos

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íe los campos "cliente" y "monto".

• Plantilla con variables numeradas, como Hola {{1}}, tu factura de {{2}} vence mañana: envíe 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": "+5215512345678",
  "template_name": "recordatorio_pago",
  "cliente": "Juan",
  "monto": "$120.00"
}'

Notas

1. account_id: El account_id se puede encontrar en el panel administrativo de la cuenta.

2. inbox_id: El inbox_id corresponde al ID de la bandeja de entrada configurada para recibir mensajes.

3. api_access_token: Genera el token en el panel de configuración de API.
   

4. Parámetros Dinámicos de la Plantilla: Consulte la configuración de su plantilla en el panel administrativo para identificar las variables disponibles y obligatorias. Estos parámetros deben enviarse directamente en la raíz del payload.

Importante: Asegúrese de que el número de teléfono esté en formato internacional (E.164), incluyendo el código del país.

Límite de solicitudes

Este endpoint 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 que se libere). Espere ese tiempo antes de reenviar y, en lotes grandes, distribuya los envíos a lo largo de los minutos. Una solicitud que recibió 429 no fue procesada, así que reenviarla no duplica el mensaje. El cuerpo de la respuesta y los demás encabezados están en la sección de límite de Cómo enviar un mensaje proactivo por WhatsApp vía API.

Campañas vía API

Para enviar a una lista de contactos, use la creación de campañas de la API pública (api.cloudhumans.com), disponible también en el MCP de Cloud Humans:

• La audiencia se define por etiqueta: la campaña va a los contactos que tienen la etiqueta.

• Antes de crearla, la API pide confirmar cuántos contactos la van a recibir.

• El envío sale por el programador de campañas, en pocos minutos o en el horario programado.

• La autenticación es por inicio de sesión de usuario (token Bearer), no por el api_access_token de este endpoint.

Referencia: Crear una campaña. El endpoint de esta página sigue siendo el camino para el envío uno a uno; para enviar en volumen a través de él, respete el límite de 200 solicitudes por minuto.