Aperçu

Quickchat AI fournit une API REST pour accéder par programmation à la configuration de votre AI Agent, à sa Knowledge Base, à ses Conversations, à ses AI Actions, et bien plus.

Authentification

Tous les endpoints de l’API utilisent l’authentification par Bearer token. Incluez votre API token dans le header Authorization de chaque requête :

Authorization: Bearer <API_TOKEN>

Les tokens sont créés dans le Dashboard Quickchat sous External Apps > API. Chaque token est un JWT qui contient votre scenario_id, aucun header d’identifiant supplémentaire n’est donc nécessaire.

• Validité du token : 52 semaines à compter de la création
• Les tokens peuvent être révoqués à tout moment depuis le Dashboard
• Chaque token est limité à un seul AI Agent (scénario)
• La création de tokens nécessite le forfait Business ou supérieur ; sur les forfaits inférieurs, l’option est désactivée et le endpoint retourne 402 Payment Required

Note

Le endpoint Chat en temps réel (POST https://app.quickchat.ai/chat) accepte le même Bearer token que le reste de cette API, mais il se situe en dehors du chemin de base /v1/api/ et requiert scenario_id dans le corps de la requête. Consultez la page Chat pour la référence complète.

Scopes des tokens

Les API tokens sont créés avec l’un des deux scopes :

Scope	Niveau d’accès	Description
read_all	Lecture seule	Peut lire toutes les ressources mais ne peut pas créer, mettre à jour ni supprimer
write_all	Lecture + écriture	Accès complet à tous les endpoints, y compris les opérations d’écriture

• Un scope est attribué aux tokens lors de leur création dans le Dashboard sous External Apps > API
• Le scope write_all inclut automatiquement toutes les permissions read_all
• L’utilisation d’un token read_all sur un endpoint d’écriture retourne 403 avec "Insufficient token scope. Required: write_all"

Astuce

Utilisez les tokens read_all pour le monitoring, l’analyse et les intégrations en lecture seule. N’utilisez les tokens write_all que lorsque votre intégration a besoin de créer ou de modifier des ressources.

Scopes requis par groupe d’endpoints :

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

URL de base

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Limites de débit

Les limites de débit sont appliquées par token et par endpoint.

Tier	Limit	Applies To
READ	120 requests/min	Opérations GET et de liste
WRITE	60 requests/min	POST, PATCH, PUT, DELETE
HEAVY	20 requests/min	Uploads de fichiers, imports, scraping

Lorsqu’une limite de débit est dépassée, l’API retourne HTTP 429 Too Many Requests.

Webhooks

Quickchat AI n’envoie pas de webhooks sortants. Il n’existe aucun moyen de s’abonner à un événement pour que nous fassions un POST vers votre endpoint lorsqu’un message arrive, qu’une conversation est transférée ou qu’une conversation se ferme.

Pour récupérer les données au fil de l’eau, utilisez plutôt l’une de ces options :

• Actions IA : l’IA appelle votre API en pleine conversation. C’est ce qui se rapproche le plus d’un webhook, et il s’agit de push, pas de polling : votre endpoint est appelé pendant que la conversation est en cours. L’action se déclenche lorsque l’IA juge qu’elle s’applique, ce qui convient mieux à « informer mon système de ce lead » qu’à « informer mon système de chaque message ».
• Google Sheets : ajoute une ligne par événement sans avoir à construire d’endpoint.
• Le polling de l’API Conversations : pour un enregistrement complet. Attention à la limite READ ci-dessus.

L’accès à l’API nécessite le forfait Business, voir Forfaits et limites.

Pagination

Les endpoints de liste prennent en charge la pagination via des query parameters :

Parameter	Description
limit integer	Nombre d’éléments par page
offset integer	Nombre d’éléments à ignorer

Les réponses paginées suivent cette structure :

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Gestion des erreurs

Toutes les erreurs sont retournées en JSON au format suivant :

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Saisie invalide ou champs requis manquants
401	PERMISSION_DENIED	Token invalide, expiré ou révoqué
402	PAYMENT_REQUIRED	Un abonnement actif est requis
403	PERMISSION_DENIED	Le token n’a pas le scope requis pour cette opération
404	NOT_FOUND	Ressource introuvable
409	CONFLICT	Opération en conflit (p. ex. modification concurrente)
422	VALIDATION_ERROR	Le corps de la requête n’a pas passé la validation du schéma
429	TOO_MANY_REQUESTS	Limite de débit dépassée
500	UNKNOWN	Erreur interne du serveur
503	SERVICE_UNAVAILABLE	Indisponibilité temporaire

---