Bookivox Documentation

Ces recettes utilisent le wrapper bookivoxFetch du Démarrage rapide. Les chemins donnés ici sont relatifs : le wrapper ajoute automatiquement le préfixe /api/v1/api.

1. Gérer un agent (workflow)

Option recommandée : créer via template

Vous n’avez pas besoin de comprendre workflow_definition :

Lister les templates : GET /workflow/templates
Dupliquer un template : POST /workflow/templates/duplicate

{ "template_id": 1, "workflow_name": "Mon agent" }

Champ	Type	Requis	Description
`template_id`	integer	oui	Identifiant du template à dupliquer.
`workflow_name`	string	oui	Nom du nouvel agent créé.

Récupérer l’agent créé : GET /workflow/fetch/{workflow_id}

Modifier un agent

PUT /workflow/{workflow_id} (le chemin /workflow/update/{id} parfois mentionné ailleurs n’existe pas).

Champ	Type	Requis	Description
`name`	string	non	Nouveau nom de l’agent.
`workflow_definition`	object	non	Graphe complet `{ nodes, edges }` à remplacer.
`template_context_variables`	object	non	Variables de contexte du template.
`workflow_configurations`	object	non	Réglages globaux de l’agent.

Opérations de base

Action	Endpoint
Lister les agents	`GET /workflow/fetch`
Lire un agent	`GET /workflow/fetch/{workflow_id}`
Créer (avancé)	`POST /workflow/create/definition`
Modifier	`PUT /workflow/{workflow_id}`
Valider	`POST /workflow/{workflow_id}/validate`

Corps pour une création manuelle :

{ "name": "Agent demo", "workflow_definition": { "nodes": [], "edges": [] } }

Ne construisez le graphe manuellement que si vous savez ce que vous faites. Sinon, utilisez la duplication de template. Voir Nœuds (graphe) pour le schéma de workflow_definition.

2. Tester un agent (text chat)

Créer une session

POST /workflow/{workflow_id}/text-chat/sessions

Champ	Type	Requis	Description
`name`	string	non	Libellé de la session de test.
`initial_context`	object	non	Variables injectées au démarrage du run.

const session = await bookivoxFetch<any>(
  `/workflow/${workflowId}/text-chat/sessions`,
  {
    method: "POST",
    apiKey,
    body: JSON.stringify({ name: "Test", initial_context: { customer_name: "Alice" } }),
  }
)

Envoyer un message

POST /workflow/{workflow_id}/text-chat/sessions/{run_id}/messages

Champ	Type	Requis	Description
`text`	string	oui	Message envoyé à l’agent.
`expected_revision`	integer	oui	Révision attendue de la session (contrôle de concurrence).

const updated = await bookivoxFetch<any>(
  `/workflow/${workflowId}/text-chat/sessions/${session.workflow_run_id}/messages`,
  {
    method: "POST",
    apiKey,
    body: JSON.stringify({ text: "Bonjour", expected_revision: session.revision }),
  }
)

Le run_id de la session est un entier (workflow_run_id).

Gestion du 409 : la session a changé entre-temps. Relisez-la (GET /workflow/{id}/text-chat/sessions/{run_id}), puis renvoyez le message avec un expected_revision à jour.

3. Base de connaissance (documents)

Demander une URL d’upload : POST /knowledge-base/upload-url
Uploader le fichier via PUT sur upload_url.
Lancer le processing : POST /knowledge-base/process-document

Détails et paramètres : Knowledge base.

4. Campagnes

Uploader une source CSV (pour obtenir `source_id`)

Demander une URL : POST /campaign/sources/presigned-upload-url

{ "file_name": "contacts.csv", "file_size": 12345, "content_type": "text/csv" }

Champ	Type	Requis	Description
`file_name`	string	oui	Nom du fichier.
`file_size`	integer	oui	Taille en octets (validée côté serveur).
`content_type`	string	oui	Type MIME (ex. `text/csv`).

Réponse :

{ "upload_url": "https://...", "file_key": "opaque-reference", "expires_in": 900 }

Uploader en PUT sur upload_url (Content-Type: text/csv).
Utiliser file_key comme source_id.

Créer et démarrer

POST /campaign/create

{
  "name": "Campagne demo",
  "workflow_id": "c1f0a2e4-...-9b7",
  "source_type": "csv",
  "source_id": "opaque-reference"
}

Champ	Type	Requis	Description
`name`	string	oui	Nom de la campagne.
`workflow_id`	string	oui	UUID public de l’agent à exécuter.
`source_type`	string	oui	Type de source (ex. `csv`).
`source_id`	string	oui	`file_key` renvoyé par l’upload.

Puis POST /campaign/{campaign_id}/start. Si la réponse est 402, il n’y a plus de crédits : créditez d’abord. Détails des options (retry, planning, disjoncteur) : Campagnes.

5. Crédits & usage

Solde + ledger : GET /organizations/billing/credits
Usage : GET /organizations/usage/current-period

La recharge de crédits se fait uniquement dans le dashboard, pas via clé API. Un appel de recharge via clé API est refusé (403).

6. Numéros (téléphonie)

La gestion de la téléphonie est dashboard only. Via clé API (lecture) :

GET /organizations/telephony-configs
GET /organizations/telephony-configs/{config_id}/phone-numbers

Nœuds

Construire le graphe.

Endpoints

Le cheatsheet complet.

Agents

Base de connaissance

Campagnes

Chat texte

Clés API

Crédits et usage

Node-types

Outils

Téléphonie

Templates

Flows (recettes)

1. Gérer un agent (workflow)

Option recommandée : créer via template

Modifier un agent

Opérations de base

2. Tester un agent (text chat)

Créer une session

Envoyer un message

3. Base de connaissance (documents)

4. Campagnes

Uploader une source CSV (pour obtenir `source_id`)

Créer et démarrer

5. Crédits & usage

6. Numéros (téléphonie)

Nœuds

Endpoints

​1. Gérer un agent (workflow)

​Option recommandée : créer via template

​Modifier un agent

​Opérations de base

​2. Tester un agent (text chat)

​Créer une session

​Envoyer un message

​3. Base de connaissance (documents)

​4. Campagnes

​Uploader une source CSV (pour obtenir source_id)

​Créer et démarrer

​5. Crédits & usage

​6. Numéros (téléphonie)

Nœuds

Endpoints

1. Gérer un agent (workflow)

Option recommandée : créer via template

Modifier un agent

Opérations de base

2. Tester un agent (text chat)

Créer une session

Envoyer un message

3. Base de connaissance (documents)

4. Campagnes

Uploader une source CSV (pour obtenir `source_id`)

Créer et démarrer

5. Crédits & usage

6. Numéros (téléphonie)