Quickstart
Esta guía rápida te lleva paso a paso por el envío de un mensaje, la lectura de la respuesta de la API y la confirmación de la entrega mediante un callback del webhook.
Antes de comenzar
Asegúrate de tener todo lo siguiente:
- Hosts, credenciales y acceso por IP habilitados por Operaciones. Las peticiones desde IPs que no están en la lista de acceso son rechazadas. Consulta Información general.
- Un remitente de negocio y una WABA (WhatsApp Business Account) asignados, incluido el phone number ID del remitente.
- Un destinatario de prueba controlado, es decir, un número de WhatsApp de tu propiedad que haya aceptado (opt-in) recibir mensajes de tu negocio.
- Una plantilla aprobada, o una ventana de servicio abierta con el destinatario de prueba (ver abajo).
- Un webhook registrado que pueda recibir callbacks de estatus. Sin él no puedes confirmar la entrega. Consulta Webhook.
Elige el tipo de mensaje
El mensaje que puedes enviar depende de si el cliente te escribió recientemente:
- El cliente te escribió o te llamó en las últimas 24 horas (la ventana de servicio está abierta): puedes enviar un mensaje libre (mensaje de servicio), como texto, multimedia o contenido interactivo. Consulta Mensajes sin plantilla.
- En cualquier otro caso: debes enviar una plantilla aprobada. Esto incluye el primer mensaje a un cliente nuevo. Consulta Mensajes con plantilla y Crear plantilla.
Si no estás seguro de que la ventana esté abierta, envía una plantilla. Las plantillas son válidas tanto dentro como fuera de la ventana. Un mensaje libre enviado fuera de la ventana falla con el error 470.
Paso 1: Envía el mensaje
Todos los mensajes se envían con POST /v1/messaging y el token de mensajería (cómo generarlo). Este ejemplo envía una plantilla aprobada:
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": "template","template":{"language": "es","name": "body_text","components":[{"type":"body","parameters":[{"type":"text","text":"123456"}]}]}}'
Si la ventana de servicio está abierta, puedes enviar texto libre reemplazando los campos type y template por "type": "text" y un campo text:
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": "~Texto tachado~ \n _Texto en cursivas_ \n *Texto en negritas* \n Emojis 😋"}'
Paso 2: Lee la respuesta
Una petición exitosa responde HTTP 200 con un ID de mensaje:
[{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i"}]
Guarda el id: es la única forma de relacionar los callbacks de estatus de este mensaje.
HTTP 200 significa que la plataforma aceptó la petición, no que el mensaje se haya entregado. La entrega solo se confirma con el callback de estatus delivered (paso 3). Los errores que se devuelven en este punto (400, 401, 500) se describen en Respuesta.
Paso 3: Relaciona el callback de estatus
Tu webhook recibe callbacks de estatus con el mismo ID de mensaje. El estatus avanza por sent → delivered → read, o termina en failed. Los callbacks pueden llegar desordenados, así que relaciónalos por id, no por orden de llegada.
Todos los campos se describen en Notificaciones de estatus.
sent
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "sent","timestamp": "1693419170","recipient_id": "5215500000002","conversation":{"id": "05b0852529d1652f2ccf3cde096f2150","origin":{"type": "utility"}},"pricing":{"billable": true,"pricing_model": "CBP","category": "utility"}}]}
delivered
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "delivered","timestamp": "1693419173","recipient_id": "5215500000002","conversation":{"id": "05b0852529d1652f2ccf3cde096f2150","origin":{"type": "utility"}},"pricing":{"billable": true,"pricing_model": "CBP","category": "utility"}}]}
read
{"statuses": [{"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","status": "read","timestamp": "1693419180","recipient_id": "5215500000002"}]}
failed
Por ejemplo, un mensaje libre enviado fuera de la ventana de servicio:
{"statuses": [{"errors": [{"code": 470,"title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."}],"id": "gBGHUhVUByKUHwIJCSIVo3YWvs8i","recipient_id": "5215500000002","status": "failed","timestamp": "1693419173"}]}
Cuando el estatus es failed, busca errors[].code en Códigos de error.
