API do WhatsApp para agentes de IA: acesso oficial em minutos, sem se tornar Tech Provider
Um agente de IA obtém acesso oficial ao WhatsApp através da Cloud API da Meta, e um número que continua na app do WhatsApp Business junta-se a ela através de um Tech Provider ou Solution Partner. Pode tornar-se um, com verificação da empresa, vídeos de App Review e uma implementação de Embedded Signup, ou ligar-se através de um fornecedor que já o seja: o número junta-se em minutos e o agente recebe ferramentas MCP ou credenciais de API.
A easyCoexistence é um Tech Provider independente da Meta: liga um número do WhatsApp Business à Cloud API através da Coexistência em minutos, para que o seu agente tenha acesso oficial enquanto a empresa mantém a app.
O que a Meta exige de quem integra um número que continua na app do WhatsApp Business: estatuto de Tech Provider ou Solution Partner.
A App Review pede um vídeo de uma mensagem enviada a partir da sua aplicação e outro da sua aplicação a criar um template.
O que a App Review concede a whatsapp_business_messaging e a whatsapp_business_management, ambos necessários para se tornar Tech Provider.
Quando a Meta descontinuou o Embedded Signup v2 e v3, indicando às integrações que migrem para a v4.
Throughput fixo de um número em uso com a app do WhatsApp Business e com a Cloud API.
Durante quanto tempo um link de ligação alojado continua válido quando uma plataforma integra o número de um cliente através da Partner API.
De que precisa um agente de IA para usar o WhatsApp de forma oficial?
Quatro coisas da Cloud API da Meta. Um ID do número de telefone e um token de acesso com a permissão whatsapp_business_messaging, para que o agente possa chamar o endpoint de mensagens. Um endpoint de webhook para onde a Meta entrega as mensagens recebidas e, num número partilhado com a app, smb_message_echoes para as respostas que uma pessoa escreve no telefone. Templates aprovados, porque uma mensagem escrita só chega a quem contactou nas últimas 24 horas. E uma forma de saber quando a ligação falha, já que a app no telefone continua a funcionar quando a parte da API deixa de funcionar.
O atalho que as pessoas encontram primeiro é a automatização do WhatsApp Web, que entra como dispositivo associado. Isso viola os termos do WhatsApp e coloca o número em risco de banimento, seja qual for o agente que esteja por cima.
Em que consiste o percurso Tech Provider?
A sequência da própria Meta, por esta ordem. Cada passo é gratuito, e nenhum pode ser comprado mais depressa: as revisões seguem o calendário da Meta, que não publica prazos, por isso deve prever semanas e não dias antes de o número do primeiro cliente se ligar. Depois disso, o backend tem de continuar a funcionar: a troca de token após cada registo, um recetor de webhooks, o encaminhamento por número e a monitorização de desligamentos, como a regra de inatividade de 14 dias da Meta.
Qual é o percurso mais curto?
Ligar o número através de um fornecedor que já passou por esse processo. Com a easyCoexistence, a empresa executa o Embedded Signup da Meta e lê um código com a app do WhatsApp Business, o que demora cerca de dois minutos, e o número junta-se à Cloud API no portefólio da própria empresa, enquanto a app continua a funcionar. O agente recebe depois acesso na forma que falar: ferramentas MCP para um assistente como o ChatGPT, Claude, Claude Code ou Codex, ou as credenciais e webhooks do número para o código que execute.
| Connect through easyCoexistence | Become a Tech Provider | |
|---|---|---|
| Meta app and App Review | Not needed: the number joins through ours | Yours to build and pass |
| Embedded Signup | Hosted, with the QR scan in the app | You integrate version 4 and host the flow |
| First number connected | Minutes after signing up | After verification and review |
| Webhook trust | A secret in your URL, or X-EC-Signature on forwarded messages | Your app secret signs Meta's deliveries |
| Disconnection alerts | Every number watched 24/7, 14-day rule included | Monitoring you build and run |
| Who owns the WhatsApp Business Account | The business, in its own portfolio | The business |
Como é que o agente obtém as credenciais do número?
Através de get_api_credentials, ou na página do número no painel. A ferramenta devolve o URL base da Graph API, o ID da WhatsApp Business Account, o phone number ID, o endpoint de envio e, quando existe, o token de acesso próprio, limitado aos recursos do WhatsApp da empresa. Quando não foi emitido nenhum token de cliente, o token vem como null com uma nota a indicar que voltar a ligar o número a partir do painel emite um, sem substituir um token que funcione. Não há segredo de app para obter, porque a Meta assina os webhooks com o segredo de app da easyCoexistence, que nunca é partilhado. A ferramenta exige um plano ativo, já que o token pode enviar.
curl -X POST "$SEND_ENDPOINT" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5511999998888",
"type": "text",
"text": { "body": "Your order #1042 is ready for pickup." }
}'Como chegam as mensagens recebidas ao agente?
Cada número tem dois modos, que se alternam com set_inbound_mode ou na página do número. Direto para o seu servidor: set_webhook_destination aponta a Meta diretamente para o seu endpoint HTTPS, que tem de responder ao handshake GET da Meta, e a easyCoexistence nunca vê as mensagens, por isso as automatizações ficam desligadas. Como a Meta assina essas entregas com o nosso segredo de app, coloque um segredo aleatório longo no caminho do URL e rejeite os pedidos que não o tenham.
Com automatizações ativas: a Meta entrega à easyCoexistence, as automatizações podem responder, e um URL de reencaminhamento opcional recebe o payload original da Meta sob "value", assinado com X-EC-Signature: t=<unix>,v1=<HMAC-SHA256 de "<t>.<body>"> com um segredo mostrado uma só vez. O passo Chamar o meu webhook de uma automatização também entrega a mensagem e as últimas 10 mensagens da conversa ao seu agente, e envia a resposta quando a sua resposta for {"reply": "..."} no prazo de 20 segundos.
Que limites o agente tem de respeitar?
Os da Meta, e são os mesmos através de qualquer fornecedor. Um agente que os conheça de antemão evita as falhas que parecem bugs:
- 20 mensagens por segundo por número, fixadas pela Meta para números partilhados com a app do WhatsApp Business.
- Mensagens escritas apenas nas 24 horas seguintes à última mensagem do cliente; depois, um template aprovado.
- Os templates são enviados apenas pela API, porque a app num número de Coexistência não os consegue enviar.
- As respostas que uma pessoa escreve na app chegam como
smb_message_echoes; convém pausar o agente nesse chat, senão o cliente recebe duas respostas. - As conversas de grupo não são sincronizadas com a API, por isso o agente trabalha em conversas individuais.
- Contactos e até 6 meses de conversas individuais são importados uma única vez, apenas se um destino de webhook direto estiver guardado nas 24 horas seguintes à ligação; um número com automatizações ativas não recebe a importação.
- As chamadas de voz e de vídeo continuam a funcionar na app, mas a Cloud API não transporta chamadas num número de Coexistência, por isso o agente trabalha em texto.
Uma plataforma pode ligar desta forma os números dos seus próprios clientes?
Sim, através da Partner API, que é a forma como um SaaS ou uma agência regista os seus clientes sem ter estatuto de Tech Provider próprio. Crie a chave com create_api_key (começa por ec_live_ e é mostrada uma só vez) e depois chame POST /api/v1/connect-sessions a partir do seu backend, ou create_connect_link a partir do assistente, para obter um link alojado válido durante 1 hora. O cliente executa ali a janela pop-up da Meta e a leitura do código QR, e regressa ao seu redirect_url com um connection_id. GET /api/v1/connections/:id?credentials=1 devolve então o token próprio do cliente, e os eventos de estado, como connection.disconnected, chegam assinados com X-EC-Signature. Cada número é faturado na sua conta, com os mesmos escalões por número.
Erros comuns
- Validar o X-Hub-Signature-256 num destino direto. A Meta assina com o segredo de app da easyCoexistence, que nunca é partilhado, por isso as entregas genuínas falham a verificação; a solução é confiar num segredo aleatório longo no URL, ou usar o reencaminhamento com X-EC-Signature.
- Receber com o nó WhatsApp Trigger do n8n. Este espera a sua própria app da Meta; use antes o nó genérico Webhook com um segredo no URL.
- Ignorar smb_message_echoes. O agente responde então por cima de uma pessoa que já respondeu do telefone, e o cliente lê duas respostas.
- Guardar o destino direto dias depois de ligar, ou deixar o número com automatizações ativas. A importação única de contactos e de até 6 meses de conversas da Meta exige um destino direto guardado nas 24 horas seguintes à ligação.
O agente trabalha através de mais de 30 ferramentas MCP ou através das credenciais e webhooks de cada número, e cada número é monitorizado 24/7 com alertas. De US$ 9 a US$ 0.75 por número por mês, com descida à medida que acrescenta números, e os primeiros 3 dias sem custo.
Perguntas frequentes
Preciso de uma app própria da Meta?
Não. O número é integrado através da app da Meta da easyCoexistence e fica no portefólio e na WhatsApp Business Account da própria empresa. O seu código envia com o token próprio da empresa obtido em get_api_credentials, por isso nenhuma app sua fica envolvida, a menos que mais tarde a construa.
O agente e a equipa podem usar o número ao mesmo tempo?
Sim. A Meta espelha as mensagens entre a Cloud API e a app do WhatsApp Business, por isso o que o agente envia aparece na conversa, na app do telefone, e o que a equipa escreve na app chega ao seu sistema como smb_message_echoes.
Que frameworks de agentes funcionam com ele?
Qualquer cliente que fale MCP sobre HTTP com OAuth, como o ChatGPT, Claude, Claude Code, Codex e Cursor, e qualquer código que chame a Graph API da Meta: Node.js, Python, n8n, LangChain, o OpenAI Agents SDK ou o Vercel AI SDK. A API por baixo é a da própria Meta, por isso nada proprietário fica dentro do agente.
É permitido um assistente de IA de uso geral no WhatsApp?
Os Termos de Solução para Empresas da Meta, secção 4.7, impedem os fornecedores de assistentes de IA de uso geral de os oferecer na WhatsApp Business Platform quando a IA é a funcionalidade principal, segundo a determinação da Meta, em vigor desde 15 de janeiro de 2026. Uma empresa que usa IA para os seus próprios clientes, em apoio, vendas ou marcações, não é o alvo, e reguladores da UE e do Brasil ordenaram à Meta que suspendesse ou revertesse a regra para assistentes concorrentes.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em