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

# Nœud Déclencheur

> Le point d'entrée API : chemin personnalisé et corps de requête accepté pour déclencher un appel depuis un système externe.

Le nœud **Déclencheur** (`trigger`) est le point d'entrée d'un workflow
lorsqu'un appel est **déclenché par API** (votre CRM, un script, un autre
service) plutôt que par un appel entrant classique.

Un workflow contient **au plus un** déclencheur.

## Champs du nœud

| Champ | Type | Requis | Défaut | Description |
| - | - | - | - | - |
| **Nom** | texte | non | `API Trigger` | Libellé du nœud. **N'a aucun effet** sur l'appel. |
| **Activé** | interrupteur | non | activé | Si désactivé, l'URL n'est plus opérationnelle. |
| **Chemin du webhook** | texte | non | vide | Identifiant d'URL : 36 caractères max, lettres, chiffres, tirets et underscores. |

### Le chemin

Le **chemin** est la partie variable de l'URL de votre agent. Choisissez un
identifiant stable et explicite, par exemple `prise-rdv-acme` ou
`relance_panier`.

> [!NOTE]
>
> Si vous laissez le chemin vide, aucune URL n'est générée et le déclencheur
> n'est pas opérationnel. Renseignez un chemin pour l'activer.

## L'URL générée

À partir du chemin, Bookivox génère une **URL de webhook** dédiée à votre agent.
Vous la trouvez dans le panneau du nœud ainsi que dans
[Clés d'API](https://docs.bookivox.com/workspace/api-keys.md).

> [!NOTE]
>
> Utilisez la version de **test** de l'agent pour valider vos modifications avant
> publication, puis l'URL de **production** une fois l'agent publié. Voir
> [Versions](https://docs.bookivox.com/workflow/testing-and-versions.md).

## Corps de la requête

L'endpoint accepte un corps JSON.

| Champ | Type | Requis | Description |
| - | - | - | - |
| `phone_number` | chaîne | **oui** | Le numéro à appeler. |
| `initial_context` | objet | non | Données fusionnées dans le contexte initial du run. |
| `telephony_configuration_id` | chaîne | non | La configuration téléphonique à utiliser (identifiant public). |

> [!WARNING]
>
> * Vous devez fournir une **clé d'API** dans l'en-tête **`X-API-Key`**.
> * `telephony_configuration_id` doit appartenir à la **même organisation** que
>   le déclencheur. Sinon, la configuration téléphonique sortante **par défaut**
>   de l'organisation est utilisée.

### Exemple d'appel

```
curl -X POST "$BOOKIVOX_API_URL/api/v1/api/trigger/<chemin>" \
  -H "X-API-Key: VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+33XXXXXX",
    "initial_context": {
      "first_name": "Marie",
      "order_ref": "CMD-10234"
    }
  }'
```

Les clés de `initial_context` deviennent des variables accessibles dans vos
prompts : `{{initial_context.first_name}}`, `{{initial_context.order_ref}}`.

## Quand l'utiliser

> **Appels sortants pilotés par un système**
>
> Votre CRM déclenche un appel et transmet le nom du client, la commande, etc.

> **Relances automatisées**
>
> Un service planifie des relances et appelle via l'API à heure fixe.

> **Personnalisation**
>
> L'agent démarre avec du contexte déjà connu, sans avoir à le demander au
> client.

> **Intégration à votre back-office**
>
> Un événement métier déclenche un appel immédiat (livraison, incident,
> rendez-vous manqué).

## Contraintes

* Un workflow contient **au plus un** déclencheur.
* Le nœud est **isolé** : il n'a **ni entrée, ni sortie**. C'est une porte
  d'entrée, pas une étape du chemin.
* Le chemin est **unique** dans votre organisation.
* Le déclencheur n'apparaît que si vous concevez l'agent pour être appelé par
  API.

## Sécurité

> [!WARNING]
>
> * Ne **partagez jamais** votre clé d'API et ne la placez pas dans du code
>   client (navigateur, application mobile).
> * Traitez `initial_context` comme une **entrée non fiable** : validez-la côté
>   serveur avant de la transmettre.
> * **Désactivez** le déclencheur si vous ne l'utilisez pas : l'URL renverra
>   `404`.
> * Surveillez l'usage : un endpoint public peut être la cible d'abus. Voir
>   [Clés d'API](https://docs.bookivox.com/workspace/api-keys.md).

> **[Clés d'API](https://docs.bookivox.com/workspace/api-keys.md)**
>
> Créer et gérer les clés.

> **[Endpoints](https://docs.bookivox.com/api-reference/endpoints)**
>
> La référence des endpoints.

> **[Réglages de l'agent](https://docs.bookivox.com/workflow/agent-settings.md)**
>
> Variables et contexte.

> **[Le canevas du builder](https://docs.bookivox.com/workflow/builder-canvas.md)**
>
> Revenir à l'éditeur.


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