> ## Documentation Index > Fetch the complete documentation index at: https://docs.bookivox.com/llms.txt > Use this file to discover all available pages before exploring further. # Intégration : Brevo > Connectez Brevo à Bookivox pour que vos agents envoient e-mails et SMS et consultent vos contacts pendant l'appel. ## À quoi ça sert L'intégration **Brevo** relie votre compte d'envoi à vos agents vocaux. Pendant l'appel, l'agent peut **envoyer un SMS**, **envoyer un e-mail**, **créer un contact** et **consulter vos contacts, vos listes, vos gabarits et vos expéditeurs**. Par exemple : confirmer un rendez-vous par SMS, envoyer un devis par e-mail, ou vérifier qu'un client est déjà connu. Comme pour les autres intégrations, vous branchez **votre propre compte** : Bookivox ne fournit aucun identifiant et ne détient aucune clé. Les envois consomment **vos crédits** Brevo. > [!NOTE] > > L'intégration **écrit réellement** dans votre compte : un SMS ou un e-mail part > réellement vers le destinataire, et un contact créé apparaît dans Brevo. Aucune > mise à jour ni suppression par identifiant n'est exposée. ## Ce qu'il faut préparer | Élément | D'où il vient | Format attendu | | - | - | - | | **Clé API v3** | Brevo : **Paramètres → Clés API → Générer une clé v3** | Chaîne commençant par `xkeysib-` | | **Contacts à jour** | Votre compte Brevo | Contacts créés ou synchronisés | | **Listes à jour** | Votre compte Brevo | Listes publiées avec leurs abonnés | | **Crédits e-mail et SMS** | Votre compte Brevo | Crédits disponibles sur le plan | | **Expéditeur SMS validé** | Brevo : **SMS → Expéditeurs** | 11 caractères alphanumériques maximum, ou 15 chiffres | | **Adresse d'envoi validée** | Brevo : **Expéditeurs et IP** | Domaine et adresse vérifiés | > [!WARNING] > > La clé v3 n'est affichée **qu'une seule fois**, au moment de sa génération. Si > vous la perdez, supprimez-la et générez-en une nouvelle. ## Connecter Brevo **1. Générer la clé** Dans Brevo, ouvrez **Paramètres → Clés API**, puis **Générer une clé v3**. Copiez la valeur affichée : elle commence par `xkeysib-`. **2. Coller la clé** Dans **Intégrations → Brevo**, collez la clé telle quelle, **sans préfixe** `Bearer`. Bookivox l'envoie dans l'en-tête `api-key`. **3. Cocher les actions** Sélectionnez les actions utiles. Chacune devient un **outil indépendant**. **4. Vérifier la connexion** Cliquez sur **Créer les outils**. Bookivox appelle `GET /v3/account` avec la clé : un bandeau **vert** confirme la connexion, une erreur est affichée sinon. **5. Attacher les outils** Rattachez les outils utiles à un nœud agent. Ils s'exécutent **pendant l'appel**. ## Ce que l'agent peut faire | Action | Usage | Exemple de demande | | - | - | - | | **Lire le compte** (`get_account`) | Entreprise, plan et options rattachés à la clé | « Quel est le plan de notre compte ? » | | **Lister les contacts** (`list_contacts`) | Contacts paginés, filtrables par date de création ou de modification | « Retrouve le contact créé cette semaine. » | | **Lister les listes de contacts** (`list_contact_lists`) | Listes du compte avec leur nombre d'abonnés | « Combien d'abonnés dans la liste newsletter ? » | | **Créer un contact** (`create_contact`) | Crée la fiche ou complète une fiche existante, éventuellement dans une liste | « Enregistrez mes coordonnées et inscrivez-moi à la newsletter. » | | **Envoyer un SMS** (`send_sms`) | Envoie un SMS transactionnel depuis l'expéditeur validé | « Confirmez-moi le rendez-vous par SMS. » | | **Envoyer un e-mail** (`send_email`) | Envoie un e-mail transactionnel à un ou plusieurs destinataires | « Envoyez-moi le devis par e-mail. » | | **Lister les gabarits d'e-mail** (`list_email_templates`) | Gabarits du compte, avec leurs identifiants | « Utilisez notre modèle de confirmation. » | | **Lister les expéditeurs** (`list_senders`) | Adresses d'envoi validées dans le compte | « Depuis quelle adresse partent nos e-mails ? » | Les paramètres de lecture sont **facultatifs** : `limit`, `offset`, `modifiedSince`, `createdSince` et `sort` pour les contacts ; `limit`, `offset` et `sort` pour les listes et les gabarits. Pour les envois, l'agent fournit l'expéditeur, le destinataire et le contenu : le SMS exige `sender`, `recipient` et `content`, l'e-mail exige `sender`, `to`, `subject` et `htmlContent`. La clé n'est **jamais** un paramètre : elle est injectée par la credential. > [!NOTE] > > Les plafonds diffèrent : les contacts acceptent jusqu'à **1000** résultats par > appel (`50` par défaut), les listes seulement **50** (`10` par défaut). Un SMS > compte **160 caractères par segment** : au-delà, le message est envoyé en > plusieurs segments facturés. Les valeurs de `attributes` doivent utiliser des > clés déjà définies dans Brevo. ## Cas d'usage | Cas d'usage | Ce que fait l'agent | Résultat pour le client | | - | - | - | | **Confirmer un rendez-vous par SMS** | L'agent appelle `send_sms` avec l'expéditeur validé, le numéro du client et le créneau retenu. | Le client reçoit la confirmation sur son téléphone avant la fin de l'appel. | | **Envoyer un devis par e-mail** | L'agent appelle `send_email` avec l'adresse d'envoi validée et le contenu préparé pendant l'appel. | Le document part immédiatement, sans passer par une boîte partagée. | | **Inscrire un prospect à une liste** | L'agent appelle `create_contact` avec `email`, `listIds` et `updateEnabled` à `true`, après avoir vérifié la fiche avec `list_contacts`. | Le prospect est créé ou mis à jour et reçoit la campagne de la liste. | | **Reconnaître un inscrit récent** | Le client dit s'être inscrit la veille : l'agent appelle `list_contacts` avec `createdSince` fixé à la veille, puis confirme la présence du contact. | Le parcours reprend là où le client s'est arrêté, sans redemander ses informations. | | **Choisir le bon gabarit** | L'agent appelle `list_email_templates` pour retrouver l'identifiant du modèle de confirmation, puis `send_email` avec ce contenu. | L'e-mail respecte la charte déjà validée par l'entreprise. | | **Annoncer la taille d'une liste** | Le client demande combien de personnes reçoivent la newsletter : l'agent appelle `list_contact_lists` et lit le nombre d'abonnés de la liste citée. | Un chiffre exact, donné pendant l'appel et sans ouvrir Brevo. | ## Comment ça marche 1. Bookivox crée une **credential** `api_key` dont l'en-tête est `api-key` et la valeur la clé brute : le schéma Brevo est `apiKey`, donc **sans** préfixe `Bearer`. 2. Les lectures (`limit`, `offset`, `modifiedSince`, `createdSince`, `sort`) partent en **query params** sur l'URL fixe `https://api.brevo.com`. 3. Les envois et la création de contact partent en **corps JSON** vers une URL fixe : `/v3/transactionalSMS/send`, `/v3/smtp/email` et `/v3/contacts`. Le chemin n'est **jamais** construit à partir d'une valeur du modèle. 4. Chaque action cochée devient un **outil `http_api`** avec `config.provider = "brevo"`, `config.operation` et un **timeout de 10 000 ms**. 5. Brevo renvoie le résultat en JSON, que l'outil restitue à l'agent. ## Rédiger la description de l'outil La description décide **quand** l'agent appelle Brevo. Rédigez-la comme une consigne : ``` Utiliser cet outil pour confirmer par SMS un rendez-vous déjà accepté par le client, et pour envoyer un devis uniquement après avoir relu l'adresse e-mail. Ne jamais inventer d'expéditeur : utiliser celui validé dans Brevo, et ne pas communiquer l'adresse e-mail complète sans confirmation du client. ``` > [!WARNING] > > Les données renvoyées sont **personnelles** (e-mail, téléphone, attributs). Ne > demandez à l'agent que les champs nécessaires et ne les recopiez pas dans un > compte rendu d'appel accessible à tous. ## Sécurité | Risque | Ce que fait le preset | | - | - | | **Clé exposée** | Elle vit dans une **credential** chiffrée, jamais dans la définition de l'outil ni dans un prompt. Elle n'est jamais réaffichée. | | **Envoi non voulu** | Seules les actions cochées sont créées : sans `send_sms` ni `send_email`, l'agent ne peut rien envoyer. Chaque envoi part vers un destinataire fourni pendant l'appel et consomme vos crédits. | | **Expéditeur usurpé** | Brevo n'accepte que les expéditeurs **validés dans le compte** : un nom inconnu est refusé, et l'adresse e-mail doit figurer parmi les expéditeurs vérifiés. | | **Détournement d'URL** | L'URL de base est figée sur `https://api.brevo.com` : l'outil ne peut pas viser un autre service. | | **Injection de chemin** | Les valeurs dynamiques partent en **query params** (GET) ou en **corps JSON** (POST) ; aucun segment de chemin n'est construit depuis le modèle. | | **Suppression ou mise à jour massive** | Aucune action ne prend d'identifiant de contact ou de campagne : les endpoints de suppression et de modification par identifiant ne sont pas exposés. | | **Erreur silencieuse** | La connexion est **testée avant validation** avec `GET /v3/account`. | | **Données personnelles** | L'agent ne reçoit que ce que l'API renvoie pour les actions cochées : pas d'export global. | ## Ce qui est déconseillé | Usage | Pourquoi | | - | - | | **Préfixe `Bearer` ajouté** | Brevo attend la clé **brute** dans `api-key` ; un préfixe provoque une erreur `401`. | | **Clé d'un autre compte** | Les contacts lus et les envois partiraient depuis un autre compte : utilisez la clé du compte concerné. | | **Utiliser une clé SMTP** | Les identifiants SMTP ne fonctionnent pas sur l'API v3 ; il faut une **clé API v3**. | | **Envoyer un SMS sans expéditeur validé** | Brevo refuse l'envoi (`400`) : déclarez l'expéditeur dans **SMS → Expéditeurs** avant de cocher l'action. | | **Compter sur un SMS marketing la nuit** | En France, les SMS marketing sont mis en file entre **22 h et 8 h**, le dimanche et les jours fériés ; ils partent plus tard, sans erreur. | | **Mot STOP dans un SMS de service** | Un code STOP dans `content` bascule le message en **marketing** : retirez-le d'un SMS transactionnel. | | **Pagination oubliée** | Les listes sont plafonnées à **50** résultats : au-delà, utilisez `offset`. | | **Tâches planifiées** | Un outil d'agent s'exécute **pendant l'appel**, pas en tâche de fond. | ## Limites et dépannage | Symptôme | Cause probable | Correction | | - | - | - | | Erreur `401` | Clé invalide, révoquée, espace ajouté, ou préfixe `Bearer`. | Recopier la clé brute, sans espace ni préfixe. | | Erreur `400` | Paramètre mal formé (`sort`, date, `limit` hors bornes), expéditeur non validé ou contenu vide. | Corriger la valeur ; `sort` vaut `asc` ou `desc`, l'expéditeur doit être validé dans Brevo. | | Erreur `402` | Crédits SMS ou e-mail épuisés. | Recharger les crédits dans Brevo, puis relancer l'envoi. | | Erreur `429` | Trop de requêtes. | Espacer les appels ; Brevo applique ses propres quotas. | | Erreur `5xx` | Incident côté Brevo. | Réessayer plus tard ; contacter Brevo si cela dure. | | Le test de connexion échoue | La clé est révoquée ou appartient à un autre compte. | Générer une nouvelle clé v3 dans Brevo. | | Contacts vides | Aucun contact dans le compte, ou filtre trop restrictif. | Retirer `modifiedSince` / `createdSince` et relancer. | | SMS non reçu | Numéro sans indicatif, expéditeur non validé, ou crédits épuisés. | Vérifier le format `33680005003`, l'expéditeur et les crédits. | | E-mail refusé | Adresse d'envoi non vérifiée, ou `sender` mal formé. | Valider l'expéditeur dans Brevo et fournir un objet `{ "name", "email" }`. | | L'agent répond « de tête » | L'outil n'est pas attaché à l'agent, ou il est inactif. | L'activer et l'attacher au nœud agent. | > [card] [Intégrations](https://docs.bookivox.com/integrations/overview.md) > > Toutes les intégrations et les catégories d'outils. > [card] [API HTTP](https://docs.bookivox.com/integrations/http-api.md) > > Comprendre les outils HTTP : paramètres, presets, credentials. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.