Riferimento ai nodi delle sequenze vocali

Avviso: le sequenze vocali sono in anteprima. Passaggi, dati di ingresso e formato della definizione di sequenza possono cambiare in modi che rendono non funzionanti le sequenze esistenti e le richieste API.

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, tranne `3` per `voice.dial`.
`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 Crea chiamata 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 `{}`.
Esito	`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`.
Esito	`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 esito 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.
Esiti	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'esito quando nessun caso è vero.
Esiti	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 numero di telefono o un numero su uno dei trunk SIP in ingresso del tuo spazio di lavoro, oppure fa squillare un gruppo di squillo, e lo connette alla chiamata in corso. Usa type_version 3.

Campo	Valore
`input.type`	Obbligatorio. `pstn` per chiamare un numero di telefono, `sip_trunk` per chiamare un numero tramite uno dei tuoi trunk SIP in ingresso, oppure `ring_group` per far squillare i membri online di un gruppo di squillo.
`input.pstn`	Obbligatorio quando `type` è `pstn`, altrimenti omesso. Oggetto con `dest` e `orig` opzionale.
`input.sip_trunk`	Obbligatorio quando `type` è `sip_trunk`, altrimenti omesso. Oggetto con `trunk_id`, `dest` e `orig` opzionale.
`input.ring_group`	Obbligatorio quando `type` è `ring_group`, altrimenti da omettere. Oggetto con `ring_group_id`.
`trunk_id`	Obbligatorio in `sip_trunk`. ID di un trunk SIP in ingresso nel tuo spazio di lavoro, ad esempio `spt_01jzj6c0p4f8b3x2m9k7q5r1tw`. Solo valore letterale.
`ring_group_id`	Obbligatorio in `ring_group`. ID di un ring group nel tuo spazio di lavoro, compreso il gruppo predefinito, ad esempio `vrg_01jzj6c0p4f8b3x2m9k7q5r1tw`. Solo valore letterale.
`dest`	Obbligatorio, binds. Per `pstn`, il numero E.164 da chiamare, ad esempio `+12025550123`. Per `sip_trunk`, un numero, un interno o un nome, ad esempio `1001`: da 1 a 64 lettere, cifre e `+*._-`. Il routing in ingresso del trunk consegna la chiamata come se fosse arrivata per questo valore.
`orig`	Opzionale, binds. Se ometti la proprietà `orig`, la chiamata mostra il numero Bird composto in una chiamata in ingresso o il numero di origine in una chiamata in uscita. Per `pstn`, usa un ID chiamante dello spazio di lavoro o il numero E.164 valido del chiamante in ingresso. I numeri dei chiamanti in ingresso vengono inviati senza firma e l'operatore ricevente può filtrarli. Per `sip_trunk`, accetta gli stessi valori di `dest`, ad esempio `sales`.
`input.timeout_seconds`	Obbligatorio per `pstn` e `sip_trunk`, da omettere per `ring_group`, expr. Secondi di attesa di una risposta, compreso il failover tra i gateway del trunk, da `1` a `120`. Le chiamate senza risposta prendono `no_answer`; una chiamata con risposta non ha limiti di durata.
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 trunk SIP che rifiuta o inoltra la chiamata seleziona `failure`. Un `failure` non connesso causa il fallimento dell'esecuzione. Per un ring group, `busy` indica che i membri erano occupati, hanno rifiutato o erano impegnati in un'altra chiamata, `no_answer` indica che nessuno ha risposto entro 60 secondi o che nessuno era online, e `failure` indica che Bird non è riuscito a far squillare il gruppo.

La versione 2 non ha la destinazione ring_group e richiede sempre timeout_seconds. Ogni input valido nella versione 2 è valido anche nella versione 3, quindi aggiornare un passaggio non cambia nient'altro.

La versione 1 accetta il numero in input.to e non ha orig. I passaggi che la usano continuano a funzionare. Quando aggiorni nell'editor un passaggio della versione 1, il suo valore to viene spostato in pstn.dest.

`logic.voice_goto`

Avvia un'altra entry nella stessa definizione. La nuova visita riceve un nuovo trigger.data e cancella gli output e le variabili dei passaggi 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.

Automations

`automation.send_event`

Invia un evento applicativo a un'automazione senza attendere un'esecuzione. La chiamata prosegue appena l'evento è in coda; se un'esecuzione viene avviata è visibile solo in Automations.

Campo	Valore
`input.automation_id`	Obbligatorio. ID di un'automazione in questo spazio di lavoro.
`input.event`	Obbligatorio. Il nome dell'evento dell'automazione: da 1 a 128 lettere, cifre, punti, trattini bassi o trattini.
`input.data`	Opzionale, default `{}`. L'intero contenuto dei dati dell'evento. I suoi valori di primo livello supportano binds, oppure l'intero oggetto può essere un unico `$expr`. I valori annidati più in profondità restano letterali. L'intero `input` è al massimo 16 KiB.
Esiti	`success` quando l'evento è in coda, oppure `failure` se non può esserlo. Nessuno dei due riporta l'esecuzione dell'automazione. Un `failure` non connesso causa il fallimento dell'esecuzione.

Terminare la chiamata

`logic.exit`

Termina la chiamata con un risultato.

Campo	Valore
`config.status`	Obbligatorio. `succeeded` o `failed`.
`config.reason`	Opzionale, 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.

Per voice.webhook, consulta Usare i dati applicativi in una sequenza vocale.

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": 3,
      "config": {},
      "input": { "type": "pstn", "pstn": { "dest": "+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