Sessões

Uma sessão representa uma conversa individual entre um contato e um agente. Sessões são a unidade central da API Conversations V2 — toda mensagem pertence a uma sessão, e toda sessão é atribuída a um agente.

Ciclo de vida da sessão

┌─────────┐    transfer     ┌─────────┐    finish     ┌────────┐
│  open   │ ──────────────► │  open   │ ────────────► │ closed │
│ (AI)    │                 │ (human) │               │        │
└─────────┘                 └─────────┘               └────────┘
     │                                                     ▲
     └─────────────────── finish ──────────────────────────┘

As sessões começam como open e permanecem abertas até serem explicitamente finalizadas. Não há timeout — sua integração controla quando fechar as sessões.

Objeto da sessão

{
  "id": "sess_abc123",
  "contact_id": "5511999888777",
  "organization_id": "org_xyz",
  "conversation_id": "conv_789",
  "thread_id": "thread_001",
  "status": "open",
  "agent": {
    "id": "agent_abc",
    "name": "Support Bot",
    "type": "ai",
    "assistant_id": "asst_123"
  },
  "metadata": {
    "whatsapp_phone_number": "5511999888777",
    "whatsapp_phone_number_id": "phone_id_123"
  },
  "ending_survey_submission_id": null,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}

Campos principais

Field	Description
`id`	Identificador único da sessão
`contact_id`	Identificador do usuário final (tipicamente um número de telefone ou ID externo)
`status`	`"open"` ou `"closed"`
`agent`	O agente atualmente atribuído (IA ou humano). Pode ser `null`.
`metadata`	Pares chave-valor arbitrários para dados de roteamento específicos do canal
`thread_id`	Thread interna usada pelo agente de IA para continuidade de contexto
`conversation_id`	Agrupa sessões do mesmo contato ao longo do tempo

Transições de status

open → open: A transferência muda o agente, não o status
open → closed: Finalize a sessão via POST /sessions/{id}/finish
Uma vez fechada, a sessão não pode ser reaberta. Crie uma nova sessão.

Quando um contato envia uma nova mensagem após sua sessão ser fechada, sua integração deve criar uma nova sessão. Use POST /sessions/search para verificar se já existem sessões abertas primeiro.

Metadata

As sessões carregam um dicionário metadata que sua integração usa para armazenar informações de roteamento específicas do canal (números de telefone, IDs de tickets, IDs de threads). Veja Metadata para convenções.

Relacionados

Guia de Gerenciamento de Sessões — criando, transferindo e finalizando sessões
Referência da API de Sessões — documentação completa dos endpoints