--- title: "Riferimento ai nodi delle sequenze vocali" description: "Consulta i passaggi generalmente disponibili per una definizione inline di sequenza vocale, con ogni tipo, i suoi campi, i valori consentiti e gli esiti." --- # Riferimento ai nodi delle sequenze vocali > **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. Usa questo riferimento per scrivere il `sequence.definition` da inviare con [Crea chiamata](/docs/guides/voice/create-calls#run-an-inline-sequence). Bird esegue una definizione inline una sola volta e non la salva. Per conservare una sequenza, creala nell'[editor della dashboard](/docs/guides/voice/sequences/editor). ## Definizione | Campo | Valore | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Array di oggetti nodo. L'ordine dell'array non influisce sull'esecuzione. | | `settings` | Omettilo o invia `{}`. Un oggetto non vuoto fallisce con `unsupported_contract`; un valore che non è un oggetto fallisce con `invalid_envelope`. | | `presentation` | Layout ed etichette dell'editor, opzionali. Non influiscono sull'esecuzione ma contano ai fini dei limiti di dimensione. | Ogni nodo ha questi campi: | Campo | Valore | | -------------- | --------------------------------------------------------------------------------------------------------------------- | | `id` | Univoco nella definizione. Inizia con una lettera minuscola, poi lettere minuscole, cifre o `_`, fino a 64 caratteri. | | `type` | Un tipo di nodo tra quelli in questa pagina, ad esempio `voice.say`. | | `type_version` | `1` per ogni tipo di nodo in questa pagina. | | `config` | Configurazione che fissa la forma del nodo, come gli outcome dichiarati. Usa `{}` quando il nodo non ne ha. | | `input` | Valori che il nodo utilizza durante l'esecuzione. Usa `{}` quando il nodo non ne ha. | | `connections` | Mappa da un nome di outcome a `{ "node_id": "", "port": "input" }`. | Le connessioni non devono formare un ciclo e ogni nodo deve essere raggiungibile da un entry. Un outcome escluso da `connections` è non connesso. Gli outcome non connessi terminano normalmente l'esecuzione, salvo dove un nodo indica diversamente. ## Valori ed espressioni La maggior parte dei campi accetta valori letterali JSON. I campi contrassegnati con **binds** accettano anche `$expr` o `$template`; i campi contrassegnati con **expr** accettano solo `$expr`: - `{"$expr": "trigger.data.customer_name"}` restituisce un valore tipizzato. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` restituisce testo. I template sono array; `{{name}}` resta testo letterale. Le espressioni usano CEL e possono leggere questi valori: | Valore | Contenuto | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `trigger.data` | I dati di ingresso, corrispondenti al `data_schema` dell'entry. | | `trigger.node_id` | L'ID dell'entry che ha avviato questa visita. | | `trigger.type` | Il tipo dell’entry che ha avviato questa visita, come `trigger.start_call`. | | `steps..output` | Output di un nodo completato in precedenza in questa visita. | | `variables.` | Valori salvati da un nodo `data.set` in questa visita. | | `execution.id`, `execution.started_at` | L'ID dell'esecuzione e il suo orario di avvio. Usa `string(execution.started_at)` nel parlato. | | `execution.call` | `id`, `session_id` della chiamata e le parti originali `orig` e `dest`, ciascuna delle quali può essere `null`. | Controlla i valori opzionali prima di leggerli, ad esempio `has(trigger.data.name) ? trigger.data.name : 'caller'`. La macro `has` è disponibile; `map`, `filter`, `all`, `exists` e `exists_one` non lo sono. ## Entry ### `trigger.start_call` Punto di partenza di una chiamata. `entry_node_id` nella richiesta Create Call indica questo nodo. | Campo | Valore | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.data_schema` | Schema oggetto JSON Schema (draft 2020-12) opzionale per `trigger_data`. È supportato solo `$ref` locale. Senza di esso, l'entry accetta solo `{}`. | | Outcome | `event`. | I dati di ingresso sono limitati a 16 KiB. ## Voce e audio ### `voice.say` | Campo | Valore | | ---------------- | ------------------------------------------------------------------- | | `input.text` | Obbligatorio, **binds**. Testo da pronunciare, massimo 160 byte. | | `input.language` | Obbligatorio. Codice lingua per la sintesi vocale, ad esempio `en`. | | Outcome | `next`. | ### `voice.play` | Campo | Valore | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.asset_id` | Obbligatorio. ID di un asset audio disponibile in questo spazio di lavoro. Un asset non disponibile può far fallire la chiamata quando lo step viene eseguito. | | Esito | `next`. | ### `voice.tone` | Campo | Valore | | -------------------- | -------------------------------- | | `input.frequency_hz` | Obbligatorio. Da `100` a `3000`. | | `input.duration_ms` | Obbligatorio. Da `1` a `10000`. | | Esito | `next`. | ### `logic.pause` Attende con la chiamata connessa. | Campo | Valore | | ------------------- | ------------------------------- | | `input.duration_ms` | Obbligatorio. Da `1` a `60000`. | | Esito | `next`. | ## Input da tastiera ### `voice.gather` Riproduce i prompt, che la pressione di un tasto interrompe, e raccoglie le cifre digitate. | Campo | Valore | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Obbligatorio. Fino a 4 prompt. Ciascuno è `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` o `{"type": "pause", "duration_ms"}`, con gli stessi limiti del nodo corrispondente. La durata complessiva di toni e pause è al massimo 60.000 ms. Il `text` del prompt supporta **binds**. | | `input.max_digits` | Obbligatorio. Da `1` a `32`. | | `input.timeout_seconds` | Obbligatorio. Secondi di attesa per il primo tasto, da `1` a `10`. | | `input.inter_digit_timeout_seconds` | Obbligatorio. Secondi di attesa tra un tasto e l'altro, da `1` a `5`. | | `input.finish_on_key` | Obbligatorio. Uno tra `0`–`9`, `*`, `#`, `A`–`D` che termina l'input, oppure `null`. | | `input.matches` | Obbligatorio. Mappa da un nome di outcome alle cifre esatte che lo selezionano, ad esempio `{"hours": "1"}`. Nomi e cifre devono essere univoci. Un nome non può essere `input`, `timeout` o `fallback`. Le cifre sono lunghe al massimo `max_digits` e non possono contenere `finish_on_key`. | | `input.private` | Opzionale, default `false`. Quando è `true`, i passaggi successivi non possono leggere le cifre, che vengono escluse dalla traccia. | | Outcome | Ogni nome in `matches`, `timeout` quando nessun tasto viene premuto e `fallback` per qualsiasi altro input. | | Output | `digits` e `reason`: `initial_timeout`, `max_digits`, `finish_key` o `inter_digit_timeout`. | ## Logica e dati ### `logic.branch` Controlla le condizioni in ordine e segue la prima che risulta vera. | Campo | Valore | | --------------------- | ----------------------------------------------------------------------------- | | `config.cases` | Obbligatorio. Almeno un `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Obbligatorio. Nome dell'outcome quando nessun caso è vero. | | Outcome | Ogni `port` in `cases` e `default_port`. | | Output | `branch`: il nome dell'esito selezionato. | ### `data.set` Salva valori per i passaggi successivi nella stessa visita. | Campo | Valore | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input` | Oggetto di valori, ciascuno dei quali accetta **binds**. Ogni chiave diventa `variables.`. Ogni valore è calcolato dalle variabili così come erano prima di questo nodo. | | Esito | `next`. | | Output | L'oggetto salvato. | ## Chiamate e trasferimenti ### `voice.dial` Chiama un altro numero e lo connette alla chiamata in corso. | Campo | Valore | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `input.to` | Obbligatorio, **binds**. Numero E.164, ad esempio `+12025550123`. | | `input.timeout_seconds` | Obbligatorio, **expr**. Secondi di squillo, da `1` a `120`. | | Esiti | `success`, `busy`, `no_answer` e `failure`. `success` segue dopo che la chiamata connessa termina e l'audio della chiamata originale viene ripristinato, non quando il destinatario risponde. Un `failure` non connesso causa il fallimento dell'esecuzione. | ### `logic.voice_goto` Avvia un altro ingresso nella stessa definizione. La nuova visita riceve `trigger.data` nuovo e cancella gli output e le variabili dei passi precedenti; la chiamata prosegue. | Campo | Valore | | --------------------- | ------------------------------------------------------------------------------- | | `input.entry_node_id` | Obbligatorio. ID di un nodo `trigger.start_call` in questa definizione. | | `input.data` | Opzionale, **expr**, default `{}`. Dati di ingresso per lo schema di quel nodo. | | Esiti | Nessuno. | ## Terminare la chiamata ### `logic.exit` Termina la chiamata con un risultato. | Campo | Valore | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `config.status` | Obbligatorio. `succeeded` o `failed`. | | `config.reason` | Facoltativo, **expr**. Codice stabile di lettere minuscole, cifre e `_`, che inizia con una lettera o una cifra, fino a 64 caratteri. Omettilo invece di inviare `null`. | | `input.output` | Oggetto obbligatorio, che può essere `{}`. I suoi valori di primo livello supportano **binds**. | | Esiti | Nessuno. | ### `voice.hangup` Termina la chiamata senza un risultato definito. Non ha campi né esiti. ## Step in accesso anticipato `voice.webhook`, `voice.record_start`, `voice.record_stop` e `logic.voice_goto` con `dependency_id` per la segreteria gestita o la registrazione delle chiamate sono in accesso anticipato e non sono documentati qui. Per utilizzarli è necessario l'accesso per il proprio spazio di lavoro. ## Esempio: trasferimento a una persona Questa definizione saluta il destinatario, chiama un numero di assistenza e registra se il trasferimento è andato a buon fine: ```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": {} } } ] } ``` Inviala come `sequence.definition` con `"entry_node_id": "start"` e `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)