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

# Flows (recettes)

> Recettes de bout en bout : créer et tester un agent, uploader une base de connaissance, créer une campagne, lire crédits et usage, téléphonie.

Ces recettes utilisent le wrapper `bookivoxFetch` du
[Démarrage rapide](https://docs.bookivox.com/api-reference/quickstart). 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` :

1. Lister les templates : `GET /workflow/templates`
2. Dupliquer un template : `POST /workflow/templates/duplicate`

```json theme={null}
{ "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éé. |

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

```json theme={null}
{ "name": "Agent demo", "workflow_definition": { "nodes": [], "edges": [] } }
```

> [!WARNING]
>
> Ne construisez le graphe manuellement **que si vous savez ce que vous faites**.
> Sinon, utilisez la duplication de template. Voir
> [Nœuds (graphe)](https://docs.bookivox.com/api-reference/nodes) 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. |

```ts theme={null}
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). |

```ts theme={null}
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 }),
  }
)
```

> [!NOTE]
>
> 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)

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

Détails et paramètres : [Knowledge base](https://docs.bookivox.com/api-reference/knowledge-base).

## 4. Campagnes

### Uploader une source CSV (pour obtenir `source_id`)

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

```json theme={null}
{ "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 :

```json theme={null}
{ "upload_url": "https://...", "file_key": "opaque-reference", "expires_in": 900 }
```

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

### Créer et démarrer

`POST /campaign/create`

```json theme={null}
{
  "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](https://docs.bookivox.com/api-reference/campaigns).

## 5. Crédits & usage

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

> [!WARNING]
>
> 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](https://docs.bookivox.com/api-reference/nodes)**
>
> Construire le graphe.

> **[Endpoints](https://docs.bookivox.com/api-reference/endpoints)**
>
> Le cheatsheet complet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.