Conversas

Atendimentos e as mensagens trocadas neles, em todos os canais.

Operação	Endpoint
Listar conversas	`GET /conversations`
Ler uma conversa	`GET /conversations/{id}`
Listar mensagens de uma conversa	`GET /conversations/{id}/messages`

Listar conversas

GET/conversations

Lista as conversas da organização, da mais recente para a mais antiga (pela data de início). Use updated_after para sincronizar só o que mudou desde a última leitura.

Permissão exigida na chave: conversas:read.

Parâmetros de consulta

Nome	Tipo	Obrigatório	Descrição
`limit`	inteiro	não	Quantos itens por página, de 1 a 100. Padrão 50.
`cursor`	texto	não	Valor de `next_cursor` da página anterior. Omita para a primeira página.
`status`	`open`, `pending`, `snoozed`, `resolved`, `closed`	não	Só conversas nesta situação.
`channel`	`whatsapp`, `voice`, `instagram`, `messenger`, `telegram`, `email`, `sms`, `webchat`, `app`	não	Só conversas deste canal.
`contact_id`	texto	não	Só conversas deste contato.
`created_after`	texto	não	Só conversas iniciadas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.
`created_before`	texto	não	Só conversas iniciadas antes deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.
`updated_after`	texto	não	Só conversas alteradas a partir deste instante. ISO 8601, por exemplo 2026-11-01T00:00:00Z.

Resposta 200

Uma página de objetos Conversation em data, e next_cursor para a próxima. Veja Paginação.

Erros

Status	Quando
`400`	`invalid_parameter`: Parâmetro inválido.
`401`	`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.
`403`	`insufficient_scope`: Escopo insuficiente.
`429`	`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.
`500`	`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.

O corpo segue o formato de Erros.

Exemplo

curl "https://app.conectaai.io/api/v1/conversations" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"

Resposta 200:

{
  "data": [
    {
      "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "contact_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "channel": "whatsapp",
      "channel_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "status": "open",
      "protocol": "20261109-0042",
      "origin": "inbound",
      "handled_by": "ai",
      "assigned_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "department_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "active_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "priority": 0,
      "tags": [
        "sem-conexao"
      ],
      "summary": "Cliente sem conexão desde a manhã. A IA verificou o contrato e abriu chamado técnico.",
      "created_at": "2026-11-09T14:32:05.120Z",
      "updated_at": "2026-11-09T14:32:05.120Z",
      "last_message_at": "2026-11-09T14:32:05.120Z",
      "first_response_at": "2026-11-09T14:32:05.120Z",
      "escalated_at": "2026-11-09T14:32:05.120Z",
      "resolved_at": "2026-11-09T14:32:05.120Z"
    }
  ],
  "next_cursor": null
}

Ler uma conversa

GET/conversations/{id}

Devolve uma conversa da organização pelo identificador.

Permissão exigida na chave: conversas:read.

Parâmetros de caminho

Nome	Tipo	Obrigatório	Descrição
`id`	texto	sim	Identificador do recurso.

Resposta 200

Um objeto Conversation.

Erros

Status	Quando
`401`	`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.
`403`	`insufficient_scope`: Escopo insuficiente.
`404`	`not_found`: Recurso não encontrado.
`429`	`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.
`500`	`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.

O corpo segue o formato de Erros.

Exemplo

curl "https://app.conectaai.io/api/v1/conversations/<id>" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"

Resposta 200:

{
  "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "contact_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "channel": "whatsapp",
  "channel_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "status": "open",
  "protocol": "20261109-0042",
  "origin": "inbound",
  "handled_by": "ai",
  "assigned_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "department_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "active_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
  "priority": 0,
  "tags": [
    "sem-conexao"
  ],
  "summary": "Cliente sem conexão desde a manhã. A IA verificou o contrato e abriu chamado técnico.",
  "created_at": "2026-11-09T14:32:05.120Z",
  "updated_at": "2026-11-09T14:32:05.120Z",
  "last_message_at": "2026-11-09T14:32:05.120Z",
  "first_response_at": "2026-11-09T14:32:05.120Z",
  "escalated_at": "2026-11-09T14:32:05.120Z",
  "resolved_at": "2026-11-09T14:32:05.120Z"
}

Listar mensagens de uma conversa

GET/conversations/{id}/messages

Lista as mensagens de uma conversa em ordem cronológica, da primeira para a última. Notas internas da equipe não aparecem.

Permissão exigida na chave: conversas:read.

Parâmetros de caminho

Nome	Tipo	Obrigatório	Descrição
`id`	texto	sim	Identificador do recurso.

Parâmetros de consulta

Nome	Tipo	Obrigatório	Descrição
`limit`	inteiro	não	Quantos itens por página, de 1 a 100. Padrão 50.
`cursor`	texto	não	Valor de `next_cursor` da página anterior. Omita para a primeira página.

Resposta 200

Uma página de objetos Message em data, e next_cursor para a próxima. Veja Paginação.

Erros

Status	Quando
`400`	`invalid_parameter`: Parâmetro inválido.
`401`	`unauthenticated`: Não autenticado. `invalid_credential`: Credencial inválida.
`403`	`insufficient_scope`: Escopo insuficiente.
`404`	`not_found`: Recurso não encontrado.
`429`	`rate_limited`: Limite de requisições atingido. Tente de novo depois do tempo indicado em Retry-After.
`500`	`internal_error`: Erro interno. Tente de novo; se persistir, fale com o suporte informando o X-Request-Id.

O corpo segue o formato de Erros.

Exemplo

curl "https://app.conectaai.io/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer $CONECTAAI_API_KEY"

Resposta 200:

{
  "data": [
    {
      "id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "conversation_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "author_type": "customer",
      "author_user_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "author_agent_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "text": null,
      "caption": null,
      "media": {
        "kind": "texto",
        "mime_type": "image/jpeg",
        "file_name": null,
        "duration_sec": 0
      },
      "status": "sending",
      "reply_to_message_id": "8f0c2a4e-1b7d-4c55-9a1e-3d2f6b7c8a90",
      "deleted": false,
      "created_at": "2026-11-09T14:32:05.120Z"
    }
  ],
  "next_cursor": null
}

Objeto Conversation

Um atendimento, do primeiro contato à resolução.

Campo	Tipo	Descrição
`id`	texto	Identificador da conversa.
`contact_id`	texto	Contato com quem a conversa acontece. Leia em GET /contacts/{id}.
`channel`	`whatsapp`, `voice`, `instagram`, `messenger`, `telegram`, `email`, `sms`, `webchat`, `app`	Canal do atendimento: whatsapp, voice (telefone), instagram, messenger, telegram, email, sms, webchat (chat do site) ou app (app do assinante).
`channel_id`	texto ou `null`	Canal configurado em que a conversa entrou.
`status`	`open`, `pending`, `snoozed`, `resolved`, `closed`	open: em andamento. pending: aguardando o cliente. snoozed: adiada pela equipe. resolved: resolvida. closed: encerrada.
`protocol`	texto ou `null`	Número de protocolo mostrado ao cliente.
`origin`	`inbound`, `template`, `campaign`	inbound: o cliente iniciou. template: a equipe iniciou por modelo aprovado. campaign: veio de uma campanha.
`handled_by`	`ai`, `human`, `hybrid`	Quem conduz a conversa agora: ai (agente de IA), human (atendente) ou hybrid.
`assigned_user_id`	texto ou `null`	Atendente responsável, quando há.
`department_id`	texto ou `null`	Setor da conversa, quando há.
`active_agent_id`	texto ou `null`	Agente de IA que conduz a conversa, quando há.
`priority`	inteiro	Prioridade definida pela equipe. 0 é a padrão.
`tags`	lista de texto	Etiquetas aplicadas, pelo slug. A lista completa está em GET /tags.
`summary`	texto ou `null`	Resumo da conversa gerado pela IA, quando já existe.
`created_at`	texto	Quando a conversa começou. Data e hora em ISO 8601, UTC.
`updated_at`	texto	Última alteração da conversa. Data e hora em ISO 8601, UTC.
`last_message_at`	texto	Última mensagem trocada. Data e hora em ISO 8601, UTC.
`first_response_at`	texto ou `null`	Primeira resposta ao cliente, da IA ou de gente. Data e hora em ISO 8601, UTC.
`escalated_at`	texto ou `null`	Quando a conversa foi passada para atendimento humano. Data e hora em ISO 8601, UTC.
`resolved_at`	texto ou `null`	Quando a conversa foi resolvida. Data e hora em ISO 8601, UTC.

Objeto Message

Uma mensagem de uma conversa. Notas internas da equipe não aparecem.

Campo	Tipo	Descrição
`id`	texto	Identificador da mensagem.
`conversation_id`	texto	Conversa da mensagem.
`author_type`	`customer`, `ai`, `human_agent`, `system`, `event`	customer: o cliente. ai: o agente de IA. human_agent: um atendente. system: aviso automático do sistema. event: registro de acontecimento (por exemplo, início de ligação).
`author_user_id`	texto ou `null`	Atendente que escreveu, quando author_type é human_agent.
`author_agent_id`	texto ou `null`	Agente de IA que escreveu, quando author_type é ai.
`text`	texto ou `null`	Texto da mensagem. Em áudio, a transcrição; em imagem ou documento, a descrição que o sistema registrou. null em mensagem apagada.
`caption`	texto ou `null`	Legenda que o cliente escreveu junto do anexo, quando há.
`media`	objeto ou `null`	Anexo da mensagem, sem link para o arquivo. null quando é só texto.
`media.kind`	texto	Tipo do anexo: image, video, audio, audio_voicenote, document, sticker, location, contact e outros.
`media.mime_type`	texto ou `null`	Tipo MIME do arquivo.
`media.file_name`	texto ou `null`	Nome do arquivo, quando informado.
`media.duration_sec`	inteiro ou `null`	Duração em segundos, para áudio e vídeo.
`status`	`sending`, `sent`, `delivered`, `read`, `failed` ou `null`	Situação de entrega das mensagens enviadas ao cliente.
`reply_to_message_id`	texto ou `null`	Mensagem respondida, quando é uma resposta.
`deleted`	booleano	A mensagem foi apagada. O texto não é devolvido.
`created_at`	texto	Quando a mensagem foi registrada. Data e hora em ISO 8601, UTC.

Visão geral Contatos