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.
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 para perto de zero 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, conforme a página oficial de preços da Meta. O que se paga são mensagens iniciadas pela empresa (marketing, utilidade, autenticação), que não fazem parte deste tutorial. Como preço de API muda, confira a tabela vigente antes de planejar; os valores citados aqui são os de agosto de 2026.
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 de graça (e 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:
custo das mensagens de serviço na API oficial
Respostas ao cliente dentro da janela de 24 horas não são cobradas, sem limite de volume, na tabela por mensagem vigente em agosto de 2026
Total: menos de R$ 150 por mês para um canal que atende 24 horas. 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, o agente responde de graça na janela de 24 horas.
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 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.