Conversations

O Quickchat AI captura e analisa automaticamente todas as conversas que seu Agente de IA tem em todos os canais — widget, Slack, WhatsApp, Telegram e mais. A API de Conversations dá a você acesso programático a esse rico conjunto de dados para construir dashboards personalizados, alimentar pipelines de analytics downstream, disparar workflows de CRM ou integrar com suas ferramentas de business intelligence existentes.

Toda conversa inclui análise por IA: detecção de sentimento, classificação de tópicos, acompanhamento de resolução e sinalização automática de conversas que podem precisar de atenção humana. Combinado com o histórico completo de mensagens, cliques em links rastreados e metadados personalizados, você tem tudo o que precisa para entender como os visitantes interagem com seu Agente de IA.

Os dados de conversas estão distribuídos por vários endpoints:

• List Conversations — Informações básicas, detalhes do visitante, status. Use para dashboards, visões gerais e queries filtradas
• Get Conversation Details — Informações completas, incluindo unified_analysis (insights gerados por IA) e client_metadata
• Get Conversation Events — Histórico completo de mensagens, cliques em links rastreados e entradas de log
• Get/Set Metadata — Dados chave-valor personalizados que você anexa às conversas (veja Conversation Metadata)

List Conversations

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations

Query Parameters

Parameter	Description
limit integer	Itens por página
offset integer	Itens a pular
query string	Pesquisar por número de pedido, UUID ou texto de mensagem
assignee_type string	"ai_assistant", "human_operator" ou "unassigned"
source string	"widget", "slack", "telegram", "whatsapp", etc.
resolution_status string	"open" ou "resolved"
created_timestamp_start_date datetime	Filtrar por data de criação (início)
created_timestamp_end_date datetime	Filtrar por data de criação (fim)
last_message_at_start_date datetime	Filtrar por data da última mensagem (início)
last_message_at_end_date datetime	Filtrar por data da última mensagem (fim)
most_frequent_language string	Filtrar por idioma detectado

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations?limit=10&resolution_status=open' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 10, "resolution_status": "open"},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "id": "conv-uuid-1234",
      "ord": 42,
      "created_at": "2026-01-15T10:30:00Z",
      "last_message_at": "2026-01-15T10:35:00Z",
      "title": "Return policy question",
      "source": "widget",
      "terminated": false,
      "resolution_status": "open",
      "has_unread_messages": true,
      "supports_inbox_control": true,
      "last_message_content": "What is your return policy?",
      "most_frequent_language": "en",
      "assignee": {
        "type": "ai_assistant"
      },
      "visitor_name": "John",
      "visitor_email": "john@example.com",
      "visitor_phone_number": null,
      "visitor_label": null
    }
  ],
  "offset": 0,
  "limit": 10,
  "count": 42
}

Field	Description
id string	UUID da conversa
ord integer	Número sequencial da conversa
created_at string	Timestamp de criação da conversa
last_message_at string	Timestamp da mensagem mais recente
title string	Título da conversa gerado por IA
source string	Canal de onde a conversa se originou (ex.: "widget", "slack", "whatsapp")
terminated boolean	Se a conversa terminou
resolution_status string	"open" ou "resolved"
has_unread_messages boolean	Se há mensagens não lidas
supports_inbox_control boolean	Se a origem da conversa suporta controle de inbox (atribuição, handoff)
last_message_content string	Conteúdo da última mensagem da conversa
most_frequent_language string	Idioma detectado com mais frequência na conversa
assignee object	Responsável atual (type: "ai_assistant", "human_operator" ou "unassigned")
visitor_name string or null	Nome do visitante (do formulário de pré-chat ou do perfil do canal)
visitor_email string or null	Endereço de e-mail do visitante
visitor_phone_number string or null	Número de telefone do visitante
visitor_label string or null	Rótulo personalizado atribuído ao visitante

Get Conversation Details

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/

Shell

curl https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/ \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Response 200 OK

{
  "id": "conv-uuid-1234",
  "ord": 42,
  "created_at": "2026-01-15T10:30:00Z",
  "last_message_at": "2026-01-15T10:35:00Z",
  "title": "Return policy question",
  "source": "widget",
  "terminated": false,
  "resolution_status": "open",
  "has_unread_messages": true,
  "supports_inbox_control": true,
  "last_message_content": "What is your return policy?",
  "most_frequent_language": "en",
  "assignee": {
    "type": "ai_assistant"
  },
  "url": null,
  "client_metadata": {"userId": 12},
  "last_visitor_message_at": "2026-01-15T10:34:00Z",
  "unified_analysis": {
    "sentiment": "neutral",
    "resolution_status": "open",
    "topic": "Return policy",
    "is_flagged": false,
    "flag_reason": null
  },
  "visitor_name": "John",
  "visitor_email": "john@example.com",
  "visitor_phone_number": null,
  "visitor_label": null
}

A resposta de detalhes inclui todos os campos da resposta de listagem, além de:

Field	Description
url string or null	URL da página onde a conversa começou (somente widget)
client_metadata object or null	Pares chave-valor personalizados anexados à conversa
last_visitor_message_at string	Timestamp da última mensagem do visitante
unified_analysis object or null	Análise da conversa gerada por IA (veja abaixo)

Campos de unified_analysis:

Field	Description
sentiment string	Sentimento da conversa detectado por IA (ex.: "positive", "neutral", "negative")
resolution_status string	Status de resolução avaliado pela IA (pode diferir do resolution_status de nível superior)
topic string	Tópico da conversa detectado por IA
is_flagged boolean	Se a IA sinalizou esta conversa para revisão humana
flag_reason string or null	Motivo pelo qual a conversa foi sinalizada

resolution_status vs unified_analysis.resolution_status

O campo resolution_status de nível superior ("open" ou "resolved") é o status canônico definido manualmente ou por regras de automação.

O unified_analysis.resolution_status é calculado pela análise da IA e pode diferir — por exemplo, a IA pode classificar uma conversa como resolvida com base na análise de conteúdo, mesmo que o status de nível superior ainda seja "open". Use o campo de nível superior para filtragem e workflow; use unified_analysis para analytics e insights.

Get Conversation Events

Recupere todos os eventos (mensagens, links rastreados, logs) de uma conversa.

Scope: read_all

GET https://app.quickchat.ai/v1/api_core/conversations/{conversation_id}/events/

Query Parameters

Parameter	Description
limit integer	Itens por página
offset integer	Itens a pular

Shell

curl 'https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/?limit=20' \
  -H 'Authorization: Bearer <API_TOKEN>'

Python

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api_core/conversations/conv-uuid-1234/events/",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    params={"limit": 20},
)
data = response.json()

Response 200 OK

{
  "items": [
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-001",
        "ord": 1,
        "created_at": "2026-01-15T10:30:00Z",
        "content": "Hello! How can I help you today?",
        "author": "ai_assistant",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": true,
        "attachments": []
      }
    },
    {
      "type": "message",
      "data": {
        "id": "msg-uuid-002",
        "ord": 2,
        "created_at": "2026-01-15T10:31:00Z",
        "content": "What is your return policy?",
        "author": "visitor",
        "handoff_state": null,
        "message_insights": null,
        "feedback": null,
        "client_metadata": null,
        "sources_generated": [],
        "is_welcome": false,
        "attachments": []
      }
    }
  ],
  "offset": 0,
  "limit": 20,
  "count": 2
}

Tipos de evento: message, tracked_link, log

Tipos de autor: ai_assistant, visitor, human_operator

Field	Description
type string	Tipo de evento: "message", "tracked_link" ou "log"
data.id string	Identificador único da mensagem
data.ord integer	Número sequencial da mensagem
data.created_at string	Timestamp do evento
data.content string	Conteúdo da mensagem
data.author string	"ai_assistant", "visitor" ou "human_operator"
data.handoff_state string or null	Estado de handoff, se aplicável
data.message_insights object or null	Insights da mensagem gerados por IA
data.feedback object or null	Feedback do usuário sobre a mensagem
data.client_metadata object or null	Metadados personalizados anexados à mensagem
data.sources_generated array	Artigos da Base de Conhecimento que a IA usou ao gerar sua resposta
data.is_welcome boolean	Se esta é uma mensagem de boas-vindas
data.attachments array	Anexos de arquivos

---