API chatbot
Une API chatbot pour vos applications, votre backend et vos données
L'API REST d'intoCHAT permet à votre serveur de parler à l'agent que vous avez entraîné dans le tableau de bord. Envoyez un message et recevez la même réponse que dans le widget de chat, lisez les conversations et les leads, synchronisez les contacts, ajoutez des connaissances et abonnez des webhooks, en JSON sur HTTPS, avec une spécification OpenAPI 3.1 qui décrit chaque point de terminaison.
Votre chatbot ne devrait pas s’arrêter au widget du site
Le widget couvre les visiteurs de votre site. Mais les mêmes questions arrivent aussi dans votre application mobile, votre portail client, un outil interne ou un formulaire de support, et les conversations et leads que l'agent recueille ont leur place dans votre CRM, votre entrepôt de données ou votre outil de tickets, pas seulement dans un tableau de bord. Reconstruire le bot pour chaque endroit, c'est maintenir une deuxième base de connaissances et un deuxième jeu de règles qui finissent par diverger. Une API chatbot permet à chaque canal que vous construisez d'utiliser le seul agent que vous avez déjà entraîné, et à vos propres systèmes de lire ce qu'il a recueilli.
Ce que l’API chatbot vous apporte
Un agent, entraîné une fois, qui répond partout où tourne votre code.
Même agent, mêmes réponses
Une réponse via l’API est écrite par le même code qu’une réponse dans le widget, avec les mêmes connaissances, les mêmes instructions et le même modèle. Vos actions API, boutons personnalisés, formulaires de chat et prises de rendez-vous fonctionnent aussi dans les chats via l’API.
Des conversations qui continuent
Transmettez votre propre sessionId, par exemple l'ID de l'utilisateur, et la même personne poursuit toujours la même conversation. L'agent voit les 40 derniers messages comme historique, et chaque chat via l'API apparaît dans l'onglet Conversations à côté des chats du widget.
Vos données dans vos systèmes
Parcourez les conversations avec leurs transcriptions complètes, les leads avec leurs champs personnalisés et les contacts, du plus récent au plus ancien, avec le paramètre since pour des synchronisations incrémentales. L'ordre est fixe : rien n'est lu deux fois ni oublié pendant que de nouveaux chats arrivent.
Une clé à scopes limités par usage
Donnez à chaque intégration sa propre clé avec uniquement les scopes nécessaires, par exemple conversations:read pour un rapport et chat pour votre application. Les clés appartiennent au compte, pas à une personne, et cessent de fonctionner dès que vous les révoquez.
Une spécification OpenAPI pour démarrer
Chaque point de terminaison, champ, erreur et contenu de webhook est décrit dans un seul fichier OpenAPI 3.1. Importez-le dans Postman ou Insomnia, ou générez une bibliothèque cliente avec un outil comme OpenAPI Generator.
Comment démarrer avec l’API chatbot
Entraînez votre agent
Créez l'agent dans le tableau de bord, ajoutez votre site, vos fichiers ou des Q&R, et définissez ses instructions et son modèle. L'API utilise l'agent exactement tel qu'il y est configuré ; les agents se créent et se modifient dans le tableau de bord, pas via l'API.
Créez une clé API
Dans la barre latérale, sous Settings, cliquez sur API keys. Nommez la clé, gardez Every scope, including ones added later ou choisissez Only the scopes I choose, puis cliquez sur Create key. Copiez la clé, qui commence par ic_live_, dans une variable d’environnement de votre serveur : elle n’est affichée qu’une seule fois.
Envoyez votre premier message
Envoyez le message en POST à /api/v1/agents/{agentId}/chat, avec la clé comme jeton Bearer dans l'en-tête Authorization. La réponse JSON contient le texte, le conversationId et le sessionId pour continuer, les sources utilisées et, le cas échéant, des questions de suivi, boutons, produits, formulaires ou créneaux de rendez-vous. Avec stream à true, vous recevez le texte au fur et à mesure.
Synchronisez et abonnez-vous
Lisez régulièrement les conversations, leads et contacts avec since, ajoutez des textes ou des paires Q&R quand vos contenus changent, et abonnez un webhook à des événements comme lead.created ou handoff.requested, pour qu'ils parviennent à votre serveur dès qu'ils se produisent.
L’API chatbot en détail
Envoyer un message
Le point de terminaison de chat accepte un message de 10 000 caractères au plus, un conversationId ou sessionId facultatif pour continuer, stream pour un texte en streaming et timeZone pour les horaires de rendez-vous. Sans l'un de ces identifiants, chaque message ouvre une nouvelle conversation.
Des champs de réponse structurés
En plus de la réponse en Markdown, la réponse de l’API liste les pages utilisées, les questions de suivi suggérées, les boutons personnalisés, les fiches produits avec prix et disponibilité, un formulaire de chat ou de contact proposé, les créneaux libres, des blocs de réponses enrichies comme des tableaux et des cartes, et l’état du chat en direct.
Tient compte du chat en direct
Si un membre de votre équipe a pris la conversation dans la boîte de réception du chat en direct, votre message est enregistré, la réponse reste vide et liveChat vaut paused. Lisez les réponses de votre collègue, avec son prénom, via le point de terminaison de la conversation. Ces messages ne consomment aucun message de votre offre.
Conversations et Inbox
Listez les conversations d'un agent, venues du widget et de l'API, avec thèmes, sentiment, état du chat en direct et note CSAT, filtrez-les par statut dans l'Inbox et récupérez-en une avec tous ses messages. Avec conversations:write, vous définissez son statut, sa priorité, ses tags et son responsable.
Leads et contacts
Listez les leads avec nom, e-mail, téléphone et les champs personnalisés de votre formulaire. Créez ou mettez à jour des contacts par votre propre identifiant externe ou par e-mail, chacun avec jusqu'à 50 attributs personnalisés, pour que les contacts de l'agent correspondent aux utilisateurs de votre application.
Des connaissances à jour
Listez les sources d'un agent avec leur état d'entraînement, ajoutez un texte ou une paire Q&R, entraînée aussitôt, et supprimez une source avec tout ce que l'agent en avait appris. Une paire Q&R avec la même question est mise à jour plutôt que dupliquée.
Webhooks et événements
Abonnez jusqu'à 25 webhooks par agent à des événements comme lead.created, form.submitted, booking.created, handoff.requested et conversation.status_changed, chacun signé avec son propre secret. Ou interrogez les derniers événements d'un type, structurés exactement comme une livraison de webhook.
Des limites et des erreurs claires
Chaque clé peut faire 60 requêtes par minute, et chaque réponse porte les en-têtes X-RateLimit. Les erreurs ont toujours la même forme JSON avec un code stable, comme insufficient_scope, rate_limited ou message_limit_reached, pour que votre code puisse traiter chaque cas.
Questions fréquentes
Qu’est-ce qu’une API chatbot ?
Une API chatbot permet à votre propre logiciel d'envoyer des messages à un chatbot et de recevoir ses réponses, au lieu de passer uniquement par une fenêtre de chat sur un site. L'API REST d'intoCHAT le fait pour l'agent que vous avez entraîné dans le tableau de bord, et permet aussi à votre serveur de lire ses conversations, leads et contacts, de mettre à jour ses connaissances et de s'abonner à ses événements.
Quelle offre faut-il pour l’API ?
L'API est incluse dans les offres Starter, Pro et Enterprise. Avec l'offre Free, vous ne pouvez pas créer de clés. Si un compte repasse en Free, ses clés existantes répondent à chaque requête par l'erreur plan_required, et fonctionnent de nouveau dès que le compte est au moins en Starter.
Les réponses via l’API comptent-elles comme des messages ?
Oui. Chaque réponse que l'agent écrit via l'API compte sur votre offre exactement comme une réponse dans le widget : un message avec le modèle par défaut, davantage avec un modèle plus grand, et elle compte aussi dans le plafond mensuel de l'agent si vous en avez fixé un. Lire les conversations, leads et contacts, et ajouter ou supprimer des sources, ne consomme aucun message.
Puis-je appeler l’API depuis un navigateur ou mon code d’intégration ?
Non. L'API est destinée aux serveurs : elle n'envoie pas d'en-têtes CORS, et une clé dans une page web pourrait être copiée par n'importe qui. Pour afficher un chat sur votre site, utilisez la balise script ou le SDK JavaScript, et appelez l'API depuis votre backend. Seule la spécification OpenAPI peut être chargée depuis n'importe quel site.
Comment poursuivre une conversation ?
Envoyez le conversationId d'une réponse précédente, ou votre propre sessionId, par exemple l'ID de l'utilisateur : le même sessionId poursuit toujours la même conversation. Seules les conversations commencées via l'API peuvent être poursuivies via l'API, et l'agent voit les 40 derniers messages comme historique.
Quelles sont les limites de débit ?
Chaque clé peut faire 60 requêtes par minute, tous points de terminaison confondus, et un compte peut avoir jusqu'à 20 clés actives. Un agent répond à 1 000 messages par heure au plus, widget et API confondus, et une réponse doit être terminée en 55 secondes, sinon la requête se termine par une erreur de timeout.
Que ne fait pas encore l’API ?
Il n'existe pas encore de points de terminaison pour créer ou modifier des agents, envoyer des formulaires de chat, réserver des rendez-vous ou prendre la main sur un chat en direct. Via l'API, vous ajoutez des textes et des paires Q&R ; les pages web, fichiers et pages Notion s'ajoutent dans le tableau de bord. Les messages via l'API ne peuvent pas contenir de fichiers, et les actions client, qui s'exécutent dans le navigateur d'un visiteur, ne sont pas proposées dans les chats via l'API.
Quelle différence avec les actions IA ?
Elles vont dans des sens opposés. Avec les actions IA, l'agent appelle votre API pendant un chat pour vérifier quelque chose, comme une commande ou un compte. Avec l'API chatbot, c'est votre serveur qui appelle intoCHAT pour envoyer des messages et lire des données. Beaucoup de configurations utilisent les deux.
Construisez sur l’agent que vous avez déjà entraîné
Créez votre agent gratuitement et entraînez-le sur votre site, puis passez à Starter, créez une clé API et envoyez votre premier message avec une seule commande curl.
Créer votre agent gratuitementOffre gratuite, sans carte bancaire.