Mensajes
Resumen para integración
- Endpoint:
POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging- Token: de mensajería, en el encabezado
Authorization: Bearer {{wa-msg-api-token}}(cómo generarlo)- Campos comunes:
from,to(teléfono o BSUID) ytype(detalle)- Campo de activación:
categorycon el valor"utility"- Respuesta: la misma para todos los mensajes (ver respuesta)
Los mensajes que puedes enviar con Direct Send, con sus campos y ejemplos. Todos se envían con POST /v1/messaging agregando el campo category.
Estructura general
Campos además de los campos comunes:
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| text | Texto del mensaje. | String |
|
| category | Categoría de activación de Direct Send. Valor válido: utility. Enviar service se considera fuera de Direct Send y sigue el comportamiento de envío existente. | String |
|
| ttl_seconds | Permite configurar el TTL; se agrega debajo del campo category. Para utility:
| String | Opcional. |
| direct_send_config | Objeto para atribuir los mensajes a un template con nombre explícito. | Objeto | Opcional. |
Mensaje de texto
Envía un mensaje de texto de Direct Send. El campo type debe ser "text" y category debe ser "utility".
Ejemplo
Petición HTTP
curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \-H 'Authorization: Bearer {{wa-msg-api-token}}' \-H 'Content-Type: application/json' \-d '{"from": "5215500000001","to": "5215500000002","type": "text","text": "Tu pedido ya está en camino.","category": "utility"}'
Atribución de template
Por defecto, Direct Send hace matching automático del mensaje contra las plantillas existentes o crea una nueva con un nombre generado por Meta. Si se necesita que todos los mensajes de un mismo flujo se atribuyan siempre al mismo template, se puede fijar un nombre explícito en el objeto direct_send_config.
Cuerpo
| Nombre | Descripción | Tipo | Requerimientos |
|---|---|---|---|
| template_name | Nombre explícito del template a crear o reutilizar. Único por WABA. Solo es válido junto con category: "utility". | String |
|
Ejemplo
Petición HTTP
curl -X POST 'https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging' \-H 'Authorization: Bearer {{wa-msg-api-token}}' \-H 'Content-Type: application/json' \-d '{"from": "5215500000001","to": "5215500000002","type": "text","text": "Tu pedido TC01-9988 está en camino.","category": "utility","direct_send_config": { "template_name": "orden_en_camino_v1" }}'
Botones combinados (CTA URL + respuesta)
Un mismo mensaje interactivo puede combinar botones de URL (cta_url) y de respuesta (reply), definidos en el arreglo buttons del objeto replyButtons. El campo type debe ser "interactive" y category debe ser "utility". Consulta Botones de respuesta para el objeto completo.
- Hasta 10 botones en total.
- Máximo 2 botones de tipo
cta_url. - Los botones
cta_urldeben ir antes que losreplyen el arreglo.
Ejemplo
Body
{"from": "5215500000001","to": "5215500000002","type": "interactive","category": "utility","direct_send_config": {"template_name": "orden_actualizacion_btns"},"replyButtons": {"body": "Elige una opción","buttons": [{ "type": "cta_url", "title": "Visitar sitio", "url": "https://www.conceptomovil.com" },{ "type": "reply", "id": "btn_1", "title": "Opción 1" },{ "type": "reply", "id": "btn_2", "title": "Opción 2" }]}}
Botón de llamada de voz
El botón de llamada de voz de WhatsApp ("Llamada en WhatsApp") permite a un usuario tocar para iniciar una llamada de voz de WhatsApp al número de teléfono del negocio. Se envía como un mensaje interactivo de formato libre con la etiqueta category: "utility" de nivel superior y un solo botón de llamada, definido en el objeto voice_call. Consulta Botón de llamada (llamada de voz) para el objeto completo.
Nota: para usar esta función el número debe tener habilitado WhatsApp Calling en WhatsApp Manager; de lo contrario, Meta responde el error 138000 ("Calling API not enabled") aunque el JSON sea correcto.
Ejemplo
Body
{"from": "5215500000001","to": "5215500000002","type": "interactive","category": "utility","direct_send_config": {"template_name": "confirmacion_pedido_llamada"},"voice_call": {"body": "Te llamaremos para confirmar tu pedido","action": {"parameters": {"display_text": "Llamar ahora","ttl_minutes": 60}}}}
Cuenta sin Direct Send habilitado
Si la WABA no tiene Direct Send habilitado, el mensaje falla y se envía la siguiente notificación al webhook:
{"statuses": [{"id": "","recipient_id": "5512345678","status": "failed","timestamp": "...","errors": [{"code": 100,"title": "Internal error, please retry. If the problem persist, please contact support","details": "(#100) Invalid parameter.Parameter Invalid: The 'category' value requires Direct Send, which isn't enabled for this account. Use an approved message template instead."}]}]}
Los códigos de error propios de Direct Send (1148 a 1151) y el resto de los códigos de la API se encuentran en Códigos de Error.
