Conversations

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

Scope: 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

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 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

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
}

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

resolution_status vs unified_analysis.resolution_status

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.

Scope: 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

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" 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

---