Conversas

Todos os endpoints abaixo exigem o header Authorization: Bearer pk_... em cada requisição. Quando houver corpo JSON, inclua também Content-Type: application/json.

Base URL: https://api.squados.io/v1

Consulte Autenticação para saber como obter sua chave de API, e Erros para a referência de códigos de erro.

`GET /conversations`

Lista as conversas de um usuário, com suporte a filtros e paginação.

Pelo menos um dos parâmetros user_id ou external_user_id é obrigatório. Se nenhum for enviado, a API retorna 400.

Parâmetros de query

Nome	Tipo	Descrição
`user_id`	uuid	ID interno do usuário no SquadOS.
`external_user_id`	string	ID do usuário no seu sistema (útil para integrar com bases externas).
`agent_id`	uuid	Filtra conversas de um agente específico.
`limit`	int	Número de registros por página. Padrão: `50`. Máximo: `100`.
`offset`	int	Quantidade de registros a pular. Padrão: `0`.

curl -X GET "https://api.squados.io/v1/conversations?external_user_id=usr_abc123&agent_id=AGENT_ID&limit=20&offset=0" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "conversations": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Dúvida sobre faturamento",
      "external_user_id": "usr_abc123",
      "created_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-01T10:35:00Z",
      "channel_source": "widget"
    },
    {
      "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "agent_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Suporte técnico",
      "external_user_id": "usr_abc123",
      "created_at": "2026-05-28T14:20:00Z",
      "updated_at": "2026-05-28T14:55:00Z",
      "channel_source": "widget"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Erros relevantes: 400 se user_id e external_user_id forem ambos omitidos.

`GET /conversations/{conversationId}`

Retorna os detalhes completos de uma conversa.

Parâmetros de caminho

Nome	Tipo	Descrição
`conversationId`	uuid	ID da conversa.

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

Resposta — 200 OK

{
  "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": "widget",
  "ai_enabled": true,
  "user_name": "João Silva",
  "external_user_id": "usr_abc123",
  "credits_used": 12.5,
  "message_count": 8,
  "created_at": "2026-06-01T10:00:00Z",
  "updated_at": "2026-06-01T10:35:00Z"
}

Erros relevantes: 404 se a conversa não existir ou não pertencer à sua organização.

`PATCH /conversations/{conversationId}`

Atualiza configurações de uma conversa: habilita/desabilita a IA, altera o título ou define o nome do usuário para personalização.

Parâmetros de caminho

Nome	Tipo	Descrição
`conversationId`	uuid	ID da conversa.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`ai_enabled`	boolean	Não	Se `false`, a conversa para de gerar respostas automáticas da IA.
`title`	string	Não	Novo título da conversa.
`user_name`	string	Não	Nome do usuário para personalização das respostas.

Exemplo — definir nome do usuário:

{
  "user_name": "João Silva"
}

Exemplo — desativar a IA para intervenção humana:

{
  "ai_enabled": false
}

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

Resposta — 200 OK

{
  "success": true,
  "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ai_enabled": false,
  "user_name": "João Silva"
}

Erros relevantes: 404 se a conversa não existir ou não pertencer à sua organização.

`GET /conversations/{conversationId}/messages`

Retorna o histórico de mensagens de uma conversa, em ordem cronológica.

Parâmetros de caminho

Nome	Tipo	Descrição
`conversationId`	uuid	ID da conversa.

Parâmetros de query

Nome	Tipo	Descrição
`limit`	int	Número de mensagens por página. Padrão: `50`. Máximo: `100`.
`offset`	int	Quantidade de mensagens a pular. Padrão: `0`.

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

Resposta — 200 OK

{
  "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": "Olá, João! O faturamento é realizado todo dia 1º do mês...",
      "created_at": "2026-06-01T10:00:14Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

Erros relevantes: 404 se a conversa não existir ou não pertencer à sua organização.