--- title: "Référence des nœuds de séquence vocale" description: "Consultez les étapes disponibles pour une définition de séquence vocale en ligne, avec chaque type, ses champs, ses valeurs autorisées et ses résultats." --- # Référence des nœuds de séquence vocale > **Warning:** Voice sequences are in preview. Steps, entry data, and the sequence definition format can change in ways that break existing sequences and API requests. Utilisez cette référence pour écrire le `sequence.definition` que vous envoyez avec [Créer un appel](/docs/guides/voice/create-calls#run-an-inline-sequence). Bird exécute une définition en ligne une seule fois sans la sauvegarder. Pour conserver une séquence, construisez-la dans l'[éditeur du tableau de bord](/docs/guides/voice/sequences/editor). ## Définition | Champ | Valeur | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Tableau d'objets de nœud. L'ordre du tableau n'a aucun effet sur l'exécution. | | `settings` | Omettez-le ou envoyez `{}`. Un objet non vide échoue avec `unsupported_contract` ; une valeur qui n’est pas un objet échoue avec `invalid_envelope`. | | `presentation` | Disposition et libellés facultatifs de l'éditeur. N'affecte pas l'exécution, mais compte dans les limites de taille. | Chaque nœud possède ces champs : | Champ | Valeur | | -------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `id` | Unique dans la définition. Commence par une lettre minuscule, puis lettres minuscules, chiffres ou `_`, jusqu'à 64 caractères. | | `type` | Un type de nœud de cette page, par exemple `voice.say`. | | `type_version` | `1` pour chaque type de nœud sur cette page. | | `config` | Configuration qui fixe la forme du nœud, comme les résultats déclarés. Utilisez `{}` quand le nœud n'en a pas. | | `input` | Valeurs que le nœud utilise lors de son exécution. Utilisez `{}` quand le nœud n'en a pas. | | `connections` | Correspondance entre un nom de résultat et `{ "node_id": "", "port": "input" }`. | Les connexions ne doivent pas former de boucle, et chaque nœud doit être accessible depuis une entrée. Un résultat absent de `connections` est non connecté. Les résultats non connectés terminent l'exécution normalement, sauf indication contraire du nœud. ## Valeurs et expressions La plupart des champs acceptent des JSON littéraux. Les champs marqués **binds** acceptent aussi `$expr` ou `$template` ; les champs marqués **expr** acceptent aussi `$expr` uniquement : - `{"$expr": "trigger.data.customer_name"}` renvoie une valeur typée. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` renvoie du texte. Les templates sont des tableaux ; `{{name}}` reste du texte littéral. Les expressions utilisent CEL et peuvent lire ces valeurs : | Valeur | Contenu | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `trigger.data` | Les données d'entrée, correspondant au `data_schema` de l'entrée. | | `trigger.node_id` | L'identifiant de l'entrée qui a démarré cette visite. | | `trigger.type` | Le type de l’entrée qui a démarré cette visite, par exemple `trigger.start_call`. | | `steps..output` | Sortie d'un nœud précédent terminé dans cette visite. | | `variables.` | Valeurs enregistrées par un nœud `data.set` dans cette visite. | | `execution.id`, `execution.started_at` | L'identifiant de l'exécution et son heure de début. Utilisez `string(execution.started_at)` dans la synthèse vocale. | | `execution.call` | Le `id` de l'appel, `session_id`, et les parties d'origine `orig` et `dest`, chacune pouvant être `null`. | Vérifiez les valeurs optionnelles avant de les lire, par exemple `has(trigger.data.name) ? trigger.data.name : 'caller'`. La macro `has` est disponible ; `map`, `filter`, `all`, `exists` et `exists_one` ne le sont pas. ## Entrée ### `trigger.start_call` Point de départ d'un appel. `entry_node_id` dans la requête Create Call désigne ce nœud. | Champ | Valeur | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `config.data_schema` | Schéma d'objet JSON Schema (draft 2020-12) optionnel pour `trigger_data`. Seul `$ref` local est pris en charge. Sans ce schéma, l'entrée n'accepte que `{}`. | | Résultat | `event`. | Les données d'entrée sont limitées à 16 Kio. ## Parole et audio ### `voice.say` | Champ | Valeur | | ---------------- | --------------------------------------------------------- | | `input.text` | Requis, **binds**. Texte à prononcer, 160 octets maximum. | | `input.language` | Requis. Code de langue vocale, par exemple `en`. | | Résultat | `next`. | ### `voice.play` | Champ | Valeur | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.asset_id` | Obligatoire. ID d'un asset audio disponible dans cet espace de travail. Un asset indisponible peut faire échouer l'appel lors de l'exécution de l'étape. | | Issue | `next`. | ### `voice.tone` | Champ | Valeur | | -------------------- | ----------------------- | | `input.frequency_hz` | Requis. `100` à `3000`. | | `input.duration_ms` | Requis. `1` à `10000`. | | Résultat | `next`. | ### `logic.pause` Attend avec l'appel connecté. | Champ | Valeur | | ------------------- | ---------------------- | | `input.duration_ms` | Requis. `1` à `60000`. | | Résultat | `next`. | ## Saisie au clavier ### `voice.gather` Joue des invites, qu'une pression de touche interrompt, et collecte les chiffres saisis au clavier. | Champ | Valeur | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Obligatoire. Jusqu'à 4 invites. Chacune est `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` ou `{"type": "pause", "duration_ms"}`, avec les mêmes limites que le nœud correspondant. Les durées de tonalité et de pause combinées ne dépassent pas 60 000 ms. `text` d'invite accepte les **binds**. | | `input.max_digits` | Obligatoire. `1` à `32`. | | `input.timeout_seconds` | Obligatoire. Secondes d'attente avant la première touche, `1` à `10`. | | `input.inter_digit_timeout_seconds` | Obligatoire. Secondes d'attente entre les touches, `1` à `5`. | | `input.finish_on_key` | Requis. Un parmi `0`–`9`, `*`, `#`, `A`–`D` qui met fin à la saisie, ou `null`. | | `input.matches` | Requis. Correspondance entre un nom d'issue et les chiffres exacts qui la sélectionnent, par exemple `{"hours": "1"}`. Les noms et les chiffres doivent être uniques. Un nom ne peut pas être `input`, `timeout` ou `fallback`. Les chiffres font au plus `max_digits` de long et ne peuvent pas contenir `finish_on_key`. | | `input.private` | Optionnel, par défaut `false`. Quand `true`, les étapes suivantes ne peuvent pas lire les chiffres, et ceux-ci sont exclus de la trace. | | Issues | Chaque nom dans `matches`, `timeout` quand aucune touche n'est pressée, et `fallback` pour toute autre saisie. | | Sortie | `digits` et `reason` : `initial_timeout`, `max_digits`, `finish_key` ou `inter_digit_timeout`. | ## Logique et données ### `logic.branch` Vérifie les conditions dans l'ordre et suit la première qui est vraie. | Champ | Valeur | | --------------------- | ------------------------------------------------------------------------------ | | `config.cases` | Obligatoire. Au moins un `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Obligatoire. Nom de l'issue quand aucun cas n'est vrai. | | Issues | Chaque `port` dans `cases`, et `default_port`. | | Sortie | `branch` : le nom de l'issue sélectionnée. | ### `data.set` Enregistre des valeurs pour les étapes suivantes de la même visite. | Champ | Valeur | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input` | Objet de valeurs, dont chacune accepte un **bind**. Chaque clé devient `variables.`. Chaque valeur est calculée à partir des variables telles qu'elles étaient avant ce nœud. | | Issue | `next`. | | Sortie | L'objet enregistré. | ## Appels et transferts ### `voice.dial` Appelle un autre numéro et le connecte à l'appel en cours. | Champ | Valeur | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.to` | Obligatoire, **binds**. Numéro E.164, par exemple `+12025550123`. | | `input.timeout_seconds` | Obligatoire, **expr**. Secondes de sonnerie, de `1` à `120`. | | Issues | `success`, `busy`, `no_answer` et `failure`. `success` suit après la fin de l'appel connecté et la restauration de l'audio de l'appel initial, pas au moment où le destinataire répond. Une issue `failure` non connectée fait échouer l'exécution. | ### `logic.voice_goto` Démarre une autre entrée dans la même définition. La nouvelle visite reçoit des `trigger.data` nouvelles et efface les sorties et variables des étapes précédentes ; l'appel continue. | Champ | Valeur | | --------------------- | ---------------------------------------------------------------------------------- | | `input.entry_node_id` | Obligatoire. ID d'un nœud `trigger.start_call` dans cette définition. | | `input.data` | Facultatif, **expr**, par défaut `{}`. Données d'entrée pour le schéma de ce nœud. | | Issues | Aucun. | ## Fin de l'appel ### `logic.exit` Met fin à l'appel avec un résultat. | Champ | Valeur | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.status` | Requis. `succeeded` ou `failed`. | | `config.reason` | Optionnel, **expr**. Code stable composé de lettres minuscules, de chiffres et de `_`, commençant par une lettre ou un chiffre, jusqu'à 64 caractères. Omettez-le plutôt que d'envoyer `null`. | | `input.output` | Objet requis, qui peut être `{}`. Ses valeurs de premier niveau acceptent **binds**. | | Résultats | Aucun. | ### `voice.hangup` Met fin à l'appel sans résultat défini. Ce nœud n'a ni champs ni résultats. ## Étapes en accès anticipé `voice.webhook`, `voice.record_start`, `voice.record_stop` et `logic.voice_goto` avec `dependency_id` pour la messagerie vocale gérée ou l'enregistrement d'appels sont en accès anticipé et ne sont pas documentés ici. Leur utilisation nécessite un accès pour votre espace de travail. ## Exemple : transfert vers une personne Cette définition salue le destinataire, compose un numéro de support et enregistre si le transfert a abouti : ```json { "schema_version": 1, "expression_environment": "bird.cel.v1", "nodes": [ { "id": "start", "type": "trigger.start_call", "type_version": 1, "config": {}, "input": {}, "connections": { "event": { "node_id": "greeting", "port": "input" } } }, { "id": "greeting", "type": "voice.say", "type_version": 1, "config": {}, "input": { "text": "Connecting you to our support team.", "language": "en" }, "connections": { "next": { "node_id": "support", "port": "input" } } }, { "id": "support", "type": "voice.dial", "type_version": 1, "config": {}, "input": { "to": "+12025550123", "timeout_seconds": 30 }, "connections": { "success": { "node_id": "connected", "port": "input" }, "busy": { "node_id": "unavailable", "port": "input" }, "no_answer": { "node_id": "unavailable", "port": "input" }, "failure": { "node_id": "unavailable", "port": "input" } } }, { "id": "connected", "type": "logic.exit", "type_version": 1, "config": { "status": "succeeded", "reason": "transferred" }, "input": { "output": {} } }, { "id": "unavailable", "type": "logic.exit", "type_version": 1, "config": { "status": "failed", "reason": "support_unavailable" }, "input": { "output": {} } } ] } ``` Envoyez-la en tant que `sequence.definition` avec `"entry_node_id": "start"` et `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)