WhatsApp APIAPI
WhatsApp: enviar templates pela API
Liste os templates aprovados de cada número e envie um template de WhatsApp pela API da XBASE, a qualquer hora, com exemplos e erros.
Atualizado em
Template é a mensagem aprovada pela Meta que pode ser enviada a qualquer hora, inclusive para quem nunca falou com a empresa ou fora da janela de 24 horas. Os templates são criados e aprovados em WhatsApp API → Templates.
Listar os templates
GET https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId é opcional: sem ele, vêm os templates de todos os números do workspace. Com ele, vêm os templates do número e os que não estão ligados a nenhum número.
curl "https://api.xbase.app/api/external/v1/whatsapp/templates?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Resposta 200:
[
{
"id": "0f4c8e2a-1b3d-4e5f-8a9b-7c6d5e4f3a2b",
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"name": "pedido_entregue",
"language": "pt_BR",
"category": "UTILITY",
"status": "APPROVED",
"body": "Olá {{1}}, o seu pedido {{2}} foi entregue em {{3}}.",
"paramsCount": 3,
"headerFormat": null
}
]| Campo | Tipo | Descrição |
|---|---|---|
id | texto | Id do template. Pode ir em template.id no envio |
numberId | texto ou null | Número dono do template: o template só sai por ele. null: o template não está ligado a um número e sai pelo número escolhido no envio |
name | texto | Nome do template na Meta |
language | texto ou null | Idioma, como pt_BR |
category | texto ou null | MARKETING, UTILITY ou AUTHENTICATION |
status | texto | Situação na Meta. Só APPROVED pode ser enviado |
body | texto ou null | Texto com as variáveis {{1}}, {{2}}… |
paramsCount | número | Quantas variáveis o texto tem: o tamanho de template.params |
headerFormat | texto ou null | Cabeçalho do template. IMAGE, VIDEO e DOCUMENT pedem template.headerMediaUrl no envio |
Enviar um template
POST https://api.xbase.app/api/external/v1/whatsapp/templates| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
numberId | texto | sim | Número que envia (listar os números) |
to | texto | sim | Telefone do contato com DDI, 8 a 15 dígitos. +, espaços, hífens e parênteses são removidos |
template.name | texto | um dos dois | Nome do template, como na lista |
template.id | texto | um dos dois | Id do template, como na lista |
template.language | texto | não | Idioma do template, como pt_BR (o padrão). Só com template.name |
template.params | lista de textos | não | Valores de {{1}}, {{2}}…, na ordem. Até 30, cada um com até 1.024 caracteres |
template.headerMediaUrl | texto | com cabeçalho de mídia | URL https pública da imagem, do vídeo ou do documento do cabeçalho |
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": "5521999990000",
"template": {
"name": "pedido_entregue",
"language": "pt_BR",
"params": ["Maria", "12345", "04/11 às 14:28"]
}
}'Resposta 200:
{
"status": "accepted",
"messageId": "wamid.HBgNNTUyMTk5OTk5MDAwMBUCABEYEjQ1QzM1RkQ2RDhGNjZBMDQ3MwA=",
"threadId": "c1d7f0b2-5a4e-4f3d-9c2b-1a0e9d8c7b6a",
"dialogId": "5a0e4c31-7b2d-4e8f-a1c3-9d6b5e4f3a21"
}| Campo | Descrição |
|---|---|
status | accepted: a Meta aceitou o envio. A entrega ao celular vem depois, nos eventos de webhook |
messageId | Id da mensagem na Meta (wamid.…), o mesmo dos eventos de entrega e leitura |
threadId | Conversa do contato na XBASE |
dialogId | Mensagem na conversa |
Regras dos parâmetros
- Mande os parâmetros como texto, na ordem das variáveis e na quantidade de
paramsCount. Com a quantidade errada, a resposta é 422SEND_REJECTED, dizendo quantas variáveis o template espera. - Template com variáveis ligadas a dados da conversa (configuradas em WhatsApp API → Templates) pode ir sem
params: a XBASE preenche com os dados do contato e da conversa. - A Meta recusa parâmetro com quebra de linha, tabulação ou mais de 4 espaços seguidos (422
META_ERROR).
O que acontece depois do envio
- A XBASE cria o contato, se ele ainda não existir, abre ou reaproveita a conversa dele com o número e grava o template enviado.
- A mensagem aparece no Chatcenter. A entrega e a leitura chegam pelos webhooks do workspace.
- Quando o contato responde, a janela de 24 horas abre e você pode mandar mensagens livres.
- A API não evita envio duplicado: repetir a mesma chamada manda o template de novo.
Erros do envio
| Status | code | Quando |
|---|---|---|
| 400 | (sem code) | Campo inválido. A message diz qual, como to: telefone inválido |
| 404 | NUMBER_NOT_FOUND | O número não existe neste workspace |
| 404 | TEMPLATE_NOT_FOUND | O template não existe para este número: confira o nome, o idioma e o numberId |
| 422 | NUMBER_DISCONNECTED | O número está desconectado |
| 422 | SEND_REJECTED | A XBASE recusou antes de enviar: variáveis faltando ou a mais, ou falta a mídia do cabeçalho. A message diz o motivo |
| 422 | META_ERROR | A Meta recusou, por exemplo, template pausado ou não aprovado. details.metaCode traz o código da Meta |
Veja o formato completo em Erros.