Gerenciamento de Sessões

Sessões são a unidade principal de conversa na Antonnia. Este guia cobre o ciclo de vida completo da sessão: criação, busca, transferência e encerramento.

Criando sessões

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": "5511999888777",
    "contact_name": "Jane Doe",
    "agent_id": "agent_abc",
    "metadata": {
      "mychannel_instance_id": "inst_789",
      "mychannel_user_id": "ext_user_456"
    }
  }'

session = httpx.post(f"{BASE_URL}/sessions", headers=HEADERS, json={
    "contact_id": "5511999888777",
    "contact_name": "Jane Doe",
    "agent_id": "agent_abc",
    "metadata": {
        "mychannel_instance_id": "inst_789",
        "mychannel_user_id": "ext_user_456",
    },
}).json()

Sempre defina metadata com as informações de roteamento do seu canal no momento da criação. Esses dados são necessários posteriormente para a entrega de mensagens de saída.

Buscando sessões

Antes de criar uma nova sessão, busque por uma sessão aberta existente para o mesmo contato:

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/search \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "5511999888777",
    "status": "open",
    "metadata": { "mychannel_instance_id": "inst_789" }
  }'

sessions = httpx.post(f"{BASE_URL}/sessions/search", headers=HEADERS, json={
    "contact_id": "5511999888777",
    "status": "open",
    "metadata": {"mychannel_instance_id": "inst_789"},
}).json()

if sessions:
    session = sessions[0]  # Use existing session
else:
    session = create_new_session(...)  # Create new

Filtros de busca

Field	Descrição
`contact_id`	Filtrar por identificador do contato
`status`	`"open"` ou `"closed"`
`metadata`	Corresponder pares chave-valor específicos de metadata
`offset` / `limit`	Paginação (limite padrão: 100)

Padrão get-or-create

O padrão utilizado por todas as integrações da Antonnia:

async def get_or_create_session(contact_id: str, instance_id: str, contact_name: str):
    # 1. Search for existing open session on this channel instance
    sessions = httpx.post(f"{BASE_URL}/sessions/search", headers=HEADERS, json={
        "contact_id": contact_id,
        "status": "open",
        "metadata": {"mychannel_instance_id": instance_id},
    }).json()

    if sessions:
        return sessions[0]

    # 2. Create new session
    return httpx.post(f"{BASE_URL}/sessions", headers=HEADERS, json={
        "contact_id": contact_id,
        "contact_name": contact_name,
        "agent_id": AGENT_ID,
        "metadata": {
            "mychannel_instance_id": instance_id,
            "mychannel_user_id": contact_id,
        },
    }).json()

Sempre envolva isso em um lock distribuído para evitar a criação de sessões duplicadas quando mensagens chegam simultaneamente. Veja o Guia de Integração de Canal.

Transferindo sessões

A transferência altera o agente atribuído a uma sessão. A sessão permanece aberta.

# Transfer to a human agent
curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/transfer \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agent_human_456" }'

# Transfer to a human agent
httpx.post(
    f"{BASE_URL}/sessions/{session_id}/transfer",
    headers=HEADERS,
    json={"agent_id": "agent_human_456"},
)

Um evento de webhook session.transferred é disparado quando a transferência é concluída.

Finalizando sessões

Feche uma sessão quando a conversa estiver completa:

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

httpx.post(
    f"{BASE_URL}/sessions/{session_id}/finish",
    headers=HEADERS,
    json={},
)

Opcionalmente, você pode anexar uma pesquisa de satisfação:

POST /sessions/{session_id}/finish
{ "ending_survey_id": "survey_abc" }

Um evento de webhook session.finished é disparado quando a sessão é fechada.

Sessões fechadas não podem ser reabertas. Quando o mesmo contato enviar uma nova mensagem, crie uma nova sessão.

Atualizando metadata da sessão

curl -X PATCH https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "metadata": {
        "mychannel_instance_id": "inst_789",
        "mychannel_user_id": "ext_user_456",
        "mychannel_ticket_id": "ticket_new"
      }
    }
  }'

httpx.patch(f"{BASE_URL}/sessions/{session_id}", headers=HEADERS, json={
    "fields": {
        "metadata": {
            "mychannel_instance_id": "inst_789",
            "mychannel_user_id": "ext_user_456",
            "mychannel_ticket_id": "ticket_new",
        },
    },
})

Atualizações de metadata substituem o objeto de metadata inteiro. Sempre inclua todas as chaves existentes.