Enviar mensajes
Un solo endpoint que cubre toda la superficie de la Cloud API.
POST /api/v1/messagesUn envío siempre lleva tres cosas: la conexión desde la que se envía, el destinatario y exactamente un campo de contenido.
{
"connectionId": "cnx_...",
"to": "+237699001122",
"text": "Hello 👋"
}El número va en formato internacional. Obtén connectionId con GET /api/v1/connections. Agrega
replyTo con el wamid de un mensaje entrante para citarlo en tu respuesta.
Campos de contenido
Un campo a la vez
Enviar dos campos de contenido en la misma solicitud no envía dos mensajes: solo se usa el primero que se reconoce. Haz dos llamadas.
Texto y multimedia
| Campo | Contenido | Límites |
|---|---|---|
text | Una cadena, o { body, previewUrl } | 4096 caracteres |
image | JPEG, PNG | 5 MB, pie de foto de 1024 caracteres |
video | MP4, 3GPP (H.264 + AAC) | 16 MB |
audio | AAC, AMR, MP3, M4A, OGG | 16 MB, sin pie de foto |
document | PDF, DOC(X), XLS(X), PPT(X), TXT | 100 MB |
sticker | WebP estático o animado | 100 KB / 500 KB |
Ubicación, contactos, reacción
| Campo | Contenido |
|---|---|
location | { latitude, longitude, name, address } |
locationRequest | { body } — muestra un botón "Enviar ubicación" |
contacts | Un arreglo de tarjetas de contacto |
reaction | { messageId, emoji } — una cadena vacía elimina la reacción |
Mensajes interactivos
{
"connectionId": "cnx_...",
"to": "+237699001122",
"buttons": {
"body": "How can we help?",
"footer": "Genuka",
"buttons": [
{ "id": "order", "title": "My order" },
{ "id": "support", "title": "A problem" }
]
}
}| Campo | Descripción | Límites |
|---|---|---|
buttons | Botones de respuesta rápida | 3 como máximo, títulos de 20 caracteres |
list | Secciones y filas | 10 secciones, 10 filas en total |
cta | Un único botón que lleva una URL | url + displayText |
La respuesta del usuario llega por webhook, con el id del botón o de la fila que eligió.
Plantillas
Fuera de la ventana de 24 horas, solo se entregará una plantilla aprobada.
{
"connectionId": "cnx_...",
"to": "+237699001122",
"template": {
"name": "order_confirmation",
"language": "en",
"body": ["Awa", "ORD-1042"]
}
}Un envío de plantilla abre una conversación facturable de Meta en la propia WABA del cliente: Meta le factura directamente al cliente. Los mensajes de servicio enviados dentro de la ventana de 24 horas son gratuitos.
Crea y sigue tus plantillas mediante /api/v1/templates. Una plantilla en estado PAUSED o
REJECTED no se puede usar: verifica su estado antes de lanzar una campaña.
Vía de escape
Si un tipo de mensaje aún no está expuesto, raw reenvía un fragmento de la Cloud API tal cual:
{
"connectionId": "cnx_...",
"to": "+237699001122",
"raw": { "type": "interactive", "interactive": { "type": "flow" } }
}No se aplica ninguna validación a raw: los errores vuelven de Meta tal como llegan.
Errores comunes
| Código de Meta | Significado | Qué hacer |
|---|---|---|
131047 | Han pasado más de 24 h desde el último mensaje entrante | Envía una plantilla |
131026 | Destinatario inaccesible o sin WhatsApp | No reintentes |
131050 | El usuario se dio de baja del marketing | No vuelvas a enviarle marketing nunca |
131049 | Se alcanzó el límite de marketing por usuario | Reintenta más tarde |
132001 | Plantilla inexistente o no aprobada en ese idioma | Verifica el nombre y el idioma |
130429 | Se superó el ritmo de envío | Reduce la velocidad, reintenta con backoff |