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:

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

.env:

text
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

Publicar no Fly.io, Render ou Railway

Adicionar monitoramento via webhooks (mensagem entregue, erro, execucao de ferramenta)

Integrar com CRM/ERP usando os metadados enviados pela Zavu

Quer ver em acao? Agende uma demo ou participe do Discord.