Conversas

Os endpoints de Conversas permitem localizar atendimentos de uma organização, consultar seus dados, alterar o estado da conversa e percorrer o histórico de mensagens.

Todas as chamadas exigem Authorization: Bearer pk_.... Em requisições com JSON, envie também Content-Type: application/json. A base é https://api.squados.io/v1; consulte Autenticação e Erros para os contratos compartilhados.

Listar conversas

GET /conversations

Informe pelo menos um dos filtros de identidade: user_id ou external_user_id. A API restringe os resultados à organização do token e ordena as conversas por updated_at, da mais recente para a mais antiga.

Query	Tipo	Obrigatório	Descrição
user_id	string (UUID)	Condicional	ID interno de um perfil do SquadOS. É usado principalmente em conversas internas do Hub.
external_user_id	string	Condicional	Identificador do contato no sistema integrado.
agent_id	string (UUID)	Não	Mantém somente conversas associadas a esse agente. Conversas sem agente têm agent_id: null.
limit	inteiro	Não	Tamanho da página. Padrão: 50; máximo: 100. Valores acima de 100 são reduzidos para 100.
offset	inteiro	Não	Quantidade de registros ignorados antes da página. Padrão: 0.

Se user_id e external_user_id forem enviados juntos, os dois filtros precisam corresponder à conversa. agent_id também é combinado com os filtros de identidade.

curl "https://api.squados.io/v1/conversations?external_user_id=crm-cliente-123&limit=20&offset=0" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta 200

{
  "conversations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Dúvida sobre faturamento",
      "external_user_id": "crm-cliente-123",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:35:00Z",
      "channel_source": "api"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

total é o total de conversas que correspondem aos filtros, não apenas o tamanho da página atual. Uma busca válida sem resultados retorna 200, conversations: [] e total: 0. Sem user_id e sem external_user_id, a API retorna 400 invalid_request.

Consultar uma conversa

GET /conversations/{conversationId}

Retorna detalhes e a contagem de mensagens. O UUID precisa identificar uma conversa da organização do token.

curl "https://api.squados.io/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta 200

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "agent_name": "Suporte ao Cliente",
  "title": "Dúvida sobre faturamento",
  "status": "active",
  "channel_source": "api",
  "ai_enabled": true,
  "user_name": "Maria Silva",
  "external_user_id": "crm-cliente-123",
  "credits_used": 12.5,
  "message_count": 8,
  "created_at": "2026-06-01T10:00:00Z",
  "updated_at": "2026-06-01T10:35:00Z"
}

Uma conversa de uma caixa de atendimento humano pode retornar agent_id: null e agent_name: null. Um UUID malformado retorna 400 invalid_request; uma conversa inexistente ou de outra organização retorna 404 not_found.

Atualizar uma conversa

PATCH /conversations/{conversationId}

O PATCH aceita alterações de estado, controle de IA e campos de identificação. Você pode enviar um ou mais campos no mesmo corpo.

Campo	Tipo	Descrição
status	active | completed	completed conclui a conversa; active reabre uma conversa concluída.
ai_enabled	boolean	Liga ou desliga respostas automáticas. Quando false, mensagens ainda podem ser registradas, mas o agente não responde automaticamente.
title	string	Substitui o título da conversa.
user_name	string	Substitui o nome na conversa e também no contato externo vinculado, quando ele existe.

Controle de estado e IA

• {"ai_enabled": false} desliga a IA sem concluir a conversa.
• {"status": "completed"} conclui a conversa e deixa ai_enabled: false.
• {"status": "active"} reabre a conversa. O resultado de ai_enabled depende do modo de resolução guardado na conversa.
• {"status": "active", "ai_enabled": false} reabre e mantém o atendimento humano.
• {"status": "active", "ai_enabled": true} reabre e solicita que a IA volte a responder. A operação pode falhar se não houver um agente disponível para assumir.
• Se status: "completed" for enviado com ai_enabled, a conclusão prevalece e a resposta continua com ai_enabled: false.

Cuidado

ai_enabled e status representam coisas diferentes. Desligar a IA não conclui a conversa; concluir altera o ciclo do atendimento e dispara o processamento de encerramento em segundo plano.

curl -X PATCH "https://api.squados.io/v1/conversations/CONVERSATION_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"status":"active","ai_enabled":false}'

Resposta 200

{
  "success": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "active",
  "ai_enabled": false
}

A resposta inclui success e conversation_id, mais os campos de estado processados. Campos não envolvidos são omitidos. Por exemplo, um PATCH somente com title retorna apenas success e conversation_id; um PATCH com user_name também devolve user_name.

Corpo malformado, UUID inválido ou status fora de active/completed retorna 400 invalid_request. Conversa ausente ou de outra organização retorna 404 not_found. Uma falha ao concluir, reabrir ou alterar a IA retorna 500 internal_error.

Ler o histórico de mensagens

GET /conversations/{conversationId}/messages

Retorna mensagens em ordem cronológica, da mais antiga para a mais recente.

Query	Tipo	Descrição
limit	inteiro	Tamanho da página. Padrão: 50. O handler atual não aplica um máximo.
offset	inteiro	Quantidade de mensagens ignoradas. Padrão: 0.

Nota

Embora o Swagger ainda informe máximo de 100 mensagens, o endpoint atual não limita limit. Para respostas previsíveis, use páginas moderadas, como 50 ou 100 itens.

curl "https://api.squados.io/v1/conversations/CONVERSATION_ID/messages?limit=50&offset=0" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta 200

{
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "messages": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "role": "user",
      "content": "Olá, como funciona o faturamento mensal?",
      "created_at": "2026-06-01T10:00:10Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
      "role": "assistant",
      "content": "O faturamento é realizado no início de cada ciclo.",
      "created_at": "2026-06-01T10:00:14Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

Este endpoint devolve apenas id, role, content e created_at de cada mensagem. Anexos, passos de execução, modelo e metadados não fazem parte desta resposta.

Paginação

Em GET /conversations, avance offset de limit em limit até offset >= total. O histórico de mensagens não devolve total; nele, encerre quando messages vier vazio ou com menos itens que o limit solicitado.