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.
Flag do Claude Code que carrega um servidor em todos os seus projetos; o âmbito local predefinido carrega-o apenas onde foi adicionado.
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.
O que um destino webhook direto tem de usar, e tem de devolver hub.challenge no handshake GET da Meta.
Quanto tempo um passo «Chamar o meu webhook» espera pelo {"reply"} do seu endpoint antes de o passo falhar.
Janela de atendimento ao cliente após a última mensagem do utilizador; fora dela, a Meta só aceita mensagens template.
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.
# 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 listQue 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.
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:
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
- Connect your numberAt easycoexistence.com, run Meta's Embedded Signup and scan the code with the WhatsApp Business app; the app keeps its chats.
- 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.
- 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.
- Expose the receiver over HTTPSDeploy it, or run a tunnel while developing, and confirm the URL answers from outside your machine.
- Route the messagesLet the agent call set_inbound_mode with a Forward URL, or set_webhook_destination for the direct route, once you approve.
- 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.
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 gratuitoVerificado em