whatsapp-flows

Cidadão (WhatsApp) → Twilio → POST /api/v1/webhook/whatsapp/chat → TaNaMaoAgent → Resposta

Olá! Sou o assistente do Tá na Mão.

Posso te ajudar com:
1️⃣ Ver meus benefícios
2️⃣ Documentos que preciso
3️⃣ Achar CRAS perto de mim
4️⃣ Dinheiro esquecido
5️⃣ Farmácia Popular

Manda o número da opção!

Para consultar seus benefícios, preciso do seu CPF.

Pode mandar aqui que é seguro. Só uso pra consultar, não guardo.

(Manda só os 11 números)

{{nome}}, achei seus dados!

✅ Bolsa Família: R$ {{valor}}/mês
📋 CadÚnico: Atualizado até {{data}}

Quer saber de mais benefícios que você pode ter direito?
Manda SIM ou NÃO.

Para pedir {{beneficio}}, leve ao CRAS:

📄 CPF de todos da família
📄 Certidão de nascimento ou casamento
📄 Comprovante de onde mora
📄 Carteira de trabalho
📄 Comprovante de renda (se tiver)

O CRAS mais perto de você fica em:
📍 {{endereco_cras}}
📞 {{telefone_cras}}

⚠️ {{nome}}, seu CadÚnico precisa ser atualizado!

Se não atualizar até {{data_limite}}, seus benefícios podem ser suspensos.

Leve seus documentos ao CRAS:
📍 {{endereco_cras}}

Horário: {{horario_funcionamento}}

# backend/app/agent/whatsapp/flows/consulta_beneficio.py

FLOW_CONSULTA = {
    "inicio": {
        "mensagem": "Vou consultar seus benefícios. Manda seu CPF (só números).",
        "espera": "cpf",
        "proximo": "validar_cpf"
    },
    "validar_cpf": {
        "acao": "validar_cpf_tool",
        "sucesso": "consultar",
        "erro": {
            "mensagem": "CPF inválido. Confere e manda de novo (11 números).",
            "voltar": "inicio"
        }
    },
    "consultar": {
        "acao": "consultar_beneficio_tool",
        "sucesso": "mostrar_resultado",
        "erro": {
            "mensagem": "Não consegui consultar agora. Tenta de novo em 5 minutos.",
            "voltar": "fim"
        }
    },
    "mostrar_resultado": {
        "mensagem": "template_resultado",
        "botoes": [
            {"texto": "Ver mais benefícios", "proximo": "elegibilidade"},
            {"texto": "Documentos necessários", "proximo": "checklist"},
            {"texto": "Achar CRAS", "proximo": "buscar_cras"}
        ]
    }
}

FLOW_CRAS = {
    "inicio": {
        "mensagem": "Manda sua localização 📍 ou seu CEP que acho o CRAS mais perto.",
        "espera": "localizacao_ou_cep",
        "proximo": "buscar"
    },
    "buscar": {
        "acao": "buscar_cras_tool",
        "sucesso": "mostrar_cras",
        "erro": {
            "mensagem": "Não achei CRAS perto. Manda outro CEP ou sua cidade.",
            "voltar": "inicio"
        }
    },
    "mostrar_cras": {
        "mensagem": "template_cras_proximo",
        "botoes": [
            {"texto": "Ver no mapa", "acao": "enviar_localizacao"},
            {"texto": "Ligar pro CRAS", "acao": "enviar_telefone"},
            {"texto": "O que levar", "proximo": "checklist_cras"}
        ]
    }
}

# backend/app/routers/webhook.py
@router.post("/whatsapp/chat")
async def whatsapp_webhook(request: Request):
    form = await request.form()
    from_number = form.get("From")  # whatsapp:+5511999999999
    body = form.get("Body", "").strip()
    media_url = form.get("MediaUrl0")  # foto de receita, etc.
    latitude = form.get("Latitude")
    longitude = form.get("Longitude")

    # Recuperar sessão do Redis
    session = await get_whatsapp_session(from_number)

    # Processar pelo fluxo ativo ou agente
    if session.active_flow:
        response = await process_flow(session, body, media_url, latitude, longitude)
    else:
        response = await agent.process(body, session_id=from_number)

    # Enviar resposta via Twilio
    return await send_whatsapp_response(from_number, response)

# backend/app/services/whatsapp_service.py
from twilio.rest import Client

async def enviar_menu(to: str, texto: str, botoes: list[dict]):
    """Envia mensagem com botões interativos."""
    client = Client(TWILIO_SID, TWILIO_TOKEN)
    message = client.messages.create(
        from_=f"whatsapp:{TWILIO_WHATSAPP_NUMBER}",
        to=to,
        body=texto,
        # Botões interativos (máximo 3)
    )
    return message.sid

async def enviar_localizacao(to: str, lat: float, lng: float, nome: str):
    """Envia localização do CRAS/farmácia."""
    client = Client(TWILIO_SID, TWILIO_TOKEN)
    message = client.messages.create(
        from_=f"whatsapp:{TWILIO_WHATSAPP_NUMBER}",
        to=to,
        body=f"📍 {nome}",
        persistent_action=[f"geo:{lat},{lng}|{nome}"]
    )
    return message.sid

# Redis: sessão WhatsApp com TTL de 24h
async def get_whatsapp_session(phone: str) -> WhatsAppSession:
    key = f"wa_session:{phone}"
    data = await redis.get(key)
    if data:
        return WhatsAppSession.parse_raw(data)
    session = WhatsAppSession(phone=phone)
    await redis.setex(key, 86400, session.json())
    return session

async def update_whatsapp_session(session: WhatsAppSession):
    key = f"wa_session:{session.phone}"
    await redis.setex(key, 86400, session.json())

# Limite: 1 mensagem por segundo por número, 1000/dia por número
WHATSAPP_RATE_LIMITS = {
    "por_segundo": 1,
    "por_dia": 1000,
    "janela_conversa": 24 * 60 * 60,  # 24h após última mensagem do usuário
}

TWILIO_ACCOUNT_SID=ACxxxxx
TWILIO_AUTH_TOKEN=xxxxx
TWILIO_WHATSAPP_NUMBER=+14155238886
WHATSAPP_WEBHOOK_URL=https://api.tanamao.com.br/api/v1/webhook/whatsapp/chat