Início Rápido

Este guia mostra como criar uma sessão, enviar uma mensagem e acionar uma resposta da IA.

Pré-requisitos

Uma organização Antonnia com um token de API (sk_live_...)
Um agente de IA configurado na sua organização

Passos

Crie uma sessão

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "user_123",
    "contact_name": "Jane Doe",
    "agent_id": "agent_abc",
    "metadata": {
      "channel_type": "my_channel",
      "channel_user_id": "ext_user_456"
    }
  }'

import httpx

BASE_URL = "https://services.antonnia.com/conversations/v2/api/v1"
HEADERS = {
    "Authorization": "Bearer sk_live_YOUR_TOKEN",
    "Content-Type": "application/json",
}

response = httpx.post(f"{BASE_URL}/sessions", headers=HEADERS, json={
    "contact_id": "user_123",
    "contact_name": "Jane Doe",
    "agent_id": "agent_abc",
    "metadata": {
        "channel_type": "my_channel",
        "channel_user_id": "ext_user_456",
    },
})
session = response.json()
session_id = session["id"]

Resposta:

{
  "id": "sess_abc123",
  "contact_id": "user_123",
  "status": "open",
  "agent": {
    "id": "agent_abc",
    "name": "Support Bot",
    "type": "ai"
  },
  "metadata": {
    "channel_type": "my_channel",
    "channel_user_id": "ext_user_456"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Envie uma mensagem do usuário

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "type": "text", "text": "Hello, I need help with my order" },
    "role": "user",
    "provider_message_id": "ext_msg_001"
  }'

response = httpx.post(
    f"{BASE_URL}/sessions/{session_id}/messages",
    headers=HEADERS,
    json={
        "content": {"type": "text", "text": "Hello, I need help with my order"},
        "role": "user",
        "provider_message_id": "ext_msg_001",
    },
)
message = response.json()

Acione a resposta da IA

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/reply \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "debounce_time": 3 }'

httpx.post(
    f"{BASE_URL}/sessions/{session_id}/reply",
    headers=HEADERS,
    json={"debounce_time": 3},
)

O agente de IA processa a conversa e gera uma resposta. Você receberá um webhook message.created com role: "assistant" contendo a resposta da IA.

Processe o webhook de saída

Quando a IA responde, a Antonnia dispara um evento message.created para o seu endpoint de webhook:

{
  "type": "message.created",
  "data": {
    "object": {
      "id": "msg_xyz789",
      "session_id": "sess_abc123",
      "role": "assistant",
      "content": { "type": "text", "text": "I'd be happy to help with your order. Could you share your order number?" },
      "delivery_status": "pending"
    }
  }
}

Sua integração deve:

Entregar esta mensagem através do seu canal
Atualizar a mensagem com o ID do provedor e o status de entrega

curl -X PATCH https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/messages/msg_xyz789 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_message_id": "ext_msg_002",
    "delivery_status": "sent"
  }'

httpx.patch(
    f"{BASE_URL}/sessions/{session_id}/messages/msg_xyz789",
    headers=HEADERS,
    json={
        "provider_message_id": "ext_msg_002",
        "delivery_status": "sent",
    },
)

Próximos passos

Guia de Integração de Canal — guia completo com locking, metadata e tratamento de erros
Referência da API — documentação completa dos endpoints
Padrão WhatsApp — exemplo de integração do mundo real