Bookivox Documentation

À quoi ça sert

L’intégration HubSpot relie votre CRM à vos agents vocaux. Pendant l’appel, l’agent peut retrouver une fiche contact, créer un contact, journaliser l’appel, puis laisser une trace exploitable : note, tâche de suivi, affaire dans le pipeline ou ticket support, avec un rattachement optionnel à une fiche existante. Comme pour les autres intégrations, vous branchez votre propre compte : Bookivox ne fournit aucun identifiant. Vous créez une application privée dans HubSpot, copiez son jeton, puis cochez les actions à exposer.

Cette intégration écrit réellement dans votre CRM : un contact, une note, une tâche, une affaire, un ticket ou un appel journalisé apparaissent dans HubSpot. Le client fournit sa propre clé ; Bookivox ne fournit aucun identifiant.

Ce qu’il faut préparer

Élément	D’où il vient	Format attendu
Jeton d’accès	HubSpot : Paramètres → Intégrations → Applications privées, avec les droits CRM sur les objets Appels, Contacts, Notes, Tâches, Affaires et Tickets	Chaîne commençant par `pat-`, affichée une seule fois à la création de l’application

Les droits se règlent sur l’application privée elle-même. Sans accès à l’objet visé (Appels, Contacts, Notes, Tâches, Affaires ou Tickets), l’outil est refusé (403) même si le jeton est valide.

Connecter HubSpot

Créer l'application privée

Dans HubSpot, ouvrez Paramètres → Intégrations → Applications privées et créez une application dédiée à Bookivox.

Accorder les droits CRM

Autorisez la lecture et l’écriture sur les objets Contacts, Appels, Notes, Tâches, Affaires et Tickets, selon les actions que vous voulez exposer.

Copier le jeton

Générez le jeton de l’application et copiez-le : il commence par pat- et n’est affiché qu’une fois.

Saisir la clé

Dans Intégrations → HubSpot, collez le jeton. Le formulaire vérifie qu’il commence par pat- avant l’enregistrement.

Cocher les actions

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

Vérifier la connexion

Cliquez sur Créer les outils. Un bandeau vert confirme la création et indique le nombre d’outils créés. Le jeton disparaît du formulaire : il reste chiffré et n’est plus jamais réaffiché.

Compléter la connexion

La carte Connexions HubSpot liste les comptes reliés à l’organisation avec leur état (Complète ou Partielle). Le bouton Créer ajoute une action manquante sans ressaisir le jeton.

Ce que l’agent peut faire

Action	Usage	Exemple de demande
Enregistrer un appel (`create_call`)	Journalise l’appel dans HubSpot, rattachable à une fiche contact	« Notez bien que j’ai appelé pour mon devis. »
Créer un contact (`create_contact`)	Crée une fiche contact à partir des informations données	« Créez-moi une fiche, je ne suis pas encore client. »
Rechercher un contact (`search_contacts`)	Retrouve une fiche contact par nom, e-mail ou téléphone	« Vous avez déjà mes coordonnées ? »
Rédiger une note (`create_note`)	Ajoute une note au fil d’une fiche contact ou entreprise	« Marquez dans mon dossier que je rappelle lundi. »
Créer une tâche (`create_task`)	Planifie une tâche de suivi avec échéance et priorité	« Prévoyez un rappel pour la semaine prochaine. »
Créer une affaire (`create_deal`)	Ouvre une affaire dans le pipeline et la rattache au contact	« Ouvrez une affaire pour mon projet de rénovation. »
Ouvrir un ticket (`create_ticket`)	Ouvre un ticket support rattaché au contact qui a appelé	« Ouvrez un incident, ma box ne fonctionne plus. »

Chaque action crée un outil distinct : vous pouvez n’en activer qu’une partie, et n’attacher à un agent que celles dont il a besoin.

Les écritures Appels, Notes et Tâches exigent hs_timestamp (epoch en millisecondes ou date ISO 8601 UTC). Les valeurs de properties sont toujours des chaînes, jamais des nombres. Le rattachement à une fiche se fait par associations, jamais par un chemin avec identifiant.

Cas d’usage

Cas d’usage	Ce que fait l’agent	Résultat pour le client
Journaliser l’appel	L’agent appelle `create_call` avec `hs_timestamp` et le résumé de l’échange.	L’appel laisse une trace exploitable dans le CRM, même sans suite commerciale.
Rattacher l’appel au bon contact	L’agent appelle `search_contacts`, puis `create_call` avec l’association vers la fiche trouvée.	L’historique reste groupé par client, pas dans des fiches orphelines.
Créer la fiche d’un prospect	L’agent appelle `create_contact` avec les informations données pendant l’appel, en valeurs texte.	Le prospect est créé avec des valeurs conformes au preset.
Éviter les doublons	Avant toute création, l’agent appelle `search_contacts` pour vérifier que la fiche n’existe pas déjà.	La base reste propre et le client ne reçoit pas deux relances.
Consigner une précision en note	L’agent appelle `create_note` avec `hs_note_body` et l’association vers la fiche du contact.	L’information reste attachée au dossier, pas seulement dans l’enregistrement de l’appel.
Programmer un rappel	L’agent appelle `create_task` avec l’échéance dans `hs_timestamp`, une priorité et le type `CALL` ou `EMAIL`.	Le commercial retrouve une tâche datée dans son tableau de bord, sans ressaisie.
Ouvrir une opportunité	L’agent appelle `create_deal` avec `dealname`, `dealstage` et `amount`, puis associe le contact.	L’affaire entre dans le pipeline dès la fin de l’appel, au bon stade.
Déclencher le support	L’agent appelle `create_ticket` avec `subject`, `hs_pipeline_stage` et une priorité.	Un incident est ouvert et suivi, au lieu de rester dans un compte rendu d’appel.

Comment ça marche

Bookivox crée une credential bearer_token contenant le jeton pat-…. Le backend l’envoie en en-tête Authorization: Bearer.
Toutes les requêtes partent vers l’URL de base fixe https://api.hubapi.com, avec les chemins de l’API CRM v3.
Un outil http_api par action est créé, avec config.provider = "hubspot", config.operation et un timeout de 10 000 ms.
Toutes les actions sont des POST, une par objet : create_call sur /crm/v3/objects/calls, create_contact sur /crm/v3/objects/contacts, search_contacts sur /crm/v3/objects/contacts/search, create_note sur /crm/v3/objects/notes, create_task sur /crm/v3/objects/tasks, create_deal sur /crm/v3/objects/deals et create_ticket sur /crm/v3/objects/tickets.
Les valeurs de properties sont transmises en chaînes. Chaque objet a ses champs obligatoires : hs_timestamp pour un appel, une note ou une tâche, dealname et dealstage pour une affaire, subject et hs_pipeline_stage pour un ticket.
Le rattachement à une fiche passe par associations, avec l’identifiant de la fiche cible et le type d’association défini par HubSpot.
Seuls les endpoints de collection sont exposés : l’URL de l’outil est envoyée telle quelle, donc les chemins avec identifiant (/crm/v3/objects/contacts/{id}) ne sont pas accessibles.

Rédiger la description de l’outil

La description de l’outil est ce qui décide quand l’agent appelle HubSpot. Rédigez-la comme une consigne :

Utiliser cet outil pour retrouver le contact de l'appelant avant de lui répondre,
puis pour journaliser l'appel et laisser une note ou une tâche de suivi à la fin
de la conversation.

Si vous exposez Créer un contact et Rechercher un contact au même agent, précisez dans le prompt de chercher d’abord et de ne créer qu’en l’absence de résultat. Sans cette consigne, l’agent risque de dupliquer des fiches. Indiquez aussi l’objet visé quand plusieurs écritures se ressemblent : « note » pour un compte rendu, « tâche » pour une action datée, « affaire » pour une vente à suivre, « ticket » pour un incident.

Sécurité

Risque	Ce que fait le preset
Jeton exposé	Il vit dans une credential chiffrée, jamais dans la définition de l’outil ni dans un prompt. Il n’est jamais réaffiché après l’enregistrement.
Écritures non voulues	Les écritures sont limitées aux actions cochées : un appel journalisé, un contact, une note, une tâche, une affaire ou un ticket créés. Aucune suppression, aucune modification d’une fiche existante.
Portée excessive	Les droits se limitent à ceux de l’application privée : ne cochez que les scopes des objets réellement utilisés (Appels, Contacts, Notes, Tâches, Affaires, Tickets).
Mauvais compte	L’URL de base est figée sur `https://api.hubapi.com` : l’outil ne peut pas viser un autre portail.
Doublons de contacts	Le preset n’impose pas de fusion : la description de l’outil et le prompt doivent imposer une recherche préalable.

Créez une application privée dédiée à Bookivox et révoquez son jeton en cas de doute. Un jeton partagé avec un autre usage ne peut pas être révoqué sans interrompre cet autre usage.

Ce qui est déconseillé

Usage	Pourquoi
Créer un contact sans recherche préalable	Vous générez des doublons difficiles à fusionner ensuite.
Appeler `create_call` sans `hs_timestamp`	Le champ est obligatoire : HubSpot refuse la requête (`422`).
Envoyer des nombres ou des dates libres dans `properties`	Les valeurs doivent être des chaînes ; une date doit être en epoch millisecondes ou ISO 8601 UTC.
Supprimer ou mettre à jour une fiche existante	Hors périmètre : aucune action de ce type n’est exposée.
Créer une affaire hors pipeline	`dealstage` doit appartenir à un pipeline existant, sinon HubSpot refuse la requête (`422`).
Ouvrir un ticket pour une demande commerciale	Un ticket alimente le support : pour une vente, utilisez une affaire, et pour un simple compte rendu, une note.
Attendre une relance automatique après `create_task`	La tâche est créée dans le CRM ; c’est le commercial qui l’exécute. Un outil d’agent s’exécute pendant l’appel, pas en tâche de fond.
Empiler les écritures dans un seul outil	Un outil par action permet de n’accorder que le strict nécessaire et de garder un journal lisible.

Limites et dépannage

Symptôme	Cause probable	Correction
Erreur `401`	Jeton erroné, révoqué, ou application privée supprimée.	Régénérer le jeton et recréer la connexion.
Erreur `403`	Droits CRM insuffisants sur l’objet visé (Appels, Contacts, Notes, Tâches, Affaires ou Tickets).	Élargir les droits de l’application privée, puis recréer la connexion.
Erreur `404`	Endpoint inconnu ou objet non disponible sur ce portail.	Vérifier les actions cochées et la version de l’API CRM.
Erreur `422`	Champ obligatoire absent (`hs_timestamp`, `dealname`, `dealstage`, `subject`, `hs_pipeline_stage`) ou valeur non conforme (`properties` attend des chaînes).	Reformuler la description : dates ISO 8601 UTC ou epoch en millisecondes, valeurs sous forme de chaînes, stade appartenant à un pipeline existant.
Erreur `429`	Limite de requêtes HubSpot atteinte.	Espacer les appels ; ne pas attacher plusieurs agents très actifs au même portail.
Erreur `5xx`	Incident côté HubSpot.	Réessayer plus tard ; contacter HubSpot si cela dure.
« Jeton invalide »	Le jeton ne commence pas par `pat-`, ou un espace a été collé.	Recopier la valeur brute, sans espace.
Un identifiant d’objet est demandé	Le preset ne gère que les collections, pas les chemins avec identifiant.	Utiliser Rechercher un contact pour retrouver la fiche, puis son identifiant dans `associations` ; les identifiants de pipeline et de stade se lisent dans HubSpot.
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.
« Créer » ne fait rien	L’action est déjà créée pour cette connexion.	Elle porte la mention Déjà créé ; rien à faire.

HubSpot n’est pas relié ici par un serveur MCP : chaque action est un outil HTTP distinct, ce qui permet à l’agent de choisir précisément une action plutôt que d’appeler un serveur générique.

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 : HubSpot

À quoi ça sert

Ce qu’il faut préparer

Connecter HubSpot

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 HubSpot

​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 HubSpot

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