WhatsApp APIAPI
WhatsApp: enviar plantillas por la API
Lista las plantillas aprobadas de cada número y envía una plantilla de WhatsApp por la API de XBASE, a cualquier hora, con ejemplos y errores.
Actualizado el
Una plantilla es el mensaje aprobado por Meta que se puede enviar a cualquier hora, incluso a quien nunca habló con la empresa o fuera de la ventana de 24 horas. Las plantillas se crean y se aprueban en WhatsApp API → Plantillas.
Listar las plantillas
GET https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId es opcional: sin él, vienen las plantillas de todos los números del workspace. Con él, vienen las plantillas del número y las que no están ligadas a ningún número.
curl "https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Respuesta 200:
[
{
"id": "0f4c8e2a-1b3d-4e5f-8a9b-7c6d5e4f3a2b",
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"name": "pedido_entregado",
"language": "es",
"category": "UTILITY",
"status": "APPROVED",
"body": "Hola {{1}}, tu pedido {{2}} se entregó el {{3}}.",
"paramsCount": 3,
"headerFormat": null
}
]| Campo | Tipo | Descripción |
|---|---|---|
id | texto | Id de la plantilla. Puede ir en template.id en el envío |
numberId | texto o null | Número dueño de la plantilla: la plantilla solo sale por él. null: la plantilla no está ligada a un número y sale por el número elegido en el envío |
name | texto | Nombre de la plantilla en Meta |
language | texto o null | Idioma, como es |
category | texto o null | MARKETING, UTILITY o AUTHENTICATION |
status | texto | Situación en Meta. Solo APPROVED se puede enviar |
body | texto o null | Texto con las variables {{1}}, {{2}}… |
paramsCount | número | Cuántas variables tiene el texto: el tamaño de template.params |
headerFormat | texto o null | Encabezado de la plantilla. IMAGE, VIDEO y DOCUMENT piden template.headerMediaUrl en el envío |
Enviar una plantilla
POST https://api.xbase.app/api/external/v1/whatsapp/templates| Campo | Tipo | Obligatorio | Regla |
|---|---|---|---|
numberId | texto | sí | Número que envía (listar los números) |
to | texto | sí | Teléfono del contacto con el código de país, de 8 a 15 dígitos. Se quitan +, espacios, guiones y paréntesis |
template.name | texto | uno de los dos | Nombre de la plantilla, como en la lista |
template.id | texto | uno de los dos | Id de la plantilla, como en la lista |
template.language | texto | no | Idioma de la plantilla, como pt_BR (el predeterminado). Solo con template.name |
template.params | lista de textos | no | Valores de {{1}}, {{2}}…, en orden. Hasta 30, cada uno con hasta 1024 caracteres |
template.headerMediaUrl | texto | con encabezado multimedia | URL https pública de la imagen, el video o el documento del encabezado |
curl -X POST https://api.xbase.app/api/external/v1/whatsapp/templates \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"to": "5491155550100",
"template": {
"name": "pedido_entregado",
"language": "es",
"params": ["María", "12345", "04/11 a las 14:28"]
}
}'Respuesta 200:
{
"status": "accepted",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABEYEjQ1QzM1RkQ2RDhGNjZBMDQ3MwA=",
"threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
"dialogId": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21"
}| Campo | Descripción |
|---|---|
status | accepted: Meta aceptó el envío. La entrega al celular llega después, en los eventos de webhook |
messageId | Id del mensaje en Meta (wamid.…), el mismo de los eventos de entrega y lectura |
threadId | Conversación del contacto en XBASE |
dialogId | Mensaje en la conversación |
Reglas de los parámetros
- Envía los parámetros como texto, en el orden de las variables y en la cantidad de
paramsCount. Con la cantidad equivocada, la respuesta es 422SEND_REJECTED, diciendo cuántas variables espera la plantilla. - Una plantilla con variables ligadas a datos de la conversación (configuradas en WhatsApp API → Plantillas) puede ir sin
params: XBASE las completa con los datos del contacto y de la conversación. - Meta rechaza un parámetro con salto de línea, tabulación o más de 4 espacios seguidos (422
META_ERROR).
Qué pasa después del envío
- XBASE crea el contacto si todavía no existe, abre o reutiliza su conversación con el número y guarda la plantilla enviada.
- El mensaje aparece en el Chatcenter. La entrega y la lectura llegan por los webhooks del workspace.
- Cuando el contacto responde, se abre la ventana de 24 horas y puedes enviar mensajes libres.
- La API no evita envíos duplicados: repetir la misma llamada envía la plantilla de nuevo.
Errores del envío
| Estado | code | Cuándo |
|---|---|---|
| 400 | (sin code) | Campo inválido. El message dice cuál, como to: telefone inválido |
| 404 | NUMBER_NOT_FOUND | El número no existe en este workspace |
| 404 | TEMPLATE_NOT_FOUND | La plantilla no existe para este número: revisa el nombre, el idioma y el numberId |
| 422 | NUMBER_DISCONNECTED | El número está desconectado |
| 422 | SEND_REJECTED | XBASE rechazó antes de enviar: faltan variables o sobran, o falta el archivo del encabezado. El message dice el motivo |
| 422 | META_ERROR | Meta rechazó, por ejemplo, una plantilla pausada o no aprobada. details.metaCode trae el código de Meta |
Mira el formato completo en Errores.