> ## 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 : HubSpot > Connectez HubSpot à Bookivox pour que vos agents retrouvent un contact, journalisent l'appel et créent notes, tâches, affaires ou tickets dans votre CRM pendant la conversation. ## À 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. > [!NOTE] > > 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 | > [!NOTE] > > 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 **1. 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. **2. 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. **3. 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. **4. Saisir la clé** Dans **Intégrations → HubSpot**, collez le jeton. Le formulaire vérifie qu'il commence par `pat-` avant l'enregistrement. **5. Cocher les actions** Sélectionnez les actions à exposer. Chacune devient un **outil indépendant**. **6. 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é. **7. 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. > [!NOTE] > > 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 1. Bookivox crée une **credential** `bearer_token` contenant le jeton `pat-…`. Le backend l'envoie en en-tête `Authorization: Bearer`. 2. Toutes les requêtes partent vers l'URL de base fixe `https://api.hubapi.com`, avec les chemins de l'**API CRM v3**. 3. Un **outil `http_api` par action** est créé, avec `config.provider = "hubspot"`, `config.operation` et un **timeout de 10 000 ms**. 4. 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`. 5. 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. 6. Le rattachement à une fiche passe par `associations`, avec l'identifiant de la fiche cible et le type d'association défini par HubSpot. 7. 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. ``` > [!WARNING] > > 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. | > [!WARNING] > > **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. | > [!NOTE] > > 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. > [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.