API (Legacy)

Aviso de deprecacion

Esta pagina documenta la API de Chat heredada que utiliza autenticacion por API Key. Para la nueva API con token Bearer que incluye acceso a los endpoints de Base de Conocimiento, Conversaciones y Acciones de IA, consulta API.

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

Autenticacion

Incluye tu API Key y scenario_id en cada peticion.

Para obtener tu clave de API, actualiza tu suscripcion para incluir acceso a la API.

Chat

Inicializar nueva conversacion / historial de nuevo 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 peticion anterior devuelve un JSON con la siguiente estructura:

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

conv_id es un parametro opcional. Una peticion que no contenga conv_id inicia una nueva conversacion y se devuelve un conv_id recien generado.

Asocia conv_id con tu usuario particular para mantener el contexto de la conversacion a lo largo del tiempo y entre multiples interacciones del usuario.

Este endpoint realiza un unico intercambio conversacional.

Peticion HTTP

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

Parametros de consulta

Parameter	Type	Description
api_key	string	Crea una cuenta y suscribete para obtener tu clave de API
scenario_id	Text	ID asociado a tu implementacion 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 peticion anterior devuelve un JSON con la siguiente estructura:

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

Peticion HTTP

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

Parametros de consulta

Parameter	Type	Description
api_key	string	Crea una cuenta y suscribete para obtener tu clave de API
scenario_id	string	ID asociado a tu implementacion de Quickchat API.
conv_id	string (Optional)	Identifica una conversacion/usuario particular.
text	string	Mensaje de entrada del usuario.
message_context	string (Optional)	Contexto adicional por mensaje proporcionado por el cliente, que se pasa a la IA junto con el mensaje.
client_metadata	dict (Optional)	Por ejemplo {userId: 12, website: mywebsite.com}. Maximo 5 claves a la vez. Estos parametros se asignan a cada mensaje nuevo y se muestran como columnas de datos en la exportacion de conversaciones en la Bandeja de Entrada.

Mensajes con contexto y metadatos personalizados

Como se describe en la tabla de parametros anterior, el endpoint https://chat.quickchat.ai/chat permite enviar dos parametros opcionales: message_context y client_metadata.

Los metadatos del cliente representan atributos personalizados que se asignan a cada mensaje nuevo y se muestran como columnas de datos en la exportacion de conversaciones en la Bandeja de Entrada. Tambien puedes agregar atributos personalizados a los mensajes a traves del Widget con el mismo efecto.

El contexto del mensaje te permite proporcionar, por ejemplo, contexto especifico por usuario a cada mensaje para dar una sensacion mas personalizada a cada conversacion.

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

Agregar filtros de etiquetas de la Base de Conocimiento via API

En la aplicacion de Quickchat AI tienes la posibilidad de agregar etiquetas a cada Articulo. Estas se pueden usar para filtrar la Base de Conocimiento, de modo que la IA responda unicamente en base a un subconjunto de Articulos de la Base de Conocimiento. Ten en cuenta que por el momento esta funcionalidad solo esta disponible via API.

Para filtrar por temas de la Base de Conocimiento (etiquetas), debes agregar kb_topic a tu client_metadata en las llamadas a la API. Es importante asegurarse de que la clave kb_topic este presente en cada llamada a la API, incluyendo la inicializacion de la conversacion. Aunque el valor de kb_topic puede cambiar entre llamadas a la API, el parametro en si debe estar constantemente presente durante toda la conversacion para ser considerado por nuestro sistema.

El siguiente ejemplo muestra como agregar kb_topic a client_metadata. En el ejemplo, cualquier Articulo con la etiqueta your-topic o sin etiqueta sera seleccionado para el conjunto de candidatos de conocimiento para la respuesta.

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 continuacion se presentan los codigos de error que puede devolver la API, junto con su descripcion y posibles soluciones.

Code	Description	Action
400	Se deben proporcionar los siguientes parametros: api_key, scenario_id, text	Asegurate de que todos los parametros obligatorios esten incluidos.
400	El conv_id abcd1234 no existe	Verifica que el conv_id que estas utilizando sea correcto.
400	El limite para el contexto del mensaje es de 1000 caracteres.	Reduce el contexto del mensaje a 1000 caracteres incluyendo espacios.
401	No autorizado	Asegurate de que tu api_key y scenario_id sean correctos (consulta Integrations - API en la App).
500	Error interno del servidor	Hay un problema de nuestro lado. Por favor contacta con soporte.
503	Servicio no disponible	Nuestros servidores estan sobrecargados o temporalmente no disponibles por mantenimiento. Si el problema persiste, por favor contacta con soporte.