API de WhatsApp para desenvolvedores
O WAIA Connect é uma API REST sobre a API oficial do WhatsApp da Meta (Cloud API e Coexistence). Você envia um POST /v1/messages com a sua chave, nós o colocamos na fila e o entregamos à Meta em um ritmo seguro, e as mensagens que chegam vão para um webhook assinado. Provedor de tecnologia verificado pela Meta, com documentação pública, OpenAPI e exemplos em quatro linguagens.
O que a API resolve por você
- Fila de saída com novas tentativas: o envio é confirmado com
202e entregue à Meta respeitando o ritmo de cada número. Uma rejeição da Meta fica registrada no status da mensagem com um código estável. - Idempotência: o cabeçalho
Idempotency-Keyevita enviar duas vezes a mesma mensagem se você tentar de novo. - Webhooks assinados com HMAC sobre data e corpo (proteção contra reenvios), e um cabeçalho estático opcional para ferramentas sem código como o n8n.
- Modelos: criá-los, sincronizá-los e validá-los antes de enviá-los à Meta, com o motivo e como corrigir se algo for ser rejeitado. Também carrosséis de 2 a 10 cartões com foto ou vídeo, e saber qual cartão e qual botão cada contato tocou (Modelos carrossel).
- Mídia: enviar imagem, documento, áudio e vídeo por link, e baixar a mídia que chega por um proxy.
- Lido e «digitando…»: marcar como lida uma mensagem recebida (tiques azuis) e mostrar «digitando…» enquanto o seu sistema prepara a resposta. Não consome cota.
- Webhooks pela API (
/v1/webhooks): criar, testar e trocar o segredo com a sua chave; e o link de cadastro pode trazer o webhook do número, que nasce assinado com o segredo que você já tem. - O desfecho de cada cadastro:
onboarding.completedeonboarding.failed(com o motivo e o código da Meta) chegam ao seu webhook, ou você pergunta comGET /v1/onboarding-links?externalId=; e a desconexão também vai pela API (DELETE /v1/connections/{id}, com o seuexternalId): o webhook dele se desliga sozinho e você recebeconnection.disconnected. - O histórico da coexistência: se você escolher ao conectar, recebe até 6 meses de conversas por webhook (
history.batch) ou pede pela API (GET /v1/connections/{id}/history). Não consome cota. - Mensagens editadas e apagadas:
message.editedtraz a versão final com o id da original (em números somente Cloud API, a Meta avisa a edição sem o texto:textAvailable: false) emessage.revoked, a exclusão. - Erros da Meta traduzidos para um catálogo de códigos estáveis, com o que fazer em cada caso.
- Estado de envio antes de uma campanha:
GET /v1/connections/{id}/sending-statusdiz se um número pode iniciar conversas e por que não — o veredito e os códigos originais da Meta (141006,141010,131042), a verificação da empresa, o pagamento (sem dados de cartão) e o limite diário, compartilhado por todo o portfólio; o que a Meta não deixa ler vemunknown. Cada mudança chega ao seu webhook comoconnection.sending_status_changed(Estado de envio). - Avisos por e-mail e Novidades: cada aviso dos seus números (desconectado, template aprovado, webhook falhando…) fica em
GET /v1/noticescom o mesmo texto do e-mail; você escolhe se também chega por e-mail, para toda a conta (PATCH /v1/account/settings) ou número por número.
Como fica
Um envio é uma requisição HTTP com a sua chave de API. O número sai do identificador de conexão (conn_…) que GET /v1/connections devolve.
Exemplos prontos para copiar em cURL, Node.js, PHP e Python: Enviar uma mensagem. O contrato completo: OpenAPI.
Tudo o que a API faz, endpoint por endpoint
| Endpoint | O que faz |
|---|---|
POST /v1/messages | Enviar uma mensagem: texto, template, imagem, documento, áudio ou vídeo. Confirmado com 202 e enviado pela fila. Limite por número (Coexistência 20/s, Cloud API 80/s) e por conta. |
GET /v1/messages/{id} | O status de um envio (na fila, enviado, entregue, lido, falhou) e o motivo se falhou. Nunca o conteúdo. |
POST /v1/messages/read | Marcar como lida uma mensagem recebida (tiques azuis) e, se quiser, mostrar «digitando…». Não consome cota. |
GET /v1/connections | Seus números conectados, com o identificador conn_…, o status e o modo (Cloud API ou coexistência). |
PATCH /v1/connections/{id} | Dar a um número o seu nome, o seu identificador externo, notas, um limite mensal de envios e se os avisos dele chegam por e-mail. |
DELETE /v1/connections/{id} | Desconectar um número (pelo conn_… ou o seu identificador externo), como «Desconectar» do painel: libera a vaga no seu plano e não apaga nada na Meta. |
GET /v1/connections/{id}/history | Ler, por páginas, o histórico da coexistência que você escolheu receber ao conectar. Ler não apaga nada. |
POST /v1/connections/{id}/history/{batchId}/ack | Confirmar que você recebeu um lote do histórico: o WAIA Connect o apaga na hora. |
GET /v1/account/settings | Ver se os avisos dos seus números e dos seus cadastros chegam por e-mail (emailNotices). |
PATCH /v1/account/settings | Ligar ou desligar esses avisos por e-mail para toda a conta. Cobrança, segurança e suporte chegam sempre. |
GET /v1/notices | As Novidades: cada aviso dos seus números, tenha saído por e-mail ou não, com o mesmo texto, no seu idioma. Filtre por número e por não lidos. |
POST /v1/notices/{id}/read | Marcar um aviso como lido (também no painel). |
POST /v1/notices/read-all | Marcar todos os avisos como lidos de uma vez (também no painel). |
GET /v1/usage | O que você consumiu no período atual, seus números e o extra estimado do ciclo. |
GET /v1/connections/{id}/sending-status | Este número pode iniciar conversas? canSend, os códigos da Meta por entidade, verificação, pagamento (sem cartão) e limite diário; o que a Meta não deixa ler, unknown. |
POST /v1/connections/{id}/sending-status/refresh | Reler o estado de envio na Meta (só leitura), uma vez por número a cada 10 min. |
GET /v1/connections/{id}/usage | Os números de uma linha: totais, série diária e saúde. |
GET /v1/usage/by-connection | Os totais de todos os seus números em um período, de relance. |
GET /v1/accounts/oversubscription | Se você está vendendo mais números do que o seu plano inclui. |
GET /v1/branding | A sua marca (nome, logo, cor) para a página de cadastro que os seus clientes veem. |
PUT /v1/branding | Alterar a sua marca. |
POST /v1/onboarding-links | Criar um link de cadastro para o seu cliente conectar o número sem te passar as credenciais da Meta. Com webhook, o número já nasce com o seu webhook. |
GET /v1/onboarding-links | Os seus links de cadastro e como terminou cada um (outcome). Com ?externalId=, os de um cliente. |
GET /v1/onboarding-links/{id} | Um link de cadastro com o seu desfecho: pendente, concluído (com o conn_… e o webhook) ou falho, com o motivo e o código da Meta. |
PATCH /v1/onboarding-links/{id} | Mudar a página prévia de um link ativo: intro: "minimal" (um botão e uma linha) ou full; null = a da conta. |
GET /v1/onboarding-cases | Os casos de cadastro dos seus clientes (A-<n>): o que escreveram, o código da Meta e o diagnóstico; ?status=open|acked|all. |
POST /v1/onboarding-cases/{id}/ack | Marcar um caso como atendido (idempotente). Uma entrega do webhook não conta. |
DELETE /v1/onboarding-links/{id} | Revogar um link de cadastro. |
POST /v1/webhooks | Criar um webhook da conta ou de um número (por conn_… ou o seu externalId). O segredo de assinatura aparece uma única vez. |
GET /v1/webhooks | Os seus webhooks, todos ou os de um número (filtre por conn_… ou externalId). Nunca o segredo. |
GET /v1/webhooks/{id} | Um webhook e o seu estado: ativo, falhas seguidas, última resposta. |
PATCH /v1/webhooks/{id} | Mudar a URL ou os eventos, ligar ou desligar, ou passar para outro número. |
DELETE /v1/webhooks/{id} | Apagar um webhook. |
POST /v1/webhooks/{id}/test | Enviar agora um evento de teste assinado e ver o que o seu servidor respondeu. |
POST /v1/webhooks/{id}/rotate-secret | Trocar o segredo de assinatura: o novo aparece uma vez e o antigo deixa de valer na hora. |
GET /v1/media/{mediaId} | Baixar a imagem, o áudio ou o documento que te enviaram, sem expor o token da Meta. |
GET /v1/templates | Os seus templates e o status na Meta. |
POST /v1/templates | Criar um template na Meta, validado antes de enviar: com imagem, vídeo, documento ou localização no topo, e botões, ou um carrossel de 2 a 10 cartões. |
POST /v1/templates/media | Enviar o arquivo de amostra que a Meta revisa para um template com imagem, vídeo ou documento. Devolve o handle para criá-lo. |
POST /v1/templates/validate | Validar um template sem enviar nada à Meta: todos os erros juntos, cada um com seu campo, no seu idioma. |
POST /v1/templates/preview | A prévia de um template, em JSON ou como um balão do WhatsApp em HTML para mostrar ao seu cliente. |
GET /v1/templates/{id} | Um template. |
PATCH /v1/templates/{id} | Editar um template onde a Meta permite (aprovado, rejeitado ou pausado), dentro do limite de vezes. |
DELETE /v1/templates/{id} | Apagar um template. |
POST /v1/templates/sync | Trazer da Meta os templates e o status atual. |
POST /v1/templates/precheck | Validar um rascunho antes de enviar: se a Meta vai recusar, o motivo e como corrigir. |
POST /v1/templates/generate-examples | Sugerir exemplos para as variáveis de um template (a Meta pede). |
GET /v1/templates/catalog | O catálogo de templates por segmento, escritos para a Meta aprovar. |
POST /v1/templates/seed | Carregar templates do catálogo em um número. |
GET /v1/templates/bulk-targets | Em quais números um template pode ser aplicado de uma vez. |
POST /v1/templates/bulk | Criar o mesmo template em vários números de uma vez. |
GET /v1/templates/drafts | Os templates que os seus clientes propuseram, para revisar. |
GET /v1/templates/drafts/count | Quantas propostas aguardam revisão. |
POST /v1/templates/drafts/{id}/approve | Aprovar uma proposta: é validada e criada na Meta. |
PUT /v1/templates/drafts/{id} | Corrigir uma proposta antes de aprovar (a original fica guardada). |
POST /v1/templates/drafts/{id}/reject | Recusar uma proposta. |
POST /v1/templates/drafts/bulk-approve | Aprovar várias propostas juntas; se uma falhar, as outras seguem. |
POST /v1/template-links | Criar um link para o seu cliente propor templates para o número dele. |
GET /v1/template-links | Os seus links para propor templates. |
DELETE /v1/template-links/{id} | Revogar um link para propor templates. |
O detalhe de cada um, com os erros: OpenAPI.
O que ela não faz
- Não é uma caixa de entrada de conversas para atender com uma equipe: para isso existe o WAIA, o nosso produto pronto para usar.
- Não guarda arquivos: para enviar um arquivo seu, você o hospeda e envia o link.
- Não tira você das regras da Meta: a janela de 24 horas, os modelos aprovados e os limites de envio continuam valendo. Nós os explicamos em Antes de conectar.
Quanto custa
Tarifa fixa por número conectado, sem teto de mensagens. Você começa com 14 dias de teste; o plano menor é o Starter (US$ 12 por mês).
- Starter — US$ 12 por mês, 1 número
- Studio — US$ 25 por mês, 5 números
- Agencia — US$ 45 por mês, 12 números
- Escala — US$ 99 por mês, 30 números, e US$ 3 por número extra
A Meta cobra à parte as mensagens dela, no seu cartão; não acrescentamos nenhuma taxa. Comparação com quem acrescenta: WAIA Connect vs Twilio.
Perguntas frequentes
Usa a API oficial da Meta?
Sim. O WAIA Connect é um provedor de tecnologia verificado pela Meta e opera a Cloud API e a convivência (Coexistence). Não usa bibliotecas não oficiais que simulam o WhatsApp Web.
Como recebo as mensagens que chegam?
Você registra uma URL https e elas chegam por POST, assinadas com HMAC. O guia de verificação da assinatura tem exemplos em quatro linguagens.
O que acontece se eu enviar a mesma requisição duas vezes?
Com o mesmo Idempotency-Key a mensagem é enviada uma única vez e a segunda resposta devolve o mesmo identificador.
Existe limite de mensagens por mês?
No WAIA Connect, não: o plano é pago por número conectado. A Meta tem limites próprios para iniciar conversas com modelos, que dependem da sua conta da Meta.
A documentação foi pensada para ser lida com uma IA?
Sim: cada módulo também está em Markdown, há um llms.txt na raiz do site e o contrato completo está em OpenAPI.
Continue lendo
Conecte o seu primeiro número hoje
Provedor de tecnologia verificado pela Meta. Coexistence em um clique.
Começar