Bookivox Documentation

À 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.

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

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

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-.

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.

Cocher les actions

Sélectionnez les actions utiles. Chacune devient un outil indépendant.

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.

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.

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

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.
Les lectures (limit, offset, modifiedSince, createdSince, sort) partent en query params sur l’URL fixe https://api.brevo.com.
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.
Chaque action cochée devient un outil http_api avec config.provider = "brevo", config.operation et un timeout de 10 000 ms.
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.

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.

Intégrations

Toutes les intégrations et les catégories d’outils.

API HTTP

Comprendre les outils HTTP : paramètres, presets, credentials.

Prise en main

LABS

Construire

Préparer

Piloter

Revendeur (White-label)

Intégration : Brevo

À quoi ça sert

Ce qu’il faut préparer

Connecter Brevo

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage

Intégrations

API HTTP

​À quoi ça sert

​Ce qu’il faut préparer

​Connecter Brevo

​Ce que l’agent peut faire

​Cas d’usage

​Comment ça marche

​Rédiger la description de l’outil

​Sécurité

​Ce qui est déconseillé

​Limites et dépannage

Intégrations

API HTTP

À quoi ça sert

Ce qu’il faut préparer

Connecter Brevo

Ce que l’agent peut faire

Cas d’usage

Comment ça marche

Rédiger la description de l’outil

Sécurité

Ce qui est déconseillé

Limites et dépannage