Documentação da API
Tudo o que precisas para enviar mensagens de WhatsApp a partir dos teus sistemas.
Primeiros passos
- Cria a tua conta e liga o teu WhatsApp em Os meus números.
- Em Chaves API, cria uma chave. Guarda-a: só é mostrada uma vez.
- Abre este link no navegador, com a tua chave. Vais receber uma mensagem:
/api/send?text=Ola&apikey=TUA_CHAVE
Enviar uma mensagem
Há duas formas equivalentes. Usa a que for mais cómoda para ti.
Link simples (GET ou POST de formulário)
/api/send?phone=912345678&text=A%20sua%20encomenda%20sai%20hoje&apikey=TUA_CHAVE
Aceita os parâmetros no endereço ou como formulário (application/x-www-form-urlencoded). Também responde em /send.php.
API REST (JSON)
POST /api/v1/messages
Authorization: Bearer TUA_CHAVE
Content-Type: application/json
{ "to": "912345678", "text": "A tua encomenda sai hoje" }
Parâmetros
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
apikey | Sim | A tua chave. Na API REST vai no cabeçalho Authorization: Bearer. |
phone ou to | Não | Destinatário. Sem ele, a mensagem chega ao teu próprio número: ideal para avisos internos. Também se aceita recipient. |
group | Não | ID de um grupo de WhatsApp em vez de um número. Vê Grupos. |
from | Não | Número emissor se tiver vários: o ID, o nome ou o número. Sem ele usa-se o principal. |
text | Sim, exceto com ficheiro | Texto da mensagem, até 4.000 caracteres. Aceita emojis e a formatação do WhatsApp: *negrito*, _itálico_. |
file | Não | Link público para uma imagem, PDF, vídeo ou áudio. O texto é enviado como legenda. |
format | Não | Com json, o link simples responde em JSON em vez de texto. |
lang | Não | Idioma das mensagens de erro: pt, es, en ou fr. |
Grupos
Disponível no plano Pro e superiores, e durante o período de teste. O teu número tem de ser membro do grupo. No painel, Os meus números → Ver grupos mostra cada grupo com o ID. Também os podes consultar pela API:
GET /api/v1/groups
Authorization: Bearer TUA_CHAVE
{"ok":true,"groups":[{"id":"120363012345678901","name":"Comerciais","size":6}]}
/api/send?group=120363012345678901&text=Reunião%20às%2010&apikey=TUA_CHAVE
Em JSON também serve "to": "[email protected]". Os grupos estão disponíveis com números ligados por QR.
Vários números
Se a tua conta tiver vários números, escolhe o emissor com from. Aceita o ID que aparece no painel, o nome que lhe deste (por exemplo Oficina) ou o próprio número.
/api/send?from=Oficina&phone=912345678&text=O%20seu%20equipamento%20está%20pronto&apikey=TUA_CHAVE
Cada número tem a sua fila: os envios de um número não esperam pelos de outro.
Imagens e documentos
Adiciona file com um link que se possa descarregar sem iniciar sessão. Máximo 16 MB.
/api/send?phone=912345678&text=Guia%20em%20anexo&file=https://drive.google.com/file/d/ID/view&apikey=TUA_CHAVE
Os links do Google Drive do tipo «Qualquer pessoa com o link» são convertidos automaticamente em descarga direta.
Respostas da API
As mensagens não são enviadas no momento do pedido: entram numa fila e saem por ordem, com pausas de alguns segundos para proteger o teu número. A resposta confirma que a mensagem está na fila.
Link simples: 200 Mensagem na fila. id=123
API REST: 202 {"ok":true,"id":123,"status":"queued","to":"351912345678","from":5}
| Código | Significado | O que fazer |
|---|---|---|
| 400 | Falta o texto, o número é inválido ou o emissor não existe | Revê os parâmetros |
| 401 | Chave errada ou eliminada | Cria uma nova chave no painel |
| 402 | O teste gratuito terminou | Escolhe um plano no painel |
| 403 | Conta desativada, ou chave do bot usada para outro destino | Contacta o suporte |
| 429 | Demasiados pedidos por minuto ou limite diário atingido | Aguarda, ou sobe de plano |
Estado de uma mensagem
GET /api/v1/messages/123
Authorization: Bearer TUA_CHAVE
{"ok":true,"message":{"id":123,"status":"sent","attempts":1,"error":null, ...}}
Estados: queued (na fila), sending, sent (entregue ao WhatsApp) e failed (não enviada, com o motivo em error). Se um número se desligar, as mensagens esperam e são reenviadas automaticamente.
Estado dos teus números: GET /api/v1/status
Formato dos números
Funciona com números de qualquer país. Podes escrevê-los em formato internacional (+351 912 345 678, 00351…) ou no formato local do teu país. Sem indicativo, usa-se o país da tua conta, configurável nas Definições.
O sistema conhece as regras de numeração de cada país: retira o 0 ou o prefixo nacional quando necessário e acrescenta o indicativo. Por exemplo, (11) 98765-4321 no Brasil passa a +55 11 98765 4321 e 06 12 34 56 78 em França passa a +33 6 12 34 56 78.
Limites
- Mensagens por dia: conforme o teu plano. Vês no início do painel.
- Pedidos: até 30 por minuto por chave.
- Entre mensagens do mesmo número há alguns segundos de pausa para que o WhatsApp não as considere spam.
Envia apenas mensagens que os destinatários esperam. Os envios em massa para pessoas que não te conhecem podem levar o WhatsApp a restringir o teu número.
Receber mensagens
Nas Definições podes indicar um endereço https:// do teu sistema. Cada mensagem que qualquer um dos teus números receber é reencaminhada assim:
POST https://o-teu-sistema.com/webhook
Content-Type: application/json
X-Wagate-Signature: assinatura HMAC-SHA256 do corpo
{"event":"message.received","number_id":5,"from":"+351912345678","message":"SIM","name":"Luís","group":null,"at":1762440000000}
Exemplos
Google Apps Script
function enviarWhatsApp(telefone, texto) {
const r = UrlFetchApp.fetch('/api/send', {
method: 'post',
payload: { apikey: 'TUA_CHAVE', phone: telefone, text: texto },
muteHttpExceptions: true,
});
return r.getResponseCode() === 200;
}
AppSheet
Automation, Bot, tarefa «Call a webhook»: URL /api/v1/messages, POST, JSON, cabeçalho Authorization: Bearer TUA_CHAVE e corpo:
{ "to": "<<[TELEFONE]>>", "text": "Olá <<[CLIENTE]>>, a tua encomenda está pronta." }
PHP
file_get_contents('/api/send?' . http_build_query([
'apikey' => 'TUA_CHAVE', 'phone' => '912345678', 'text' => 'Olá do PHP',
]));
Python
import requests
requests.post('/api/v1/messages',
headers={'Authorization': 'Bearer TUA_CHAVE'},
json={'to': '912345678', 'text': 'Olá do Python'})