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. Bird esegue una definizione inline una sola volta e non la salva. Per conservare una sequenza, creala nell'editor della dashboard.

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": "<target>", "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.<id>.output`	Output di un nodo completato in precedenza in questa visita.
`variables.<key>`	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": "<name>", "when": {"$expr": "<boolean>"}}`.
`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.<key>`. 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:

Esempio di codice

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

Continua con la documentazione, le guide e gli esempi per questo argomento.

Voice sequences

Risorse correlate