API (Legacy)

Avis de depreciation

Cette page documente l’API Chat heritee utilisant l’authentification par cle API. Pour la nouvelle API avec jeton Bearer donnant acces aux endpoints Base de connaissances, Conversations et Actions IA, consultez API.

Dans ce guide, nous passons en revue les etapes necessaires pour integrer votre Assistant IA Quickchat personnalise a votre produit via un endpoint API.

Authentification

Incluez votre API Key et le scenario_id dans chaque requete.

Pour obtenir votre cle API, mettez a niveau votre abonnement pour inclure l’acces API.

Chat

Initialiser une nouvelle conversation / historique utilisateur

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 commande ci-dessus retourne un JSON de la forme :

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

conv_id est un parametre optionnel. Une requete sans conv_id demarre une nouvelle conversation et un conv_id nouvellement genere est retourne.

Associez conv_id a votre utilisateur pour maintenir le contexte de la conversation dans le temps et a travers plusieurs interactions.

Cet endpoint realise un echange conversationnel unique.

Requete HTTP

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

Query Parameters

Parameter	Type	Description
api_key	string	Creez un compte et abonnez-vous pour obtenir votre cle API
scenario_id	Text	ID associe a votre implementation Quickchat API
text	string	Message d’entree utilisateur

Envoyer un message a l’Assistant 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 commande ci-dessus retourne un JSON de la forme :

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

Requete HTTP

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

Query Parameters

Parameter	Type	Description
api_key	string	Creez un compte et abonnez-vous pour obtenir votre cle API
scenario_id	string	ID associe a votre implementation Quickchat API.
conv_id	string (Optional)	Identifie une conversation ou un utilisateur.
text	string	Message d’entree utilisateur.
message_context	string (Optional)	Contexte supplementaire fourni par le client, transmis a l’IA avec le message.
client_metadata	dict (Optional)	Par exemple {userId: 12, website: mywebsite.com}. Maximum 5 cles a la fois. Ces parametres seront assignes a chaque nouveau message et affiches comme colonnes de donnees dans l’export des conversations depuis l’Inbox.

Messages avec contexte et metadonnees personnalises

Comme decrit dans le tableau des parametres ci-dessus, l’endpoint https://chat.quickchat.ai/chat vous permet d’envoyer deux parametres optionnels : message_context et client_metadata.

Les metadonnees client representent des attributs personnalises assignes a chaque nouveau message et affiches comme colonnes de donnees dans l’export des conversations depuis l’Inbox. Vous pouvez egalement ajouter des attributs personnalises aux messages via le Widget pour le meme resultat.

Le contexte de message permet de fournir, par exemple, un contexte specifique a chaque utilisateur pour personnaliser les echanges.

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

Ajouter des filtres par tags de Base de connaissances via l’API

Dans l’application Quickchat AI, vous avez la possibilite d’ajouter des tags a chaque Article. Ceux-ci peuvent etre utilises pour filtrer la Base de connaissances afin que l’IA reponde uniquement a partir d’un sous-ensemble d’Articles. Veuillez noter que cette fonctionnalite n’est pour l’instant prise en charge que via l’API.

Pour filtrer par sujets de Base de connaissances (tags), vous devez ajouter kb_topic dans votre client_metadata lors des appels API. Il est important de s’assurer que la cle kb_topic est presente a chaque appel a l’API, y compris lors de l’initialisation de la conversation. La valeur de kb_topic peut changer entre les appels, mais le parametre lui-meme doit etre constamment present pendant toute la conversation pour etre pris en compte par notre systeme.

L’exemple ci-dessous montre comment ajouter kb_topic a client_metadata. Dans cet exemple, tout Article ayant le tag your-topic ou aucun tag sera selectionne pour le pool de connaissances candidat pour la reponse.

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

Erreurs

Ci-dessous, nous avons rassemble les codes d’erreur pouvant etre retournes par l’API, accompagnes de leur description et des solutions possibles.

Code	Description	Action
400	Les parametres suivants sont requis : api_key, scenario_id, text	Veuillez vous assurer que tous les parametres requis sont fournis.
400	Le conv_id abcd1234 n’existe pas	Veuillez vous assurer que le conv_id que vous utilisez est correct.
400	La limite pour le contexte de message est de 1000 caracteres.	Veuillez reduire le contexte de message a 1000 caracteres, espaces compris.
401	Non autorise	Veuillez vous assurer que votre api_key et scenario_id sont corrects (voir Integrations - API dans l’application).
500	Erreur interne du serveur	Il y a un probleme de notre cote. Veuillez contacter le support.
503	Service indisponible	Nos serveurs sont surcharges ou temporairement indisponibles pour maintenance. Si le probleme persiste, veuillez contacter le support.