Autenticação
Crie um Aplicativo no painel (Aplicativos e API). Cada aplicativo é ligado a um número e tem uma appKey e uma authKey. Envie as duas nos cabeçalhos (ou no corpo):
appKey: 1cfd71ac-....
authKey: mqwdbO5ljx....
A authKey também pode ser a chave da conta (Perfil → Chave de autenticação), útil nos endpoints de leitura e no multicanal.
Números: só dígitos com código do país (5511999999999). Números brasileiros sem o 55 são corrigidos automaticamente; o 9º dígito é ajustado conforme o cadastro no WhatsApp.
Endpoints
POST /api/v2/sendText
Envia uma mensagem de texto.
{
"to": "5511999999999",
"message": "Olá! 👋",
"queue": false,
"delay": 0
}POST /api/v2/sendImage
Envia imagem por link público.
{
"to": "5511999999999",
"file": "https://exemplo.com/foto.jpg",
"message": "Legenda opcional"
}POST /api/v2/sendVideo
Envia vídeo por link público.
{
"to": "5511999999999",
"file": "https://exemplo.com/video.mp4",
"message": "Legenda"
}POST /api/v2/sendVoice
Envia áudio como mensagem de voz (OGG/Opus).
{
"to": "5511999999999",
"file": "https://exemplo.com/audio.ogg"
}POST /api/v2/sendDocument
Envia documento (PDF etc.).
{
"to": "5511999999999",
"file": "https://exemplo.com/boleto.pdf",
"fileName": "boleto.pdf",
"message": "Seu boleto"
}POST /api/v2/sendContact
Envia um cartão de contato.
{
"to": "5511999999999",
"contactName": "Suporte",
"contactNumber": "5511988887777"
}POST /api/v2/sendTemplate
Envia um modelo salvo (com mídia). Aceita variáveis para {{campos}}.
{
"to": "5511999999999",
"templateId": 12,
"variables": {
"nome": "Ana"
}
}POST /api/v2/sendReply
Dispara uma resposta do chatbot (sequência, lista ou botões).
{
"to": "5511999999999",
"replyId": 34
}POST /api/v2/messages
Envio multicanal numa chamada (WhatsApp, Telegram, SMS, e-mail). Só authKey da conta no topo.
{
"authKey": "CHAVE_DA_CONTA",
"message": "Seu pedido foi enviado",
"channels": {
"whatsapp": {
"appKey": "APP_KEY",
"to": "5511999999999"
},
"email": {
"to": "cliente@exemplo.com",
"subject": "Pedido enviado"
},
"sms": {
"to": "5511999999999"
}
}
}GET /api/v2/messages/{id}
Status de um envio feito pela API.
GET /api/v2/templates
Lista os modelos da conta (só authKey).
GET /api/v2/replies
Lista as respostas do chatbot (só authKey).
Fila: com "queue": true e "delay": 30, a API responde na hora e envia depois de 30 segundos.
Respostas e erros
{ "success": true, "messageStatus": "Success", "message_status": "Success",
"data": { "id": "3EB0...", "to": "5511999999999", "status": "sent" } }
| HTTP | Significado |
|---|---|
200 | Enviado (ou aceito na fila quando queue=true). |
207 | Multicanal com sucesso parcial — veja cada canal em data. |
401 | appKey/authKey ausentes ou inválidas. |
402 | Assinatura vencida. |
403 | Recurso fora do plano ou limite atingido. |
404 | Modelo, resposta ou mensagem não encontrados. |
422 | Dados inválidos: número, mensagem vazia, número sem WhatsApp. |
429 | Muitas requisições por minuto para o mesmo aplicativo. |
503 | Dispositivo do aplicativo desconectado. |
504 | O WhatsApp não respondeu a tempo. |
Webhooks
Cadastre URLs em Aplicativos e API → Webhooks e escolha os eventos: message.received, message.sent, message.failed, device.status, broadcast.finished.
POST https://seu-sistema.com/webhook
X-Event: message.received
X-Signature: hex(HMAC-SHA256(segredo, corpo))
{ "event": "message.received", "at": "2026-10-25T12:00:00Z", "deviceId": "...",
"from": "5511999999999@s.whatsapp.net", "phone": "5511999999999",
"pushName": "Ana", "text": "Quero agendar", "kind": "text" }
Verifique a assinatura (Node.js):
const ok = crypto.createHmac('sha256', SEGREDO).update(corpoBruto).digest('hex') === req.get('X-Signature');
Boas práticas
- Respeite o limite de 60 requisições por minuto por aplicativo.
- Use
queuepara lotes grandes; a plataforma mantém intervalos entre envios do mesmo número. - Trate o código 503 (número desconectado) avisando sua equipe — o painel também envia alerta.
- Siga a Política anti-spam.