Verboo API: Sua Primeira Mensagem com IA no WhatsApp (Tutorial)

O que vamos construir?

Neste tutorial você vai enviar sua primeira mensagem para um agente de IA da Verboo via API e receber uma resposta inteligente. Sem SDK, sem framework, sem configuração complexa. Um curl no terminal e pronto.

Ao final, você terá um script Python que conversa com o agente mantendo contexto entre mensagens, pronto pra integrar no seu produto.

Quais são os pré-requisitos?

• Conta na Verboo (7 dias grátis, sem cartão)
• API Key gerada no painel (verboo.ai/lab → API Keys → Gerar)
• Um assistente criado (o painel cria um de exemplo automaticamente)
• Terminal com curl ou Python 3.9+

Como funciona a arquitetura da API?

A Verboo expõe duas APIs principais:

API	URL Base	Pra que serve
Generativa	generative-api.verbeux.com.br	Enviar mensagens, criar sessões, receber respostas da IA
Administrativa	api.verbeux.com.br	Gerenciar assistentes, catálogos, documentos, CRM

A autenticação é via header api-key em todas as requisições. Sem OAuth, sem JWT, sem token refresh. Uma chave, todas as APIs.

Como enviar a primeira mensagem (one-shot)?

O endpoint /session/one-shot é o mais simples: você envia uma mensagem e recebe a resposta da IA sem precisar gerenciar sessão. Ideal para integrações rápidas e testes.

curl -X POST "https://generative-api.verbeux.com.br/session/one-shot" \
  -H "api-key: SUA_API_KEY" \
  -F "message=Quais serviços vocês oferecem?" \
  -F "assistant_id=SEU_ASSISTANT_ID" \
  -F "channel=API"

Resposta:

{
  "id": "fcce501d-3963-4367-bf25-8bf97e9d3e7b",
  "response": [
    {
      "data": "Olá! Oferecemos consultas com especialistas, exames laboratoriais e procedimentos. Posso te ajudar a agendar?",
      "type": "text",
      "id": "46eaba39-9709-4399-a877-db19f4c242c0"
    }
  ],
  "isAnythingElse": false
}

Três campos no request. Três campos na resposta. O response é um array porque o agente pode responder com múltiplos blocos (texto + imagem + botões). O type indica o formato: text, image, video ou document.

Onde achar o assistant_id: No painel verboo.ai/lab, abra o assistente e copie o ID na URL ou nos detalhes. Ou via API: GET https://api.verbeux.com.br/assistant/

Como manter conversa com contexto (sessões)?

O one-shot é stateless: cada chamada é independente. Para conversas com memória, use sessões. O fluxo:

1. Criar a sessão

curl -X POST "https://generative-api.verbeux.com.br/session/" \
  -H "api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id": SEU_ASSISTANT_ID}'

Resposta retorna o id da sessão (UUID). Guarde esse ID.

2. Enviar mensagens na sessão

curl -X PUT "https://generative-api.verbeux.com.br/session/SESSION_ID" \
  -H "api-key: SUA_API_KEY" \
  -F "message=Quero agendar uma consulta de dermatologia"

O agente agora tem contexto. Se você enviar uma segunda mensagem dizendo "pode ser amanhã de manhã", ele sabe que você está falando da consulta de dermatologia.

3. Consultar dados da sessão

curl -H "api-key: SUA_API_KEY" \
  "https://generative-api.verbeux.com.br/session/SESSION_ID"

Retorna todo o histórico da conversa, dados do cliente e metadados.

Como fazer isso em Python?

Um script completo com sessão persistente:

import requests
import json

API_KEY = "SUA_API_KEY"
ASSISTANT_ID = 1124  # seu assistant_id
BASE_URL = "https://generative-api.verbeux.com.br"
HEADERS = {"api-key": API_KEY}

# 1. Criar sessão
session = requests.post(
    f"{BASE_URL}/session/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={"assistant_id": ASSISTANT_ID}
).json()

session_id = session["id"]
print(f"Sessão criada: {session_id}\n")

# 2. Conversar em loop
while True:
    user_input = input("Você: ")
    if user_input.lower() in ["sair", "exit"]:
        break
    
    response = requests.put(
        f"{BASE_URL}/session/{session_id}",
        headers=HEADERS,
        data={"message": user_input}
    ).json()
    
    for block in response.get("response", []):
        if block["type"] == "text":
            print(f"\nAgente: {block['data']}\n")

Salve como chat.py e rode:

python3 chat.py

Você tem um chat interativo com IA no terminal, conectado ao seu agente Verboo. Cada mensagem mantém o contexto da conversa.

Como passar dados do seu sistema para o agente?

O parâmetro client_data permite enviar informações do seu sistema para o agente usar na conversa. Por exemplo, se o usuário já está logado no seu app:

response = requests.put(
    f"{BASE_URL}/session/{session_id}",
    headers=HEADERS,
    data={
        "message": "Quero agendar uma consulta",
        "client_data": json.dumps({
            "nome": "João Silva",
            "email": "joao@email.com",
            "plano": "Premium"
        })
    }
).json()

O agente recebe esses dados como contexto. Se ele tiver um webhook configurado para agendar, as variáveis $nome, $email e $plano ficam disponíveis automaticamente no request.

Quais os próximos passos?

Com o básico funcionando, você pode evoluir:

Funcionalidade	Como	Endpoint
Streaming (SSE)	Resposta em tempo real, token por token	PUT /session/{id}/stream
Base de conhecimento	Upload de docs para RAG	POST /ai-document-repository
Catálogo de produtos	Agente consulta e vende	POST /assistant/{id}/catalog
Webhooks	Agente chama seu sistema	Configurar no painel
CRM	Salvar leads automaticamente	POST /assistant/{id}/crm

A API completa está documentada em verboo.ai/pt/docs, com Swagger interativo para testar cada endpoint.

A Verboo entrega tudo isso pronto: API, WhatsApp nativo, deploy em minutos. Crie sua conta grátis e teste.