Referencia de nodos de secuencia de voz

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 esta referencia para escribir el sequence.definition que envías con Crear llamada. Bird ejecuta una definición en línea una vez y no la guarda. Para conservar una secuencia, constrúyela en el editor del panel.

Definición

Campo	Valor
`schema_version`	`1`.
`expression_environment`	`"bird.cel.v1"`.
`nodes`	Array de objetos de nodo. El orden del array no afecta la ejecución.
`settings`	Omítelo o envía `{}`. Un objeto no vacío falla con `unsupported_contract`; un valor que no es un objeto falla con `invalid_envelope`.
`presentation`	Diseño y etiquetas opcionales del editor. No afecta la ejecución, pero cuenta para los límites de tamaño.

Cada nodo tiene estos campos:

Campo	Valor
`id`	Único en la definición. Comienza con una letra minúscula, seguida de letras minúsculas, dígitos o `_`, hasta 64 caracteres.
`type`	Un tipo de nodo de esta página, como `voice.say`.
`type_version`	`1` para cada tipo de nodo en esta página.
`config`	Configuración que fija la forma del nodo, como los outcomes declarados. Usa `{}` cuando el nodo no tenga ninguna.
`input`	Valores que el nodo usa cuando se ejecuta. Usa `{}` cuando el nodo no tenga ninguno.
`connections`	Mapa de un nombre de outcome a `{ "node_id": "<target>", "port": "input" }`.

Las conexiones no deben formar un ciclo, y cada nodo debe ser alcanzable desde una entrada. Un outcome omitido de connections queda sin conectar. Los outcomes sin conectar terminan la ejecución con normalidad, salvo que un nodo indique lo contrario.

Valores y expresiones

La mayoría de los campos aceptan JSON literales. Los campos marcados con binds también aceptan $expr o $template; los campos marcados con expr también aceptan solo $expr:

{"$expr": "trigger.data.customer_name"} devuelve un valor tipado.
{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]} devuelve texto. Las plantillas son arrays; {{name}} permanece como texto literal.

Las expresiones usan CEL y pueden leer estos valores:

Valor	Contenido
`trigger.data`	Los datos de entrada, correspondientes al `data_schema` de la entrada.
`trigger.node_id`	El ID de la entrada que inició esta visita.
`trigger.type`	El tipo de la entrada que inició esta visita, como `trigger.start_call`.
`steps.<id>.output`	Salida de un nodo completado anteriormente en esta visita.
`variables.<key>`	Valores guardados por un nodo `data.set` en esta visita.
`execution.id`, `execution.started_at`	El ID de la ejecución y su hora de inicio. Usa `string(execution.started_at)` en el habla.
`execution.call`	El `id` y `session_id` de la llamada, y las partes originales `orig` y `dest`, cada una de las cuales puede ser `null`.

Protege los valores opcionales antes de leerlos, por ejemplo has(trigger.data.name) ? trigger.data.name : 'caller'. La macro has está disponible; map, filter, all, exists y exists_one no lo están.

Entrada

`trigger.start_call`

Donde comienza una llamada. entry_node_id en la solicitud Create Call nombra este nodo.

Campo	Valor
`config.data_schema`	Esquema de objeto JSON Schema (draft 2020-12) opcional para `trigger_data`. Solo se admite `$ref` local. Sin él, la entrada solo acepta `{}`.
Resultado	`event`.

Los datos de entrada están limitados a 16 KiB.

Voz y audio

`voice.say`

Campo	Valor
`input.text`	Obligatorio, binds. Texto a pronunciar, como máximo 160 bytes.
`input.language`	Obligatorio. Código de idioma de voz, por ejemplo `en`.
Resultado	`next`.

`voice.play`

Campo	Valor
`input.asset_id`	Obligatorio. ID de un recurso de audio disponible en este espacio de trabajo. Un recurso no disponible puede hacer fallar la llamada cuando se ejecuta el paso.
Resultado	`next`.

`voice.tone`

Campo	Valor
`input.frequency_hz`	Obligatorio. `100` a `3000`.
`input.duration_ms`	Obligatorio. `1` a `10000`.
Resultado	`next`.

`logic.pause`

Espera con la llamada conectada.

Campo	Valor
`input.duration_ms`	Obligatorio. `1` a `60000`.
Resultado	`next`.

Entrada por teclado

`voice.gather`

Reproduce indicaciones, que una pulsación de tecla interrumpe, y recoge dígitos del teclado.

Campo	Valor
`input.prompts`	Obligatorio. Hasta 4 prompts. Cada uno es `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` o `{"type": "pause", "duration_ms"}`, con los mismos límites que el nodo correspondiente. Las duraciones de tono y pausa juntas son como máximo 60 000 ms. El `text` del prompt acepta binds.
`input.max_digits`	Obligatorio. `1` a `32`.
`input.timeout_seconds`	Obligatorio. Segundos de espera para la primera tecla, `1` a `10`.
`input.inter_digit_timeout_seconds`	Obligatorio. Segundos de espera entre teclas, `1` a `5`.
`input.finish_on_key`	Obligatorio. Uno de `0`–`9`, `*`, `#`, `A`–`D` que finaliza la entrada, o `null`.
`input.matches`	Obligatorio. Mapa de un nombre de resultado a los dígitos exactos que lo seleccionan, como `{"hours": "1"}`. Los nombres y los dígitos deben ser únicos. Un nombre no puede ser `input`, `timeout` ni `fallback`. Los dígitos tienen como máximo `max_digits` de longitud y no pueden contener `finish_on_key`.
`input.private`	Opcional, por defecto `false`. Cuando es `true`, los pasos posteriores no pueden leer los dígitos y se omiten del trace.
Resultados	Cada nombre en `matches`, `timeout` cuando no se presiona ninguna tecla, y `fallback` para cualquier otra entrada.
Salida	`digits` y `reason`: `initial_timeout`, `max_digits`, `finish_key` o `inter_digit_timeout`.

Lógica y datos

`logic.branch`

Evalúa condiciones en orden y sigue la primera que sea verdadera.

Campo	Valor
`config.cases`	Obligatorio. Al menos un `{"port": "<name>", "when": {"$expr": "<boolean>"}}`.
`config.default_port`	Obligatorio. Nombre del resultado cuando ningún caso es verdadero.
Resultados	Cada `port` en `cases`, y `default_port`.
Salida	`branch`: el nombre del resultado seleccionado.

`data.set`

Guarda valores para pasos posteriores en la misma visita.

Campo	Valor
`input`	Objeto de valores, cada uno de los cuales acepta binds. Cada clave se convierte en `variables.<key>`. Cada valor se calcula a partir de las variables tal como estaban antes de este nodo.
Resultado	`next`.
Salida	El objeto guardado.

Llamadas y transferencias

`voice.dial`

Llama a otro número y lo conecta a la llamada actual.

Campo	Valor
`input.to`	Obligatorio, binds. Número E.164, como `+12025550123`.
`input.timeout_seconds`	Obligatorio, expr. Segundos de timbre, de `1` a `120`.
Resultados	`success`, `busy`, `no_answer` y `failure`. `success` se ejecuta después de que la llamada conectada termina y se restaura el audio de la llamada original, no cuando el destino contesta. Un `failure` no conectado hace fallar la ejecución.

`logic.voice_goto`

Inicia otra entrada en la misma definición. La nueva visita recibe trigger.data nuevos y borra las salidas y variables de pasos anteriores; la llamada continúa.

Campo	Valor
`input.entry_node_id`	Obligatorio. ID de un nodo `trigger.start_call` en esta definición.
`input.data`	Opcional, expr, por defecto `{}`. Datos de entrada para el esquema de ese nodo.
Resultados	Ninguno.

Finalizar la llamada

`logic.exit`

Finaliza la llamada con un resultado.

Campo	Valor
`config.status`	Obligatorio. `succeeded` o `failed`.
`config.reason`	Opcional, expr. Código estable de letras minúsculas, dígitos y `_`, que comience con una letra o un dígito, de hasta 64 caracteres. Omítelo en lugar de enviar `null`.
`input.output`	Objeto obligatorio, que puede ser `{}`. Sus valores de nivel superior aceptan binds.
Resultados	Ninguno.

`voice.hangup`

Finaliza la llamada sin un resultado definido. No tiene campos ni resultados.

Pasos en acceso anticipado

voice.webhook, voice.record_start, voice.record_stop y logic.voice_goto con dependency_id para buzón de voz gestionado o grabación de llamadas están en acceso anticipado y no se documentan aquí. Para usarlos necesitas acceso en tu espacio de trabajo.

Ejemplo: transferir a una persona

Esta definición saluda al destinatario, marca un número de soporte y registra si la transferencia se conectó:

Ejemplo de código

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

Envíala como sequence.definition con "entry_node_id": "start" y "trigger_data": {}.

Continúa con la documentación, guías y ejemplos de este tema.

Voice sequences

Recursos relacionados