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

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": "<target>", "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.<id>.output`	Sortie d'un nœud précédent terminé dans cette visite.
`variables.<key>`	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": "<name>", "when": {"$expr": "<boolean>"}}`.
`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.<key>`. 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 :

Exemple de code

{
  "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": {}.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Voice sequences

Ressources associées