API

En esta guía, veremos los pasos necesarios para integrar tu Asistente de IA de Quickchat con tu producto mediante un endpoint API.

Autenticación

Incluye tu API Key y scenario_id en cada petición.

Para obtener tu clave, actualiza tu suscripción para incluir acceso a la API.

Chat

Inicializar nueva conversación / historial de usuario

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "text": "Hello!"
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

La petición anterior devuelve un JSON como este:

{
  "ord_number": 2,
  "conv_id": "abcd1234",
  "reply": "Hey there! 🙂"
}

conv_id es opcional. Si no lo envías, se inicia una nueva conversación y se devuelve un conv_id nuevo.

Asocia conv_id con tu usuario para mantener el contexto en el tiempo y entre interacciones.

Este endpoint realiza un único intercambio conversacional.

Petición HTTP

POST https://chat.quickchat.ai/chat

Parámetros

Parámetro	Tipo	Descripción
api_key	string	Crea una cuenta y suscríbete para obtener tu clave de API
scenario_id	Text	ID asociado a tu implementación de Quickchat API
text	string	Mensaje de entrada del usuario

Enviar mensaje al Asistente de IA

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

La petición anterior devuelve un JSON como este:

{
  "ord_number": 236,
  "reply": "Hey, great to hear from you again! 😉"
}

Petición HTTP

POST https://chat.quickchat.ai/chat

Parámetros

Parámetro	Tipo	Descripción
api_key	string	Crea una cuenta y suscríbete para obtener tu clave de API
scenario_id	string	ID asociado a tu implementación de Quickchat API.
conv_id	string (Opcional)	Identifica una conversación/usuario.
text	string	Mensaje de entrada del usuario.
message_context	string (Opcional)	Contexto adicional por mensaje, pasado a la IA junto con el mensaje.
client_metadata	dict (Opcional)	Por ejemplo {userId: 12, website: mywebsite.com}. Máx. 5 claves. Se asigna a cada mensaje nuevo y aparece como columnas en la exportación CSV de conversaciones.

Mensajes con contexto y metadatos personalizados

Como se describe arriba, el endpoint https://chat.quickchat.ai/chat permite message_context y client_metadata.

client_metadata son atributos personalizados asignados a cada mensaje y visibles en el CSV de exportación de la Inbox.

message_context permite añadir contexto por usuario para personalizar la conversación.

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
  "message_context": "The users name is John.",
  "client_metadata": {userId: 12, website: mywebsite.com}
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'userId': 12, 'website': 'mywebsite.com'}
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Añadir filtros por etiquetas de la Base de Conocimiento vía API

En la app de Quickchat AI puedes añadir etiquetas a cada Artículo. Sirven para filtrar la Base, de modo que la IA responda solo con un subconjunto de artículos.

Para filtrar por temas (tags), añade kb_topic a client_metadata. Importante: asegúrate de que la clave kb_topic esté presente en todas las llamadas, incluida la inicial. El valor puede cambiar entre llamadas, pero la clave debe estar siempre.

Ejemplo:

json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'kb_topic': 'your-topic'}
  }

Errores

A continuación, los códigos de error que puede devolver la API, con descripción y acción recomendada.

Código	Descripción	Acción
400	Se requieren api_key, scenario_id, text	Asegúrate de enviar todos los parámetros obligatorios.
400	conv_id abcd1234 no existe	Verifica el conv_id proporcionado.
400	El límite de message_context es de 1000 caracteres	Reduce message_context a 1000 caracteres (incluyendo espacios).
401	No autorizado	Verifica api_key y scenario_id (ver Integrations - API).
500	Error interno del servidor	Problema de nuestro lado. Contáctanos.
503	Servicio no disponible	Sobrecarga o mantenimiento. Si persiste, contáctanos.