Chat

Chat

Le endpoint Chat en temps réel envoie un message de visiteur à votre AI Agent et retourne la réponse de l’IA en un seul aller-retour. C’est le endpoint dont vous avez besoin pour construire une interface de chat personnalisée par-dessus Quickchat AI.

Il diffère des autres endpoints de deux façons : il se situe à app.quickchat.ai/chat, en dehors des chemins de base /v1/api/ et /v1/api_core/, et il lit scenario_id depuis le corps de la requête plutôt que depuis le token. Il utilise la même authentification par Bearer token que le reste de cette API.

Note

Envoyez chaque requête à https://app.quickchat.ai/chat. Le scenario_id dans le corps doit correspondre à l’AI Agent auquel votre Bearer token est lié.

Send Message

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

Request Body

Parameter	Description
scenario_id string, required	ID de votre AI Agent. Doit correspondre au scenario_id lié au Bearer token
text string, required	Message saisi par l’utilisateur
conv_id string	ID de conversation. Omettez-le à la première requête pour démarrer une nouvelle conversation, puis renvoyez le conv_id retourné aux requêtes suivantes pour la poursuivre
client_metadata object	Paires clé-valeur personnalisées (nous recommandons au maximum 5 clés) attachées à chaque message. Affichées sous forme de colonnes de données dans l’export de conversation dans l’Inbox

Une requête sans conv_id démarre une nouvelle conversation, et le conv_id généré est retourné dans la réponse. Stockez ce conv_id et renvoyez-le dans les requêtes ultérieures pour conserver le contexte de la conversation à travers plusieurs interactions de l’utilisateur.

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	Identifiant de conversation. Toujours retourné. Renvoyez-le dans le champ conv_id du corps pour poursuivre la conversation
reply string	La réponse de l’AI Agent. Peut contenir du HTML, par exemple des sauts de ligne <br>
ord_number integer	Numéro séquentiel du message dans la conversation
src integer	Indicateur de source interne. Les clients de l’API peuvent ignorer ce champ

Pour poursuivre une conversation existante, renvoyez le conv_id que vous avez reçu :

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

Le endpoint Chat accepte un paramètre client_metadata optionnel : des attributs personnalisés qui sont assignés à chaque nouveau message et affichés sous forme de colonnes de données dans l’export de conversation dans l’Inbox. Vous pouvez attacher les mêmes attributs via le widget. Nous recommandons d’envoyer au maximum 5 clés à la fois, par exemple {"userId": 12, "website": "mywebsite.com"}. C’est une recommandation, pas une limite imposée par l’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

Vous pouvez ajouter des tags aux articles de la Knowledge Base et les utiliser pour restreindre les articles sur lesquels l’IA s’appuie, afin qu’elle réponde uniquement à partir d’un sous-ensemble de la Knowledge Base. Ce filtrage n’est actuellement pris en charge que via l’API.

Pour filtrer par tag, ajoutez une clé kb_topic à client_metadata. La clé kb_topic doit être présente dans chaque requête de la conversation, y compris la requête qui la démarre. Sa valeur peut changer d’une requête à l’autre, mais la clé elle-même doit être présente tout au long de la conversation pour que le filtre s’applique.

Dans l’exemple ci-dessous, tout article tagué your-topic, ou sans aucun tag, est inclus dans l’ensemble candidat des connaissances utilisées pour la réponse.

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

Errors

Le endpoint Chat retourne un message d’erreur en texte brut avec un code de statut HTTP approprié.

Status	Description	Action
400	scenario_id manquant ou aucune information d’authentification fournie	Incluez scenario_id dans le corps et un header Authorization: Bearer <API_TOKEN> valide
400	conv_id invalide (Conversation conv_id <id> is not valid.)	Omettez conv_id pour démarrer une nouvelle conversation, ou renvoyez un conv_id retourné par une réponse précédente
401	Informations d’authentification invalides (Unauthorized.)	Vérifiez que votre Bearer token ou votre API key est valide pour ce scenario_id
404	scenario_id inconnu (No implementation found for scenario_id <id>)	Vérifiez le scenario_id et que votre Bearer token y est lié
500	Erreur interne du serveur	Un problème de notre côté. Veuillez nous contacter auprès du support
503	Service indisponible	Les serveurs sont temporairement surchargés ou en maintenance. Si le problème persiste, veuillez nous contacter auprès du support