Documentação da API

Tudo o que precisas para enviar mensagens de WhatsApp a partir dos teus sistemas.

Primeiros passos

  1. Cria a tua conta e liga o teu WhatsApp em Os meus números.
  2. Em Chaves API, cria uma chave. Guarda-a: só é mostrada uma vez.
  3. 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âmetroObrigatórioDescrição
apikeySimA tua chave. Na API REST vai no cabeçalho Authorization: Bearer.
phone ou toNãoDestinatário. Sem ele, a mensagem chega ao teu próprio número: ideal para avisos internos. Também se aceita recipient.
groupNãoID de um grupo de WhatsApp em vez de um número. Vê Grupos.
fromNãoNúmero emissor se tiver vários: o ID, o nome ou o número. Sem ele usa-se o principal.
textSim, exceto com ficheiroTexto da mensagem, até 4.000 caracteres. Aceita emojis e a formatação do WhatsApp: *negrito*, _itálico_.
fileNãoLink público para uma imagem, PDF, vídeo ou áudio. O texto é enviado como legenda.
formatNãoCom json, o link simples responde em JSON em vez de texto.
langNãoIdioma 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ódigoSignificadoO que fazer
400Falta o texto, o número é inválido ou o emissor não existeRevê os parâmetros
401Chave errada ou eliminadaCria uma nova chave no painel
402O teste gratuito terminouEscolhe um plano no painel
403Conta desativada, ou chave do bot usada para outro destinoContacta o suporte
429Demasiados pedidos por minuto ou limite diário atingidoAguarda, 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

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'})