WhatsApp: enviar templates pela API
Liste os números e os templates do workspace e envie templates aprovados de WhatsApp pela API da XBASE, com exemplos de requisição, resposta e erros.
Atualizado em
Com o escopo Enviar templates de WhatsApp (whatsapp:send), a API lista os números e os templates do workspace e envia templates aprovados para qualquer contato. Cada envio aparece no Chatcenter, na conversa do contato.
Quais números enviam pela API
Hoje a API envia pelos números de WhatsApp conectados por app da Gupshup: são os que aparecem em WhatsApp API → Números com o nome do app (por exemplo, MINHAEMPRESA). Números conectados direto pela Meta, inclusive o WhatsApp Business do celular, ainda não enviam por esta rota.
Listar os números
GET https://api.xbase.app/api/external/v1/whatsapp/numberscurl https://api.xbase.app/api/external/v1/whatsapp/numbers \
-H "Authorization: Bearer $XBASE_API_KEY"Resposta 200:
[
{
"appName": "MINHAEMPRESA",
"source": "5511999990000",
"name": "Atendimento",
"status": "ACTIVE"
}
]| Campo | Tipo | Descrição |
|---|---|---|
appName | texto | Nome do app. Vai em appName no envio |
source | texto | Número que envia, só dígitos, com DDI |
name | texto ou null | Nome da conexão na XBASE |
status | texto | ACTIVE, PENDING, INACTIVE, ERROR ou CONNECTING |
Listar os templates
GET https://api.xbase.app/api/external/v1/whatsapp/templates?appName=MINHAEMPRESAappName é opcional: sem ele, vêm os templates de todos os números do workspace.
Resposta 200:
[
{
"id": "2a57b53e-83f5-4122-a01f-1ed490bf6f9a",
"name": "pedido_entregue",
"appName": "MINHAEMPRESA",
"category": "UTILITY",
"language": "pt_BR",
"status": "APPROVED",
"body": "Olá {{1}}, o seu pedido {{2}} foi entregue em {{3}}.",
"paramsCount": 3
}
]| Campo | Tipo | Descrição |
|---|---|---|
id | texto | Id do template na Gupshup. Vai em template.id no envio |
name | texto | Nome do template na XBASE |
appName | texto ou null | App do número dono do template |
category | texto ou null | MARKETING, UTILITY ou AUTHENTICATION |
language | texto ou null | Idioma, como pt_BR |
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 |
A lista traz os templates de WhatsApp API → Templates que já têm id na Gupshup.
Enviar um template
POST https://api.xbase.app/api/external/v1/whatsapp/templates| Campo | Tipo | Obrigatório | Regra |
|---|---|---|---|
appName | texto | sim | App do número que envia (listar os números) |
destination | texto | sim | Telefone do contato com DDI, 8 a 15 dígitos. +, espaços, hífens e parênteses são removidos |
template.id | texto | sim | Id do template (listar os templates) |
template.params | lista de textos | não | Valores de {{1}}, {{2}}…, na ordem. Até 30, cada um com até 1.024 caracteres |
source | texto | não | Número que envia. Se vier, tem de ser o número do app |
message | objeto | não | Imagem do cabeçalho, quando o template tem: { "type": "image", "image": { "link": "https://…" } } |
metadata | objeto | não | Até 8 KB de dados seus (ids do seu sistema). Fica gravado na mensagem, na XBASE |
curl -X POST https://api.xbase.app/api/external/v1/whatsapp/templates \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"appName": "MINHAEMPRESA",
"destination": "5521999990000",
"template": {
"id": "2a57b53e-83f5-4122-a01f-1ed490bf6f9a",
"params": ["Maria", "12345", "04/11 às 14:28"]
},
"metadata": { "pedido": "12345" }
}'Resposta 200:
{
"status": "submitted",
"messageId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
"threadId": "c1d7f0b2-…",
"dialogId": "5a0e4c31-…"
}| Campo | Descrição |
|---|---|
status | submitted: a Gupshup aceitou o envio. A entrega ao celular vem depois |
messageId | Id da mensagem na Gupshup, o mesmo dos eventos de entrega e leitura |
threadId | Conversa do contato na XBASE |
dialogId | Mensagem na conversa |
Em casos raros, a mensagem sai mas o registro na XBASE falha: a resposta continua 200, com threadId e dialogId null. Não reenvie nesse caso, porque o contato já recebeu.
Regras dos parâmetros
- Quebras de linha, tabulações e espaços repetidos viram um espaço só, porque a Meta recusa parâmetros com eles.
- Se o texto do template mais os parâmetros passar de 1.024 caracteres, a XBASE encurta o parâmetro mais longo e termina com "…".
- Mande os parâmetros como texto, na ordem das variáveis.
O que acontece depois do envio
- A XBASE cria o contato, se ele ainda não existir, abre ou reaproveita a conversa e grava o template enviado.
- A mensagem aparece no Chatcenter, e os eventos de entrega e leitura chegam em WhatsApp API → Eventos.
- 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 destination: telefone inválido |
| 400 | SOURCE_MISMATCH | source não é o número do app |
| 404 | CONNECTION_NOT_FOUND | O app não existe neste workspace |
| 422 | CONNECTION_NOT_CONFIGURED | O número está sem número de origem ou sem a credencial da Gupshup. Fale com o suporte |
| 422 | GUPSHUP_ERROR | A Gupshup recusou o envio. A message traz o motivo e details.gupshupCode, o código dela |
Veja o formato completo em Erros.
Integrações antigas
Integrações criadas antes desta API chamam POST https://api.xbase.app/api/actions/waba/send/template, com app_name, source, destination, template e metadata. Essa rota continua aceita, com o mesmo corpo e a mesma resposta ({ "status", "messageId" }), e faz o mesmo envio. Integrações novas devem usar POST /whatsapp/templates.
Perguntas frequentes
Veja também
Autenticação: chaves de API
Como criar uma chave de API da XBASE, escolher os escopos, mandar a chave nas requisições, conferir com GET /me e revogar.
Instagram: contas, comentários e DMs
Liste as contas do Instagram, responda e oculte comentários e mande DMs pela API da XBASE, com exemplos de requisição e resposta.