Quand utiliser l'API REST d'AI SNS CHAT, comment la sécuriser et la tester : clés, streaming SSE, webhooks signés et limites de débit.
Votre agent répond déjà bien sur le chat de votre site, mais vous aimeriez qu'il s'intègre à votre propre application, à votre extranet ou à un outil maison. C'est précisément le rôle de l'API REST d'AI SNS CHAT. Cet article vous explique quand elle est pertinente, quels sont ses éléments de base, comment respecter les limites publiées et comment la mettre en production sans mauvaise surprise.
Quand l'API est le bon outil (et quand elle ne l'est pas)
Une API donne de la liberté, mais elle crée aussi du code à maintenir. Avant de vous lancer, posez-vous une question simple : existe-t-il déjà une voie native pour ce que vous voulez faire ?
L'API est pertinente dans les cas suivants :
- vous voulez afficher les réponses de l'agent dans votre propre interface (application mobile, espace client, intranet) ;
- vous devez déclencher une action dans votre système (création d'un dossier, mise à jour d'une fiche) lorsqu'un événement survient dans AI SNS CHAT ;
- vous avez un parcours très spécifique que les canaux standard ne couvrent pas.
Elle n'est pas nécessaire dans les cas suivants :
- vous voulez simplement l'agent sur WhatsApp, Messenger, Instagram ou le chat de votre site : ces canaux se déploient depuis le menu Canaux, sans écrire une ligne de code ;
- vous voulez ajouter une base de connaissances : les sources de données (fichiers, site web, Notion, Google Drive, etc.) s'en chargent ;
- vous voulez collecter des contacts : l'action « Collecter des leads » existe déjà.
Les briques de base
L'API d'AI SNS CHAT est une API REST au format JSON. Trois éléments suffisent à comprendre l'ensemble.
Les clés d'API
Elles se créent dans les paramètres de l'espace de travail, rubrique Clés d'API. Une clé n'est affichée qu'une seule fois : copiez-la immédiatement dans votre gestionnaire de secrets. Elle est révocable à tout moment. L'accès aux clés exige le forfait Hobby ou supérieur.
Le streaming SSE
Pour qu'une réponse s'affiche mot après mot, comme dans un vrai chat, l'API prend en charge le streaming en SSE (Server-Sent Events) avec le paramètre stream=1. Votre interface n'attend plus la réponse complète : l'utilisateur voit le texte arriver, ce qui rend l'échange plus vivant, surtout sur mobile.
Les webhooks signés
AI SNS CHAT peut vous notifier d'un événement par webhook. Chaque envoi est signé par HMAC et un journal de livraison permet de vérifier ce qui a été envoyé et reçu. C'est la base d'une intégration fiable.
Respectez les limites de débit publiées
La documentation de l'API publie les limites suivantes :
| Point d'accès | Limite |
|---|---|
| Authentification | 20 requêtes par 5 minutes et par IP |
| Chat public | 30 requêtes par minute et par IP |
| Interrogation (poll) | 120 requêtes par minute |
Quelques conséquences pratiques :
- Si votre site passe par un serveur unique qui relaie les messages, toutes les conversations partagent la même adresse IP : la limite de 30 par minute s'applique alors à l'ensemble. Faites un calcul de charge réaliste. Par exemple, si votre boutique reçoit 300 conversations par mois, vous êtes très loin du plafond ; une campagne qui concentre des centaines de visiteurs en quelques minutes est un autre sujet.
- Préférez le streaming SSE à des interrogations répétées : vous consommez moins de requêtes.
- Prévoyez une nouvelle tentative avec attente progressive en cas de refus, plutôt qu'une boucle qui insiste.
- Ne vous authentifiez pas à chaque message : réutilisez votre session ou votre clé.
Schémas de conception qui fonctionnent
- 01Votre interface ou application
- 02Votre serveur (clé d'API)
- 03API REST AI SNS CHAT
- 04Webhook signé vers votre système
Un serveur intermédiaire plutôt que le navigateur
Ne placez jamais votre clé d'API dans le code d'une page web ou d'une application mobile : n'importe qui pourrait la lire. Faites passer les appels par un petit serveur à vous, qui détient la clé et relaie les messages.
Réagir par webhook, pas par sondage
Pour déclencher une action chez vous (ouvrir un dossier, prévenir un collaborateur), écoutez le webhook plutôt que d'interroger l'API en boucle. Vous économisez des requêtes et vous réagissez plus vite.
Rendre vos traitements idempotents
Un même événement peut vous parvenir deux fois, par exemple après une nouvelle tentative. Conservez l'identifiant de l'événement et ignorez les doublons.
Dégrader proprement
Si votre serveur ou l'API est momentanément indisponible, affichez un message clair et proposez une alternative (un formulaire de contact, par exemple) au lieu d'un écran vide.
Liste de contrôle de sécurité avant la mise en ligne
- Clé en lieu sûr : stockée côté serveur, jamais dans le code client, jamais dans un dépôt public. Une clé affichée une seule fois, c'est aussi une raison de la ranger tout de suite.
- Une clé par usage : si l'une est compromise, vous la révoquez sans couper le reste.
- Vérification de la signature : rejetez tout webhook dont la signature HMAC ne correspond pas.
- HTTPS partout pour votre point de réception.
- Minimisation des données : n'envoyez et ne stockez que ce qui est utile. Dans le cadre du RGPD, c'est un réflexe à adopter dès la conception, y compris pour les conversations passant par WhatsApp ou Messenger.
- Journaux sobres : ne consignez ni clé ni contenu sensible dans vos propres logs.
- Rotation : changez vos clés à intervalle régulier et lors de chaque départ d'un collaborateur qui y avait accès.
Les pratiques d'AI SNS CHAT sont conçues en référence au RGPD et à l'APPI. Cela ne dispense pas de documenter vos propres traitements ; voir la page sécurité pour le détail de ce que fait la plateforme.
Tests et déploiement progressif
- Testez d'abord dans le Playground : validez le comportement de l'agent (persona, sources, ton) avant d'y brancher du code. Si la réponse est mauvaise, ce n'est pas un problème d'API.
- Créez un agent de test (la duplication d'agent copie persona, modèle et données d'entraînement, sans les conversations) et branchez-y votre intégration.
- Simulez les cas d'erreur : clé révoquée, limite atteinte, webhook en double, signature invalide.
- Déployez à un petit groupe : une page, une équipe interne ou un faible pourcentage de visiteurs.
- Surveillez les journaux de livraison des webhooks et les journaux de conversations (Activité → Journaux de chat), puis élargissez.
- Gardez un retour arrière : les points de restauration de l'agent (jusqu'à 40 par agent) permettent de revenir en arrière si un changement de configuration dégrade les réponses.
Mettre cela en œuvre dans AI SNS CHAT
Voici le parcours concret, étape par étape.
- Vérifiez votre forfait. Les clés d'API et les intégrations nécessitent Hobby ou supérieur. Les tarifs en vigueur sont sur la page tarifs.
- Créez la clé. Ouvrez les paramètres de l'espace de travail, puis Clés d'API. Copiez la clé à l'affichage : elle ne sera plus visible ensuite. Vous pouvez la révoquer à tout moment.
- Consultez la référence de l'API. Elle décrit les points d'accès JSON, le streaming avec
stream=1et la signature HMAC des webhooks. - Regardez la fiche du canal API. Dans la barre latérale, Canaux contient une entrée API, aux côtés du widget de chat, de WhatsApp, de Messenger, d'Instagram, de Slack et de bien d'autres. La page connexions donne la vue d'ensemble.
- Testez l'agent dans le Playground, puis comparez deux modèles avec la comparaison A/B si vous hésitez.
- Suivez le résultat. Les conversations de tous les canaux autres que l'e-mail apparaissent dans Activité → Journaux de chat, où vous pouvez filtrer, signaler, escalader ou exporter. L'Inbox, elle, est réservée aux e-mails.
- Consommation. Une réponse coûte un crédit ; la page Utilisation montre les crédits par agent. Un client dont le trafic augmente peut activer la recharge automatique, dont les crédits n'expirent pas.
Si vous voulez aussi que vos clients utilisent votre propre adresse, la fonction Domaines personnalisés (Agent → Paramètres, Hobby ou supérieur) couvre le script d'intégration, l'iframe et le lien de l'agent via un sous-domaine en CNAME. Et si vous hésitez sur un réglage, Synthia, la gestionnaire de flotte intégrée, peut vous guider à l'écran. Pour un panorama des fonctions, voir fonctionnalités.
Conclusion
L'API REST est un excellent outil lorsque les canaux natifs ne suffisent pas, et un détour inutile lorsqu'ils suffisent. Retenez trois principes : gardez la clé côté serveur, vérifiez chaque signature de webhook, et respectez les limites publiées. Avec un déploiement progressif et un agent de test, vous étendez AI SNS CHAT sans risquer votre service au quotidien. Vous pouvez créer un compte pour essayer le Playground avant de décider.
Questions fréquentes
Quel forfait faut-il pour utiliser l'API REST ?
Les clés d'API sont disponibles à partir du forfait Hobby. Elles se créent dans les paramètres de l'espace de travail, sont affichées une seule fois et restent révocables. Les prix actuels figurent sur la page des tarifs.
Puis-je diffuser les réponses en continu dans ma propre interface ?
Oui. L'API prend en charge le streaming SSE avec le paramètre stream=1. Votre interface affiche alors le texte au fur et à mesure de sa génération, sans attendre la réponse complète.
Comment savoir qu'un webhook vient bien d'AI SNS CHAT ?
Les webhooks sont signés par HMAC. Votre serveur doit recalculer la signature avec le secret partagé et rejeter toute requête qui ne correspond pas. Un journal de livraison vous permet aussi de contrôler les envois.
Quelles sont les limites de débit ?
La documentation publie 20 requêtes par 5 minutes et par IP pour l'authentification, 30 par minute et par IP pour le chat public, et 120 par minute pour l'interrogation (poll). Prévoyez une attente progressive en cas de refus.
Ai-je besoin de l'API pour mettre un agent sur WhatsApp ou Messenger ?
Non. WhatsApp et Messenger sont des canaux natifs, déployés depuis le menu Canaux sans code. L'API ne devient utile que si vous construisez une interface ou un traitement sur mesure.


