Chat

Chat

El endpoint de Chat en tiempo real envía un mensaje de un visitante a tu Agente de IA y devuelve la respuesta de la IA en un solo viaje de ida y vuelta. Este es el endpoint que necesitas cuando construyes una interfaz de chat personalizada sobre Quickchat AI.

Se diferencia de los demás endpoints en dos aspectos: está en app.quickchat.ai/chat, fuera de las rutas base /v1/api/ y /v1/api_core/, y lee scenario_id del cuerpo de la petición en lugar del token. Usa la misma autenticación mediante Bearer token que el resto de esta API.

Nota

Envía cada petición a https://app.quickchat.ai/chat. El scenario_id del cuerpo debe coincidir con el Agente de IA al que está vinculado tu Bearer token.

Send Message

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

Request Body

Parameter	Description
scenario_id string, required	ID de tu Agente de IA. Debe coincidir con el scenario_id vinculado al Bearer token
text string, required	Mensaje de entrada del usuario
conv_id string	ID de conversación. Omítelo en la primera petición para iniciar una nueva conversación; después, vuelve a pasar el conv_id devuelto en las peticiones posteriores para continuarla
client_metadata object	Pares clave-valor personalizados (recomendamos como máximo 5 claves) adjuntos a cada mensaje. Se muestran como columnas de datos en la exportación de conversaciones de la Inbox

Una petición sin conv_id inicia una nueva conversación, y el conv_id generado se devuelve en la respuesta. Guarda ese conv_id y reenvíalo en peticiones posteriores para mantener el contexto de la conversación a lo largo de varias interacciones del usuario.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Response 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Field	Description
conv_id string	Identificador de conversación. Siempre se devuelve. Reenvíalo en el campo conv_id del cuerpo para continuar la conversación
reply string	La respuesta del Agente de IA. Puede contener HTML como saltos de línea <br>
ord_number integer	Número secuencial de mensaje dentro de la conversación
src integer	Indicador de origen interno. Los clientes de la API pueden ignorar este campo

Para continuar una conversación existente, reenvía el conv_id que recibiste:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Client Metadata

El endpoint de Chat acepta un parámetro opcional client_metadata: atributos personalizados que se asignan a cada mensaje nuevo y se muestran como columnas de datos en la exportación de conversaciones de la Inbox. Puedes adjuntar los mismos atributos a través del widget. Recomendamos enviar como máximo 5 claves a la vez, por ejemplo {"userId": 12, "website": "mywebsite.com"}. Es una recomendación, no un límite impuesto por la API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Knowledge Base Tag Filtering

Puedes añadir tags a los artículos de la Base de Conocimiento y usarlos para restringir en qué artículos se basa la IA, de modo que responda únicamente a partir de un subconjunto de la Base de Conocimiento. Este filtrado solo se admite actualmente a través de la API.

Para filtrar por tag, añade una clave kb_topic a client_metadata. La clave kb_topic debe estar presente en cada petición de la conversación, incluida la que la inicia. Su valor puede cambiar entre peticiones, pero la clave en sí debe estar presente durante toda la conversación para que el filtro se aplique.

En el ejemplo siguiente, cualquier artículo etiquetado como your-topic, o sin tag alguno, se incluye en el conjunto de candidatos de conocimiento para la respuesta.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Errors

El endpoint de Chat devuelve un mensaje de error en texto plano con un código de estado HTTP adecuado.

Status	Description	Action
400	Falta scenario_id o no se proporcionaron credenciales	Incluye scenario_id en el cuerpo y un encabezado Authorization: Bearer <API_TOKEN> válido
400	conv_id no válido (Conversation conv_id <id> is not valid.)	Omite conv_id para iniciar una nueva conversación, o pasa un conv_id devuelto por una respuesta anterior
401	Credenciales no válidas (Unauthorized.)	Comprueba que tu Bearer token o clave de API es válido para este scenario_id
404	scenario_id desconocido (No implementation found for scenario_id <id>)	Verifica el scenario_id y que tu Bearer token esté vinculado a él
500	Error interno del servidor	Un problema por nuestra parte. Por favor, ponte en contacto con soporte
503	Servicio no disponible	Los servidores están temporalmente sobrecargados o en mantenimiento. Si el problema persiste, por favor ponte en contacto con soporte