Introdução à API

A API do wa-api permite enviar e receber mensagens WhatsApp programaticamente. Este guia cobre tudo que você precisa saber antes de fazer sua primeira requisição.

Base URL

Todas as requisições usam:

https://endpoint.wi.api.br

Autenticação

Toda requisição exige o header x-api-key com sua chave de API:

GET /sessions HTTP/1.1
Host: endpoint.wi.api.br
x-api-key: wk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Requisições sem header ou com chave inválida retornam 401.

Dica

Consulte a página de Autenticação para detalhes sobre criação de chaves e níveis de permissão.

Identificação de sessão

Existem duas formas de identificar qual sessão WhatsApp deve processar a requisição:

Header x-instance

Usado nos endpoints de operação: /chat/*, /user/*, /groups, /newsletter/*.

POST /chat/send/text HTTP/1.1
Host: endpoint.wi.api.br
x-api-key: wk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
x-instance: minha-sessao
Content-Type: application/json

{"chatId": "5511999999999@s.whatsapp.net", "text": "Olá!"}

Path parameter /sessions/:id/*

Usado nos endpoints de gerenciamento da sessão: criar, conectar, desconectar, verificar status.

GET /sessions/minha-sessao/status HTTP/1.1
Host: endpoint.wi.api.br
x-api-key: wk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Use x-instance quando estiver enviando mensagens ou consultando dados. Use o path parameter quando estiver gerenciando o ciclo de vida da sessão.

Formato de resposta

Respostas de sucesso:

{
  "success": true,
  "messageId": "3EB0A8C2F5B3D1E4A9"
}

Respostas de erro:

{
  "error": "Session not found"
}

O campo error contém uma descrição legível do problema. Em endpoints de envio, messageId identifica a mensagem criada no WhatsApp.

Códigos de status HTTP

Código	Significado
200	Sucesso
400	Body inválido ou campos faltando
401	API key ausente ou inválida
403	Sem permissão para o recurso
404	Recurso não encontrado
429	Rate limit excedido
500	Erro interno
502	Engine da sessão inacessível

Rate limiting

A API retorna headers de rate limit em toda resposta:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87

Quando o limite é excedido, a resposta 429 inclui o header Retry-After com o número de segundos até a próxima janela:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Implemente exponential backoff: espere 1s, 2s, 4s, 8s entre retries em caso de 429.

Formato de JID

JID (Jabber ID) é o identificador de um contato, grupo ou newsletter no WhatsApp. Use o formato correto ao enviar mensagens:

Tipo	Formato	Exemplo
Individual	{DDI}{DDD}{número}@s.whatsapp.net	5511999999999@s.whatsapp.net
Grupo	{id}@g.us	120363001234567890@g.us
Newsletter	{id}@newsletter	120363000000000000@newsletter

Para números individuais, use o telefone completo com código do país, sem +, sem espaços, sem traços.

Dicas gerais

Use x-instance para identificar a sessão

Envie o header x-instance com o nome da sessão em toda requisição de envio ou consulta de dados.

Guarde sua key em variável de ambiente

Nunca exponha a API key no código-fonte — armazene em variável de ambiente e injete em runtime.

Implemente retry com backoff em erros 5xx

Erros 500 e 502 podem ser transientes — implemente retry com exponential backoff antes de considerar a requisição como falha definitiva.

Valide o JID antes de enviar

Um JID malformado resulta em erro 400 — valide o formato (@s.whatsapp.net, @g.us, @newsletter) no seu código antes de chamar a API.