---
title: Agente de IA para WhatsApp com FastAPI e Zavu
description: Construa um agente de WhatsApp assincrono usando FastAPI e o AI Gateway da Zavu. Inclui setup, webhooks e automacoes sem API keys externas.
date: 2025-12-17
author: Victor Villalobos
locale: pt
source: https://www.zavu.dev/pt/blog/whatsapp-ai-agents-fastapi
tags: Agentes IA, WhatsApp, FastAPI, Python
---

# Agente de IA para WhatsApp com FastAPI e Zavu

# Agente de IA para WhatsApp com FastAPI e Zavu

Use FastAPI para receber webhooks de WhatsApp e delegar as respostas a um agente gerenciado pela Zavu. Tudo em modo async e com suporte aos principais modelos de IA.

## Pre-requisitos

- Python 3.10+
- FastAPI + Uvicorn
- Conta Zavu com sender WhatsApp aprovado

## Setup

```bash
mkdir whatsapp-agent && cd whatsapp-agent
python -m venv venv && source venv/bin/activate
pip install fastapi uvicorn zavudev python-dotenv
```

Estrutura sugerida:

```
app/
├── main.py
├── models.py
├── services.py
└── webhook.py
```

`.env`:

```
ZAVUDEV_API_KEY=suachave
ZAVU_WEBHOOK_SECRET=segredo
ZAVU_SENDER_ID=sender_xxx
```

`app/services.py`:

```python
from zavudev import Zavudev
import os

client = Zavudev(api_key=os.environ['ZAVUDEV_API_KEY'])

async def create_agent(sender_id: str, name: str):
    response = client.senders.agent.create(
        sender_id=sender_id,
        name=name,
        provider='zavu',
        model='gpt-4o-mini',
        system_prompt='Ajude clientes com comunicacao omnichannel',
        include_contact_metadata=True,
        enabled=True
    )
    return response.agent

async def reply_to_message(message_id: str, contact_id: str):
    return client.senders.agent.reply(
        sender_id=os.environ['ZAVU_SENDER_ID'],
        message_id=message_id,
        contact_id=contact_id
    )
```

## Modelos Pydantic

`app/models.py`:

```python
from enum import Enum
from pydantic import BaseModel

class MessageType(str, Enum):
    TEXT = 'text'
    IMAGE = 'image'

class WhatsappEvent(BaseModel):
    type: str
    data: dict
```

## Webhook com verificacao

`app/webhook.py`:

```python
import hmac
import hashlib
from fastapi import APIRouter, Header, HTTPException
from .models import WhatsappEvent
from .services import reply_to_message
import os

router = APIRouter()

@router.post('/webhooks/whatsapp')
async def handle_webhook(event: WhatsappEvent, x_zavu_signature: str = Header(None), raw_body: bytes = b''):
    secret = os.environ['ZAVU_WEBHOOK_SECRET'].encode()
    digest = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(digest, x_zavu_signature or ''):
        raise HTTPException(status_code=401)

    if event.type == 'message.received':
        await reply_to_message(
            message_id=event.data['message']['id'],
            contact_id=event.data['contact']['id']
        )

    return { 'status': 'ok' }
```

`app/main.py`:

```python
from fastapi import FastAPI
from . import webhook

app = FastAPI()
app.include_router(webhook.router)
```

Execute com `uvicorn app.main:app --reload` e exponha via `ngrok http 8000`.

## Recursos do agente

- **Modelos disponiveis**: gpt-4o/mini, claude-3-5-sonnet, gemini-pro, mistral-large.
- **Bases de conhecimento**: anexe FAQs e docs para respostas contextuais.
- **Ferramentas customizadas**: APIs internas para consultar pedidos, estoque ou CRM.
- **Fluxos**: defina fallback para SMS/email quando WhatsApp estiver fora da janela.

## Usando chaves proprias (opcional)

```python
client.senders.agent.update(
    sender_id=sender,
    provider='bring-your-own',
    integrations={'openai': { 'api_key': os.getenv('OPENAI_API_KEY') }}
)
```

## Proximos passos

1. Publicar no Fly.io, Render ou Railway
2. Adicionar monitoramento via webhooks (mensagem entregue, erro, execucao de ferramenta)
3. Integrar com CRM/ERP usando os metadados enviados pela Zavu

Quer ver em acao? [Agende uma demo](/schedule?service=demo) ou participe do [Discord](https://discord.gg/ZxE8DYkveh).