logo
enes

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) y type (detalle)
  • Campo de activación: category con 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:

NombreDescripciónTipoRequerimientos
textTexto del mensaje.String
  • Obligatorio.
  • La longitud máxima es de 1,024 caracteres.
categoryCategorí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
  • Obligatorio para usar Direct Send API.
  • Si se omite, se trata como un envío normal de mensaje.
ttl_secondsPermite configurar el TTL; se agrega debajo del campo category. Para utility:
  • 30 días predeterminados.
  • Mínimo 30 segundos.
  • Máximo 43,200 segundos (12 horas).
StringOpcional.
direct_send_configObjeto para atribuir los mensajes a un template con nombre explícito.ObjetoOpcional.

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

NombreDescripciónTipoRequerimientos
template_nameNombre explícito del template a crear o reutilizar. Único por WABA. Solo es válido junto con category: "utility".String
  • Opcional.
  • Solo minúsculas, números y guión bajo (^[a-z0-9_]{1,512}$).

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_url deben ir antes que los reply en 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.

WhatsApp — Anterior
Envío Directo
Siguiente — WhatsApp
Uso indebido de la API