Bookivox Documentation

À quoi ça sert

L’intégration Notion relie votre espace de travail à vos agents vocaux. Pendant l’appel, l’agent peut créer une page ou une ligne de base de données, chercher un contenu, lister les membres visibles par l’intégration, commenter une page ou lire les commentaires d’une page ou d’un bloc. Comme pour les autres intégrations, vous branchez votre propre espace : Bookivox ne fournit aucun identifiant. Vous créez une intégration interne dans Notion, copiez son jeton, puis cochez les actions à exposer.

Cette intégration écrit réellement dans Notion : une page créée et un commentaire ajouté apparaissent dans votre espace. Elle ne voit que les pages partagées explicitement avec l’intégration. 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’intégration	Notion : Paramètres → Connexions → Développer ou gérer les intégrations, puis création d’une intégration interne	Chaîne commençant par `secret_` ou `ntn_`, affichée une seule fois
Partage des pages	Action dans Notion, sur chaque page ou base concernée	L’intégration doit être invitée sur la page ou la base, sinon l’API renvoie un résultat vide ou `404`
Capacités de commentaire	Notion : onglet Capabilities de l’intégration	Read comments et Insert comments sont désactivées par défaut : sans elles, les actions de commentaire répondent `403`

Le jeton ne suffit pas : une intégration Notion ne voit que ce qu’on lui partage. Pensez à partager la base ou la page cible avec l’intégration, sinon create_page échoue et search reste vide. Les commentaires demandent deux autorisations distinctes en plus du partage : « Read comments » pour les lire, « Insert comments » pour en ajouter.

Connecter Notion

Créer l'intégration interne

Dans Notion, ouvrez Paramètres → Connexions → Développer ou gérer les intégrations et créez une intégration interne dédiée à Bookivox.

Copier le jeton

Copiez le jeton d’intégration : il commence par secret_ ou ntn_ et n’est affiché qu’une fois.

Activer les capacités utiles

Dans l’onglet Capabilities de l’intégration, cochez Read comments et Insert comments si vous voulez exposer les actions de commentaire.

Partager les pages et bases

Dans Notion, ouvrez chaque page ou base à rendre accessible et invitez l’intégration via le menu de partage.

Saisir la clé

Dans Intégrations → Notion, collez le jeton. Le formulaire vérifie le préfixe 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 Notion liste les espaces 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
Créer une page (`create_page`)	Crée une page ou une ligne de base de données avec ses propriétés	« Notez ma demande dans votre base. »
Rechercher (`search`)	Cherche une page ou une base par mots-clés	« Qu’est-ce que vous avez sur la garantie ? »
Lister les membres (`list_users`)	Liste les membres visibles par l’intégration	« Qui suit mon dossier ? »
Commenter une page (`create_comment`)	Ajoute un commentaire sur une page ou un bloc partagé	« Laissez un mot sur la page de suivi. »
Lire les commentaires (`list_comments`)	Liste les commentaires d’une page ou d’un bloc, avec leur auteur	« Qu’est-ce qui a été dit sur ce dossier ? »

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.

Pour créer une page, parent désigne soit une ligne de base de données (data_source_id), soit une sous-page (page_id). La clé de properties doit correspondre exactement au nom de la propriété du parent.Pour commenter, parent accepte page_id ou block_id, et le contenu passe soit par rich_text, soit par markdown, jamais les deux. Pour lire les commentaires, block_id est obligatoire et voyage en paramètre de requête.

Travailler avec une base de données. Une base se travaille aujourd’hui en deux gestes : ajouter une ligne (create_page avec parent.data_source_id) et retrouver une ligne (search renvoie les pages — lignes comprises — dont le titre correspond, avec leurs propriétés). En revanche, interroger une base (filtrer sur une propriété, trier, lire toutes les lignes) et modifier une ligne existante ne sont pas exposés : ces routes portent l’identifiant de la base ou de la ligne dans le chemin de l’URL, et l’outil HTTP envoie l’URL telle quelle. Pour un besoin de lecture, comptez sur la recherche par mot-clé et sur les propriétés qu’elle renvoie.

Cas d’usage

Cas d’usage	Ce que fait l’agent	Résultat pour le client
Consigner une demande dans une base	L’agent appelle `create_page` avec `data_source_id` et les `properties` attendues par la base.	La demande est structurée dès la prise d’appel, prête à être traitée.
Retrouver une réponse interne	L’agent appelle `search` avec les mots-clés du client : garantie, procédure, tarif.	L’agent répond à partir de la documentation interne, pas de mémoire.
Créer un dossier dans une sous-page	L’agent appelle `create_page` avec `page_id` comme parent.	Le suivi s’ajoute au dossier existant, sans arborescence parallèle.
Identifier l’interlocuteur	L’agent appelle `list_users` pour savoir qui suit le dossier.	Le client obtient un nom de contact interne fiable.
Laisser une consigne dans le dossier	L’agent appelle `create_comment` avec `parent.page_id` et un texte `markdown` court.	Le suivi apparaît sur la page, au même endroit que le reste du dossier.
Relire les échanges d’un dossier	L’agent appelle `list_comments` avec le `block_id` de la page de suivi.	L’agent reprend le contexte écrit par l’équipe, sans le reformuler de mémoire.
Tracer une décision sur un point précis	L’agent appelle `create_comment` avec `parent.block_id` pour viser un bloc plutôt que la page entière.	La décision reste rattachée au passage concerné, pas noyée en bas de page.
Éviter un doublon dans une base	L’agent appelle `search` avec le nom du client avant de créer la ligne.	Si la ligne existe, il la retrouve et ses propriétés ; sinon il appelle `create_page`.

Comment ça marche

Bookivox crée une credential bearer_token contenant le jeton secret_… ou ntn_…. Le backend l’envoie en en-tête Authorization: Bearer.
Chaque requête porte l’en-tête Notion-Version: 2026-03-11, obligatoire : sans lui, Notion répond 400. Cette valeur est un en-tête fixe, jamais un secret.
Toutes les requêtes partent vers l’URL de base https://api.notion.com/v1 : /pages en POST, /search en POST, /users en GET, et /comments en POST pour commenter comme en GET pour lire.
Un outil http_api par action est créé, avec config.provider = "notion", config.operation et un timeout de 10 000 ms.
Les résultats sont bornés à 100 éléments par appel (page_size), avec un curseur (start_cursor) pour la page suivante.
Pour un commentaire, la cible et le texte voyagent dans le corps JSON : parent avec un seul identifiant, puis rich_text ou markdown. En lecture, block_id passe en paramètre de requête et reste obligatoire.
Notion limite le débit à environ 3 requêtes par seconde par intégration et plafonne chaque bloc de texte enrichi à 2 000 caractères. Notion refuse aussi children lorsqu’un modèle (template) est utilisé.
Seuls les endpoints de collection sont exposés : l’URL de l’outil est envoyée telle quelle, donc les chemins avec identifiant (/v1/pages/{id} et /v1/data_sources/{id}/query) ne sont pas accessibles. Conséquence sur les bases : créer une ligne et la retrouver par mot-clé sont possibles ; interroger la base par propriété et modifier une ligne existante ne le sont pas.

Rédiger la description de l’outil

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

Utiliser cet outil quand le client demande une information déjà documentée,
pour consigner sa demande dans la base de suivi, ou pour laisser une consigne
sur la page du dossier.

Si vous exposez Créer une page et Rechercher au même agent, précisez dans le prompt de chercher d’abord avant de créer, et surtout indiquez la base ou la page cible attendue : sans cette précision, l’agent peut créer une page au mauvais endroit.Si vous exposez aussi les commentaires, distinguez-les explicitement de la création : une page crée une entrée, un commentaire s’ajoute à une page existante. Sans cette consigne, l’agent peut ouvrir une page pour y laisser un simple mot.

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	Deux actions écrivent : `create_page` et `create_comment`, et uniquement dans les pages ou blocs partagés avec l’intégration.
Commentaires non autorisés	Les capacités « Read comments » et « Insert comments » sont distinctes et désactivées par défaut : hors périmètre, la requête répond `403` sans rien écrire.
Périmètre trop large	L’intégration ne voit que les pages explicitement partagées : ne partagez que le strict nécessaire.
Mauvais espace	L’URL est figée sur `https://api.notion.com/v1` : l’outil ne peut pas viser un autre espace.
Réponses trop longues	Les listes sont bornées à 100 éléments et chaque bloc à 2 000 caractères.
Version d’API	`Notion-Version` est fixée par le preset (`2026-03-11`) : l’agent ne peut pas la changer.

Créez une intégration interne dédiée à Bookivox et révoquez son jeton en cas de doute depuis Notion. 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
Partager tout l’espace de travail	L’intégration verrait des pages hors périmètre ; partagez uniquement les bases utiles.
Créer une page sans vérifier le parent	Les clés de `properties` doivent correspondre au schéma du parent, sinon Notion refuse (`400`).
Promettre une lecture complète d’une base	L’intégration n’interroge pas une base : `search` ne cherche que dans les titres et ne filtre pas sur les valeurs de propriétés.
Promettre la modification d’une ligne	Une ligne existante ne peut pas être mise à jour, seulement créée ou retrouvée.
Textes très longs dans un bloc	Un bloc de texte enrichi est plafonné à 2 000 caractères.
Utiliser `children` avec un modèle	Notion refuse cette combinaison.
Envoyer `rich_text` et `markdown` ensemble	Un commentaire accepte l’un ou l’autre : les deux provoquent `400`. `markdown_version` ne s’envoie qu’avec `markdown`.
Lire les commentaires sans `block_id`	Le paramètre est obligatoire en lecture : sans lui, Notion refuse la requête.
Commenter une page non partagée	L’intégration ne peut commenter que ce qu’on lui a partagé, et seulement si « Insert comments » est activée.
Vagues d’appels rapprochés	Environ 3 requêtes par seconde seulement : au-delà, Notion renvoie `429`.
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`	Jeton erroné, révoqué ou intégration supprimée.	Recréer l’intégration ou régénérer le jeton, puis recréer la connexion.
Erreur `403`	L’intégration n’a pas accès à la page ou à la base visée, ou la capacité de commentaire demandée est désactivée.	Partager la page ou la base avec l’intégration, puis cocher Read comments ou Insert comments dans les capacités.
Erreur `403 restricted_resource` sur un commentaire	Les capacités de commentaire sont désactivées par défaut sur une intégration interne.	Activer la capacité correspondante dans Notion, puis recréer la connexion.
Erreur `404`	Page introuvable ou non partagée.	Vérifier le partage et l’identifiant du parent.
Erreur `400` « Notion-Version »	L’en-tête de version manque.	Il est fourni par le preset : recréer l’outil si le problème persiste.
Erreur `400` sur `properties`	Schéma du parent non respecté, ou clé de propriété inconnue.	Vérifier les noms et types de propriétés dans la base cible.
Erreur `400` sur un commentaire	`rich_text` et `markdown` envoyés ensemble, `markdown_version` sans `markdown`, ou deux identifiants dans `parent`.	N’envoyer qu’un seul mode de contenu et un seul identifiant de cible.
Erreur `400` sur `list_comments`	`block_id` absent de la requête.	Fournir le `block_id` de la page ou du bloc à lire.
Erreur `429`	Trop de requêtes (environ 3 par seconde).	Espacer les appels ; ne pas attacher plusieurs agents très actifs à la même intégration.
Erreur `5xx`	Incident côté Notion.	Réessayer plus tard ; contacter Notion si cela dure.
La recherche ne renvoie rien	Aucune page n’est partagée avec l’intégration.	Partager les pages concernées dans Notion.
« L’agent ne trouve pas une ligne de la base »	`search` cherche dans les titres : une valeur de propriété (statut, date, montant) n’est pas un critère de recherche.	Faire citer un mot du titre ; pour un filtre par propriété, passer par un autre canal ou par la vue Notion.
Impossible de modifier une ligne	La route de mise à jour porte l’identifiant de la page dans le chemin, que le preset n’expose pas.	Créer une ligne à jour, ou faire la modification directement dans Notion.
« Jeton invalide »	Le jeton ne commence pas par `secret_` ou `ntn_`, ou un espace a été collé.	Recopier la valeur brute, sans espace.
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.

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

À quoi ça sert

Ce qu’il faut préparer

Connecter Notion

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 Notion

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

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