Conversations

Quickchat AI captura todas las conversaciones en todos los canales. Estos endpoints te permiten listarlas y recuperarlas.

Quickchat AI captura y analiza automáticamente cada conversación que tiene tu Agente de IA en todos los canales: widget, Slack, WhatsApp, Telegram y más. La API de Conversations te da acceso programático a este rico conjunto de datos para construir dashboards personalizados, alimentar pipelines de analítica posteriores, disparar flujos de trabajo de CRM o integrarte con tus herramientas de business intelligence existentes.

Cada conversación incluye un análisis con IA: detección de sentimiento, clasificación de temas, seguimiento de resolución y marcado automático de las conversaciones que puedan necesitar atención humana. Combinado con el historial completo de mensajes, los clics en enlaces registrados y los metadatos personalizados, tienes todo lo necesario para entender cómo interactúan los visitantes con tu Agente de IA.

Los datos de conversación se reparten entre varios endpoints:

List Conversations — Información básica, detalles del visitante, estado. Úsalo para dashboards, vistas generales y consultas filtradas
Get Conversation Details — Información completa, incluidos unified_analysis (insights generados por IA) y client_metadata
Get Conversation Events — Historial completo de mensajes, clics en enlaces registrados y entradas de log
Get/Set Metadata — Datos clave-valor personalizados que adjuntas a las conversaciones (consulta Conversation Metadata)

List Conversations

Ámbito: read_all

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

Query Parameters

Parameter	Description
`limit` integer	Elementos por página
`offset` integer	Elementos a omitir
`query` string	Buscar por número de pedido, UUID o texto del mensaje
`assignee_type` string	`"ai_assistant"`, `"human_operator"` o `"unassigned"`
`source` string	`"widget"`, `"slack"`, `"telegram"`, `"whatsapp"`, etc.
`resolution_status` string	`"open"` o `"resolved"`
`created_timestamp_start_date` datetime	Filtrar por fecha de creación (inicio)
`created_timestamp_end_date` datetime	Filtrar por fecha de creación (fin)
`last_message_at_start_date` datetime	Filtrar por fecha del último mensaje (inicio)
`last_message_at_end_date` datetime	Filtrar por fecha del último mensaje (fin)
`most_frequent_language` string	Filtrar por idioma detectado
`order` string	`"desc"` (predeterminado, más recientes primero) o `"asc"` (más antiguas primero). El orden ascendente sirve para avanzar desde una conversación conocida, así que combínalo con `last_message_at_start_date`

Shell
Python

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

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 de la conversación
`ord` integer	Número secuencial de la conversación
`created_at` string	Marca de tiempo de creación de la conversación
`last_message_at` string	Marca de tiempo del mensaje más reciente
`title` string	Título de la conversación generado por IA
`source` string	Canal en el que se originó la conversación (p. ej., `"widget"`, `"slack"`, `"whatsapp"`)
`terminated` boolean	Si la conversación ha finalizado
`resolution_status` string	`"open"` o `"resolved"`
`has_unread_messages` boolean	Si hay mensajes sin leer
`supports_inbox_control` boolean	Si el origen de la conversación admite control desde la inbox (asignar, handoff)
`last_message_content` string	Contenido del último mensaje de la conversación
`most_frequent_language` string	Idioma detectado con más frecuencia en la conversación
`assignee` object	Asignación actual (`type`: `"ai_assistant"`, `"human_operator"` o `"unassigned"`)
`visitor_name` string or null	Nombre del visitante (del formulario previo al chat o del perfil del canal)
`visitor_email` string or null	Dirección de correo del visitante
`visitor_phone_number` string or null	Número de teléfono del visitante
`visitor_label` string or null	Etiqueta personalizada asignada al visitante

Get Conversation Details

Ámbito: read_all

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

Shell
Python

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

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
}

La respuesta de detalle incluye todos los campos de la respuesta de listado, más:

Field	Description
`url` string or null	URL de la página donde se inició la conversación (solo widget)
`client_metadata` object or null	Pares clave-valor personalizados adjuntos a la conversación
`last_visitor_message_at` string	Marca de tiempo del último mensaje del visitante
`unified_analysis` object or null	Análisis de la conversación generado por IA (ver más abajo)

Campos de unified_analysis:

Field	Description
`sentiment` string	Sentimiento de la conversación detectado por IA (p. ej., `"positive"`, `"neutral"`, `"negative"`)
`resolution_status` string	Estado de resolución evaluado por IA (puede diferir del `resolution_status` de nivel superior)
`topic` string	Tema de la conversación detectado por IA
`is_flagged` boolean	Si la IA marcó esta conversación para revisión humana
`flag_reason` string or null	Motivo por el que se marcó la conversación

El campo resolution_status de nivel superior ("open" o "resolved") es el estado canónico, establecido manualmente o por reglas de automatización.

El unified_analysis.resolution_status lo calcula el análisis con IA y puede diferir: por ejemplo, la IA podría clasificar una conversación como resuelta según el análisis de contenido aunque el estado de nivel superior siga siendo "open". Usa el campo de nivel superior para filtrado y flujos de trabajo; usa unified_analysis para analítica e insights.

Get Conversation Events

Recupera todos los eventos (mensajes, enlaces registrados, logs) de una conversación.

Ámbito: read_all

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

Query Parameters

Parameter	Description
`limit` integer	Elementos por página
`offset` integer	Elementos a omitir

Shell
Python

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

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"` o `"log"`
`data.id` string	Identificador único del mensaje
`data.ord` integer	Número secuencial del mensaje
`data.created_at` string	Marca de tiempo del evento
`data.content` string	Contenido del mensaje
`data.author` string	`"ai_assistant"`, `"visitor"` o `"human_operator"`
`data.handoff_state` string or null	Estado del handoff si aplica
`data.message_insights` object or null	Insights del mensaje generados por IA
`data.feedback` object or null	Feedback del usuario sobre el mensaje
`data.client_metadata` object or null	Metadatos personalizados adjuntos al mensaje
`data.sources_generated` array	Artículos de la Base de Conocimiento que usó la IA al generar su respuesta
`data.is_welcome` boolean	Si se trata de un mensaje de bienvenida
`data.attachments` array	Archivos adjuntos

Conversations

List Conversations

Get Conversation Details

Get Conversation Events

Primeros pasos

Agente de IA

Acciones

Conversaciones

Canales

Tu sitio web

Soporte y CRM

Aplicaciones de mensajería

Cuenta y facturación

Primeros pasos

Configuración

Base de conocimientos

Conversaciones