API de Sessões

Criar sessão

Cria uma nova sessão de conversa.

POST /sessions

Corpo da requisição

Field	Type	Required	Description
`contact_id`	string	Yes	Identificador do usuário final
`contact_name`	string	Yes	Nome de exibição do usuário final
`agent_id`	string	No	Agente a ser atribuído à sessão
`status`	string	No	`"open"` (padrão) ou `"closed"`
`metadata`	object	No	Dados de roteamento específicos do canal

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": {
      "whatsapp_phone_number": "5511999888777",
      "whatsapp_phone_number_id": "phone_id_123"
    }
  }'

response = httpx.post(f"{BASE_URL}/sessions", headers=HEADERS, json={
    "contact_id": "5511999888777",
    "contact_name": "Jane Doe",
    "agent_id": "agent_abc",
    "metadata": {
        "whatsapp_phone_number": "5511999888777",
        "whatsapp_phone_number_id": "phone_id_123",
    },
})
session = response.json()

Response `201`

{
  "id": "sess_abc123",
  "contact_id": "5511999888777",
  "organization_id": "org_xyz",
  "conversation_id": "conv_789",
  "thread_id": null,
  "status": "open",
  "agent": {
    "id": "agent_abc",
    "name": "Support Bot",
    "type": "ai",
    "assistant_id": "asst_123",
    "organization_id": "org_xyz",
    "created_at": "2025-01-15T10:30:00Z"
  },
  "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": null
}

Obter sessão

Recupera uma única sessão pelo ID.

GET /sessions/{session_id}

curl -X GET https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123 \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN"

response = httpx.get(f"{BASE_URL}/sessions/sess_abc123", headers=HEADERS)
session = response.json()

Response `200`

Retorna o objeto completo da sessão.

Erros

Code	Description
`401`	A sessão não existe ou pertence a outra organização

Buscar sessões

Busca sessões com filtros.

POST /sessions/search

Corpo da requisição

Field	Type	Required	Description
`contact_id`	string	No	Filtrar por contato
`status`	string	No	`"open"` ou `"closed"`
`metadata`	object	No	Corresponder pares chave-valor do metadata
`offset`	integer	No	Offset de paginação (padrão: 0)
`limit`	integer	No	Máximo de resultados (padrão: 10)

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": { "whatsapp_phone_number_id": "phone_id_123" }
  }'

response = httpx.post(f"{BASE_URL}/sessions/search", headers=HEADERS, json={
    "contact_id": "5511999888777",
    "status": "open",
    "metadata": {"whatsapp_phone_number_id": "phone_id_123"},
})
sessions = response.json()  # List[Session]

Response `200`

Retorna um array de objetos de sessão.

Atualizar sessão

Atualiza campos da sessão (metadata, status, agente).

PATCH /sessions/{session_id}

Corpo da requisição

Field	Type	Required	Description
`fields.metadata`	object	No	Substituir o metadata da sessão
`fields.status`	string	No	`"open"` ou `"closed"`
`fields.agent_id`	string	No	Alterar o agente atribuído

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_ticket_id": "ticket_new" }
    }
  }'

response = httpx.patch(f"{BASE_URL}/sessions/sess_abc123", headers=HEADERS, json={
    "fields": {
        "metadata": {"mychannel_ticket_id": "ticket_new"},
    },
})

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

Response `200`

Retorna o objeto da sessão atualizado.

Transferir sessão

Altera o agente atribuído a uma sessão.

POST /sessions/{session_id}/transfer

Corpo da requisição

Field	Type	Required	Description
`agent_id`	string	No	Novo ID do agente. `null` remove o agente.

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" }'

response = httpx.post(
    f"{BASE_URL}/sessions/sess_abc123/transfer",
    headers=HEADERS,
    json={"agent_id": "agent_human_456"},
)

Response `200`

Retorna o objeto da sessão atualizado com o novo agente.

Dispara um evento de webhook session.transferred.

Finalizar sessão

Encerra uma sessão.

POST /sessions/{session_id}/finish

Corpo da requisição

Field	Type	Required	Description
`ending_survey_id`	string	No	ID opcional de submissão de pesquisa

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 '{}'

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

Response `200`

Retorna o objeto da sessão com status: "closed".

Dispara um evento de webhook session.finished.

Disparar resposta

Aciona o agente de IA para gerar uma resposta com base no histórico da conversa.

POST /sessions/{session_id}/reply

Corpo da requisição

Field	Type	Required	Description
`debounce_time`	integer	No	Segundos para aguardar por mais mensagens (0-60, padrão: 3)
`starting_node_id`	string	No	Iniciar a partir de um nó específico da conversa
`metadata`	object	No	Metadata adicional para a resposta

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": 5 }'

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

Response `200`

Retorna o objeto da sessão.

Erros

Code	Description
`400`	Sessão não está aberta, sem agente atribuído, agente não é do tipo IA, ou sem thread

Agendar

Agenda uma mensagem ou execução de nó para um momento futuro.

POST /sessions/{session_id}/schedule

Corpo da requisição

Field	Type	Required	Description
`scheduled_for`	datetime	Yes	Data e hora ISO 8601 para execução
`config`	object	Yes	Configuração do agendamento (veja abaixo)

Configuração de mensagem:

{
  "type": "message",
  "message": { "type": "text", "text": "Follow-up!" }
}

Configuração de nó:

{
  "type": "node",
  "node_id": "node_abc"
}

curl -X POST https://services.antonnia.com/conversations/v2/api/v1/sessions/sess_abc123/schedule \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_for": "2025-01-15T14:00:00Z",
    "config": {
      "type": "message",
      "message": { "type": "text", "text": "Just checking in — need anything else?" }
    }
  }'

response = httpx.post(
    f"{BASE_URL}/sessions/sess_abc123/schedule",
    headers=HEADERS,
    json={
        "scheduled_for": "2025-01-15T14:00:00Z",
        "config": {
            "type": "message",
            "message": {"type": "text", "text": "Just checking in — need anything else?"},
        },
    },
)

Response `200`

Retorna um objeto SessionSchedule.

API de Sessões

On this page