Référence de l'API Chat

Authentification

Chaque requête est authentifiée avec la clé API de votre espace de travail, envoyée dans l'en-tête X-API-Key (ou dans un paramètre api_key). Les clés ressemblent à ck_live_.... Traitez la clé comme un mot de passe - quiconque la détient peut envoyer des messages facturés à votre espace de travail. Faites-la tourner à tout moment depuis Paramètres -> Accès API ; la clé précédente cesse de fonctionner immédiatement.

Envoyer un message

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Paramètres :

• message (chaîne) - le message du visiteur. Requis sauf si des files sont joints.
• ticket_id (chaîne, facultatif) - poursuivre une conversation existante. Omettez-le pour en démarrer une nouvelle.
• visitor_email / visitor_name (chaîne, facultatif) - associer des coordonnées au ticket.
• files (multipart, facultatif) - pièces jointes du visiteur. Nécessite un plan avec téléversement de fichiers.

Réponse

L'appel renvoie 202 Accepted dès que le message est enregistré ; la réponse de l'IA est générée de manière asynchrone.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Renvoyez data.ticket_id comme ticket_id lors de l'appel suivant pour poursuivre la conversation. Pour recevoir la réponse de l'IA, abonnez-vous via WebSocket (ActionCable) au canal identifié par data.id - le même hachage de visiteur que celui utilisé par le widget intégré.

Lire les conversations

Récupérez les tickets et leurs messages avec la même X-API-Key. Chaque endpoint de lecture est limité à votre espace de travail et disponible sur le plan Business.

• GET /api/v1/chat/tickets - liste les tickets, du plus récent au plus ancien. Paramètres de requête : status, limit (max. 100), offset. Renvoie tickets et pagination.
• GET /api/v1/chat/tickets/:id - un seul ticket.
• GET /api/v1/chat/tickets/:id/messages - les messages d'un ticket dans l'ordre, chacun avec role, content et attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Limites de débit et quota

Les requêtes sont limitées à environ 20 par minute par clé (et par IP). Chaque réponse générée puise également dans le quota mensuel de messages de votre plan ; une fois celui-ci épuisé, le point de terminaison renvoie un 200 avec data.limit_reached: true au lieu de générer une réponse.

Erreurs

• 401 - aucune clé API fournie.
• 404 - la clé ne correspond à aucun espace de travail (par exemple après une rotation).
• 403 plan_upgrade_required - l'espace de travail n'est pas sur le plan Business.
• 403 - l'abonnement est inactif, ou la requête provient d'un domaine non autorisé par les paramètres du widget.
• 422 - le message est absent (et aucun fichier n'a été joint).