Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

Criar um bot WhatsApp com Claude Code ou Codex, no número que mantém na app

Adicione um servidor MCP do WhatsApp ao Claude Code ou ao Codex e deixe o agente de programação fazer a configuração: lê as credenciais da Cloud API do número, cria um recetor de webhook, encaminha as mensagens recebidas para ele e envia uma resposta de teste a quem escreveu nas últimas 24 horas. O resultado é o seu próprio agente, a correr como código seu, no seu servidor.

A easyCoexistence liga o número WhatsApp Business que mantém na app à Cloud API da Meta através da Coexistence e dá ao Claude Code e ao Codex mais de 30 ferramentas MCP para construir: credenciais, encaminhamento, templates, envios de teste e automatizações.

--scope user

Flag do Claude Code que carrega um servidor em todos os seus projetos; o âmbito local predefinido carrega-o apenas onde foi adicionado.

codex mcp login

Comando do Codex que guarda o início de sessão OAuth de um servidor; sem credencial, o Codex pode ligar-se sem autenticação.

HTTPS

O que um destino webhook direto tem de usar, e tem de devolver hub.challenge no handshake GET da Meta.

20 seconds

Quanto tempo um passo «Chamar o meu webhook» espera pelo {"reply"} do seu endpoint antes de o passo falhar.

24 hours

Janela de atendimento ao cliente após a última mensagem do utilizador; fora dela, a Meta só aceita mensagens template.

20 msg/s

Throughput fixo de um número usado simultaneamente com a app WhatsApp Business e a Cloud API.

De que precisa um agente de programação para criar um agente WhatsApp?

Quatro coisas. Um número WhatsApp Business ligado à Cloud API da Meta através da Coexistence, para que a app continue no telemóvel enquanto o código pode enviar e receber. Uma ligação MCP do Claude Code ou do Codex a esse número, que permite ao agente de programação ler credenciais, alterar o encaminhamento e enviar mensagens de teste sem abrir um painel. Um endereço HTTPS público para o recetor, de um alojamento onde publique ou de um túnel enquanto desenvolve. E uma chave de modelo para o agente que está a criar.

Mantenha separados os dois agentes. O Claude Code ou o Codex é o construtor: atua apenas enquanto trabalha com ele no terminal. O programa que ele escreve é o que responde aos clientes, e continua a funcionar depois de fechar a sessão.

Como se adicionam as ferramentas WhatsApp ao Claude Code e ao Codex?

Cada um recebe um URL no terminal e inicia sessão com OAuth, pelo que nenhuma chave fica num ficheiro. No Claude Code, adicione o servidor com --scope user para que seja carregado em todos os projetos; depois inicie o claude, execute /mcp, escolha easycoexistence e inicie sessão no navegador. No Codex, adicione o servidor e execute codex mcp login, que guarda o início de sessão; codex mcp list mostra o que está configurado. O Codex guarda a entrada em ~/.codex/config.toml, que a aplicação ChatGPT para computador e a extensão do Codex para IDE também leem.

Verifique que funcionou pedindo algo que só as ferramentas podem responder, como «liste os meus números WhatsApp». O agente chama list_numbers e obtém o connection_id de cada número, que todas as outras ferramentas usam.

Add the server, then sign in
# Claude Code: then start claude and run /mcp to sign in
claude mcp add --transport http easycoexistence --scope user https://easycoexistence.com/api/mcp

# Codex: add, store the OAuth sign-in, check
codex mcp add easycoexistence --url https://easycoexistence.com/api/mcp
codex mcp login easycoexistence
codex mcp list

Que rota deve o agente construir?

Três rotas levam a mensagem de um cliente ao seu código, e diferem na quantidade de trabalho que o código tem de tratar. Para uma primeira versão, o passo «Chamar o meu webhook» é o mais curto: a easyCoexistence ignora duplicados, recua quando responde a partir do telemóvel e verifica a janela de 24 horas antes de chamar o seu endpoint, pelo que o código só escreve a resposta. Passe para um URL de reencaminhamento ou para um destino direto quando o agente precisar de todos os eventos, e não apenas das mensagens que uma automatização escolhe.

Call my webhook stepAn automation POSTs the message and the chat's last 10 messages, signed; return {"reply": "..."} within 20 seconds
Forward URL (Automations on)A signed copy of each Meta event goes to your code; automations keep running; you send through the Graph API
Direct destinationMeta posts straight to your endpoint; easyCoexistence never sees the messages; automations stop for that number

O que deve pedir ao agente de programação?

Dê-lhe logo à partida a rota, a linguagem e as regras, e peça um plano antes de escrever código. Diga-lhe que chamadas de ferramentas pode fazer por iniciativa própria: ler credenciais e documentação é inofensivo, mas mudar para onde vão as mensagens afeta o número em produção. get_docs devolve a documentação da easyCoexistence, incluindo a forma como um recetor autentica as entregas, para que o agente leia as regras em vez de as adivinhar. Um pedido como este produz um recetor que pode rever de uma só vez:

A request for Claude Code or Codex
Build a WhatsApp agent in Node.js for my number +55 11 4000 1234.
1. Call list_numbers, then get_api_credentials for that number.
   Put send_endpoint and access_token in .env, never in code.
2. Scaffold an HTTPS server with POST /wa/<long random path>.
   Verify X-EC-Signature (HMAC-SHA256 of "<t>.<raw body>").
   Skip message ids already handled.
   On smb_message_echoes, stay quiet on that chat for 4 hours.
3. Reply with my model only within 24 hours of the
   customer's last message.
4. Write tests for the signature check and the 24-hour rule.
Do not call set_inbound_mode or set_webhook_destination
until I say so.

Como se liga o recetor e se testa?

Inicie o servidor onde a Meta e a easyCoexistence possam chegar por HTTPS e deixe depois o agente tratar do encaminhamento. Na rota de URL de reencaminhamento, ele chama set_inbound_mode com o seu URL num número em modo Automatizações; o segredo de reencaminhamento volta uma única vez e o agente escreve-o no seu .env. Na rota direta, o endpoint tem de responder primeiro ao handshake GET da Meta; depois o agente chama set_webhook_destination com o URL, um segredo aleatório longo no caminho e o seu token de verificação.

Para testar, envie uma mensagem para o número da empresa a partir do seu telemóvel e acompanhe os registos: o recetor deve ver o evento, o modelo deve responder e a resposta deve aparecer na conversa. Como acabou de escrever, a janela de 24 horas está aberta, pelo que o agente de programação também pode tentar send_message para o seu próprio número.

O agente final ainda precisa do servidor MCP?

Não. O servidor MCP é a ferramenta do construtor, com a sua sessão iniciada. O agente que coloca em produção envia através da Graph API da Meta, com o send_endpoint e o access_token que get_api_credentials devolveu, o token próprio da empresa limitado aos seus recursos WhatsApp, e recebe pela rota que configurou. Se access_token vier nulo, voltar a ligar o número a partir do painel emite um sem substituir um token que já funciona.

Mantenha a ligação MCP para o trabalho à volta do agente: criar templates com create_template, verificar get_number_health quando algo parecer errado e ler o registo de execução de qualquer automatização que entregue mensagens ao seu código.

Como configurar

  1. Connect your numberAt easycoexistence.com, run Meta's Embedded Signup and scan the code with the WhatsApp Business app; the app keeps its chats.
  2. Add the server to your coding agentRun the claude mcp add or codex mcp add command, then sign in with /mcp in Claude Code or codex mcp login in Codex.
  3. Ask for credentials and a planHave the agent call list_numbers and get_api_credentials, store the values in .env and propose the receiver before writing it.
  4. Expose the receiver over HTTPSDeploy it, or run a tunnel while developing, and confirm the URL answers from outside your machine.
  5. Route the messagesLet the agent call set_inbound_mode with a Forward URL, or set_webhook_destination for the direct route, once you approve.
  6. Test from your phoneSend the business number a message and check that your agent's reply arrives in the same chat.

Erros comuns

  • Guardar um túnel temporário como destino direto nas primeiras 24 horas. A importação única de contactos e de até 6 meses de conversas da Meta vai para esse URL e perde-se quando o túnel fecha.
  • Definir um destino direto num número com automatizações. O número passa para o modo direto e as automatizações param; use um URL de reencaminhamento, em modo Automatizações, para manter ambos.
  • Enviar para o repositório o .env que o agente escreveu. Acrescente-o ao .gitignore primeiro, porque quem tiver o token de acesso pode enviar mensagens a clientes em nome da empresa.
  • Testar send_message num contacto que não escreveu nas últimas 24 horas. A Meta recusa texto livre fora da janela, pelo que envie primeiro uma mensagem para o número a partir do seu telemóvel.
Fazer isto com a EasyCoexistence

O seu agente corre depois no seu próprio servidor, e cada número é monitorizado 24/7 com alertas. De US$ 9 a US$ 0.75 por número ligado por mês, a descer à medida que acrescenta números, com os primeiros 3 dias grátis.

Perguntas frequentes

Isto funciona no Cursor ou noutras ferramentas de programação?

Sim. Qualquer cliente MCP que se ligue a servidores remotos por Streamable HTTP com OAuth pode usar o mesmo URL, incluindo o Cursor, o VS Code, o Gemini CLI e o Antigravity. Só muda o formato da configuração de um cliente para outro.

Em que linguagem deve ser escrito o agente?

Em qualquer linguagem capaz de servir HTTPS e calcular um HMAC-SHA256. Node.js e Python são as escolhas habituais, e há exemplos testados para ambas, com verificação de assinaturas, tratamento de duplicados e a pausa do telemóvel, na página do agente em Node.js e Python.

Preciso de uma app própria na Meta ou de App Review?

Não. O número entra na Cloud API através da app da Meta da easyCoexistence e fica no portefólio da própria empresa. O token que o seu código envia é o da empresa, pelo que nenhuma app da Meta sua está envolvida.

O agente de programação pode criar os templates de que o seu agente precisa?

Sim, com create_template, e depois get_template_status até a Meta responder, normalmente em minutos e no máximo cerca de 24 horas. O seu agente precisa de um template aprovado para iniciar uma conversa ou para escrever depois de a janela de 24 horas fechar.

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 gratuito

Verificado em