Tutorial passo a passo para criar um agente de IA no WhatsApp com a API oficial da Meta: conta, webhook, código em Python e custos reais em reais.
Especialista em inteligência artificial e transformação digital. Mais de 10 anos ajudando empresas brasileiras a implementar soluções de analytics e IA.
Ver perfil e outros artigos
Sábado, 22h47. Um cliente manda mensagem no WhatsApp da loja perguntando se determinado produto tem em estoque e se dá para retirar no domingo. Em oito segundos chega uma resposta: tem estoque, a loja abre às 9h, e o pedido já fica separado no balcão com o nome dele. Não tem ninguém no caixa nem no celular da empresa. Quem respondeu foi um agente de IA para WhatsApp, rodando na API oficial da Meta, a um custo de centavos por conversa.
Este é o primeiro post de uma série mais técnica do blog: tutoriais de verdade, com código, para quem sabe programar o básico e quer colocar IA em produção sem depender de plataforma pronta. Aqui você vai montar esse agente do zero: conta na Meta, webhook em Python, conexão com o modelo de IA e deploy, com a conta de custos aberta no final.
Um recorte importante antes de começar: o tutorial cobre atendimento receptivo, ou seja, o cliente inicia a conversa e o agente responde. Disparo ativo de mensagens (campanhas, cobranças, notificações) segue outras regras e outros custos, e fica para outro post.
A arquitetura tem quatro peças. O cliente manda mensagem no WhatsApp; a Cloud API da Meta recebe e repassa para o seu webhook (um pequeno servidor Python); o webhook monta o contexto da conversa e pergunta ao modelo de IA o que responder; a resposta volta pelo mesmo caminho até o cliente. Nada além disso: sem fila, sem banco de dados, sem orquestrador. É o mínimo que funciona, e é suficiente para um agente de verdade em produção.
O que você precisa ter:
Tempo estimado: uma tarde para o agente respondendo no número de teste, mais alguns dias de espera da Meta para verificar o negócio e liberar o número definitivo.
A maioria dos tutoriais brasileiros ensina a montar bots de WhatsApp com APIs não oficiais, como a Evolution API, que funcionam por engenharia reversa do WhatsApp Web: você escaneia um QR code e o sistema finge ser um navegador conectado. É a rota popular porque, durante anos, a API oficial era cara e burocrática. Esses dois argumentos envelheceram mal.
O custo caiu muito no caso de atendimento. Desde julho de 2025 a Meta cobra por mensagem, e não mais por conversa, e nessa tabela as mensagens de serviço são gratuitas e sem limite: toda resposta que a sua empresa manda dentro da janela de 24 horas após a última mensagem do cliente não custa nada. O que se paga são mensagens iniciadas pela empresa (marketing, utilidade, autenticação), que não fazem parte deste tutorial.
Atenção a uma mudança com data marcada: a partir de 1º de outubro de 2026 a Meta passa a cobrar também as mensagens de serviço, conforme a documentação oficial de preços. Os valores citados neste tutorial são os de agosto de 2026 e a conta muda a partir dessa data. O passo a passo para calcular a sua exposição está em novas tarifas do WhatsApp em outubro de 2026. O argumento de risco a seguir, esse, não muda.
Já o risco das APIs não oficiais só cresceu. Elas violam os termos comerciais do WhatsApp, e a Meta vem intensificando a detecção e o banimento de números conectados por clientes não oficiais. Para um projeto pessoal, é um risco que você pode escolher correr. Para o canal de atendimento de uma empresa, não é.
Em developers.facebook.com, crie um app do tipo Business e adicione o produto WhatsApp a ele. A Meta gera automaticamente um número de teste e um token de acesso temporário (validade de 24 horas, suficiente para desenvolver).
O número de teste pode conversar com até 5 números cadastrados. Adicione o seu celular pessoal na lista de destinatários e confirme o código que chega por WhatsApp.
Na própria tela do produto WhatsApp, a Meta mostra um comando cURL pronto. Ele tem esta forma:
bashcurl -X POST "https://graph.facebook.com/v23.0/SEU_PHONE_NUMBER_ID/messages" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"messaging_product": "whatsapp", "to": "5511999999999", "type": "text", "text": {"body": "Olá! Agente no ar."}}'
Se a mensagem chegou no seu celular, a metade burocrática do projeto acabou. O resto é código.
Para o agente responder, a Meta precisa avisar o seu servidor sempre que chega mensagem. Isso é o webhook: uma URL sua que a Meta chama. São dois comportamentos no mesmo endpoint.
O primeiro é a verificação: ao cadastrar a URL, a Meta faz um GET com um token combinado e um desafio (hub.challenge), e espera o desafio de volta. Serve para provar que a URL é sua. O segundo é o recebimento: cada mensagem nova chega num POST com um JSON grande, do qual interessam três campos: quem mandou (from), o texto (text.body) e o id da mensagem.
pythonfrom fastapi import FastAPI, Request, Response app = FastAPI() VERIFY_TOKEN = "um-segredo-que-voce-inventa" @app.get("/webhook") async def verificar(request: Request): params = request.query_params if params.get("hub.verify_token") == VERIFY_TOKEN: return Response(content=params.get("hub.challenge")) return Response(status_code=403) @app.post("/webhook") async def receber(request: Request): payload = await request.json() try: msg = payload["entry"][0]["changes"][0]["value"]["messages"][0] telefone, texto = msg["from"], msg["text"]["body"] except (KeyError, IndexError): return {"status": "ignorado"} # status de entrega, não mensagem resposta = gerar_resposta(telefone, texto) # passo 3 enviar_whatsapp(telefone, resposta) # passo 3 return {"status": "ok"}
Em desenvolvimento, exponha o servidor local com ngrok (ngrok http 8000) e cadastre a URL gerada no painel da Meta, marcando o evento messages. Mande um oi do seu celular e veja o JSON chegar no terminal.
Até aqui você tem um eco burro. O agente nasce de três coisas: um system prompt bem escrito, memória da conversa e a chamada ao modelo.
Imagine uma loja de suplementos com 500 pedidos por mês (cenário hipotético; troque pelos dados do seu negócio). O prompt define persona, escopo e, principalmente, os limites:
pythonSYSTEM_PROMPT = """Você é a atendente virtual da loja Suplementos Silva. Responda em português, em tom simpático e direto, mensagens curtas. Você sabe: horário (seg-sáb 9h-19h), endereço, política de troca (7 dias com nota), formas de pagamento e a tabela de produtos abaixo. Regras inegociáveis: - Nunca invente preço, prazo ou estoque. Sem certeza? Diga que vai confirmar com a equipe. - Não prometa nada fora desta lista. - Se o cliente pedir um humano, ou você não souber resolver, responda: "Vou te transferir para nossa equipe, um momento" e pare de responder. Tabela de produtos: [...]"""
Para um MVP, um dicionário em memória guardando o histórico por telefone resolve; a versão com banco de dados fica para o próximo post da série. A chamada ao modelo manda o histórico inteiro mais a mensagem nova, e o envio da resposta reaproveita o mesmo endpoint do cURL do passo 1:
pythonimport os, httpx, anthropic client = anthropic.Anthropic() # lê ANTHROPIC_API_KEY do ambiente historico: dict[str, list] = {} def gerar_resposta(telefone: str, texto: str) -> str: conversa = historico.setdefault(telefone, []) conversa.append({"role": "user", "content": texto}) resposta = client.messages.create( model="claude-haiku-4-5", max_tokens=1024, system=SYSTEM_PROMPT, messages=conversa, ) conteudo = resposta.content[0].text conversa.append({"role": "assistant", "content": conteudo}) return conteudo def enviar_whatsapp(telefone: str, texto: str): httpx.post( f"https://graph.facebook.com/v23.0/{os.environ['PHONE_NUMBER_ID']}/messages", headers={"Authorization": f"Bearer {os.environ['WHATSAPP_TOKEN']}"}, json={"messaging_product": "whatsapp", "to": telefone, "type": "text", "text": {"body": texto}}, )
Pronto: mande "vocês abrem domingo?" do seu celular e o agente responde com base no prompt. É aqui que muitas empresas travam achando que acabou. Faltam duas coisas que separam demo de produção.
O agente só responde em texto livre dentro de 24 horas após a última mensagem do cliente. Fora da janela, a empresa só pode mandar templates pré-aprovados, pagos por mensagem. Consequência prática: desenhe o agente para resolver dentro da conversa, sem depender de "te respondo amanhã". Follow-up ativo é outro projeto.
Quatro mudanças levam o MVP para o mundo real:
whatsapp_business_messaging.E um parágrafo que não é opcional: conversa de cliente é dado pessoal sob a LGPD. Informe no primeiro contato que o atendimento é feito por assistente virtual, colete apenas o necessário, defina prazo de retenção dos históricos e nunca mande esses dados para ferramentas de analytics. Regras de escalonamento para humano e limites do que o agente pode prometer são parte da mesma disciplina; tratei disso em detalhe no post sobre governança de agentes de IA.
Cenário hipotético: 1.000 conversas de atendimento por mês, média de 6 trocas de mensagem cada, sempre iniciadas pelo cliente. Aos preços de agosto de 2026:
Esta conta vale até 30 de setembro de 2026: a partir de 1º de outubro a Meta passa a cobrar as mensagens de serviço que hoje são gratuitas, e até 9 de setembro de 2026 não tinha publicado a nova tarifa.
Total: menos de R$ 150 por mês para um canal que atende 24 horas até 30 de setembro de 2026, e algo entre R$ 270 e R$ 540 a partir de outubro, dependendo da tarifa que a Meta publicar. Plataformas prontas de agente para WhatsApp cobram tipicamente algumas centenas de reais mensais pelo mesmo volume, e faz sentido pagar por elas quando não há ninguém técnico no time; o ponto do tutorial é que a barreira técnica é menor do que o mercado faz parecer. Todos esses preços mudam com frequência, então refaça a conta com as tabelas vigentes antes de decidir.
Pode, mas ele precisa ser desvinculado do aplicativo antes (apague a conta no app, espere a liberação e cadastre na API). O número deixa de funcionar no celular: todo o atendimento passa a acontecer via API. O histórico de conversas do aplicativo não migra, então exporte o que for importante antes.
Só com templates pré-aprovados pela Meta e pagando por mensagem enviada (a categoria marketing custa cerca de US$ 0,06 por mensagem no Brasil na tabela de agosto de 2026). O modelo barato deste tutorial é o receptivo: o cliente inicia e o agente responde na janela de 24 horas, sem custo de template. As mensagens de serviço passam a ser cobradas em 1º de outubro de 2026.
Para desenvolver, não: o número de teste funciona sem verificação, com até 5 destinatários. Para produção, sim: a verificação do negócio (CNPJ e documentos) libera o número definitivo e aumenta progressivamente o limite de conversas diárias.
O risco de banimento por usar cliente não autorizado desaparece, porque você está no canal oficial. Permanecem as regras de conduta: spam, mensagens fora da janela sem template e alto índice de denúncias de usuários podem gerar restrições em qualquer canal. Um agente receptivo e bem-comportado dificilmente esbarra nelas.
O que você montou nesta tarde já é um agente funcional: entende linguagem natural, respeita limites definidos por você e custa quase nada para operar. A barreira de entrada, que até pouco tempo atrás justificava APIs piratas ou plataformas caras, praticamente sumiu. O que separa esse agente de um atendimento confiável em escala não é mais código de integração: é memória persistente, conexão com os seus sistemas (estoque, pedidos, agenda), transbordo bem-feito para humanos e medição de qualidade. Cada um desses vai virar um tutorial desta série.
Se o seu caso é comercial (responder o lead na hora, qualificar, agendar e registrar no CRM), a Waxi já roda esse agente pela API oficial como serviço: veja os agentes de IA para operações comerciais, com teste grátis de qualificação em até 10 contas.
Se você quer o caminho inverso, entender o caso de negócio antes do código, o post sobre automação de atendimento com agentes de IA cobre essa camada. E se quiser pular a curva de aprendizado e colocar um agente desses para atender os seus clientes com quem já fez isso, vamos conversar. A Waxi implementa agentes de IA em produção para empresas brasileiras, do diagnóstico à operação.
MCP, o Model Context Protocol, virou o padrão que conecta a IA aos sistemas da sua empresa. Veja o que é, o que muda na prática e como adotar com segurança.
Governança de agentes de IA para PME brasileira: por que um agente que age sobre dados de cliente sem regras vira risco jurídico na LGPD, e o checklist para evitar isso.
Guia prático para automatizar o atendimento ao cliente com agentes de IA: diferença para chatbots, custos em R$, ferramentas e um plano de 4 semanas.