--- title: "Referencia de nodos de secuencia de voz" description: "Consulta los pasos disponibles de forma general para una definición de secuencia de voz en línea, con cada tipo, sus campos, valores permitidos y resultados." --- # 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](/docs/guides/voice/create-calls#run-an-inline-sequence). 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](/docs/guides/voice/sequences/editor). ## 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": "", "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..output` | Salida de un nodo completado anteriormente en esta visita. | | `variables.` | 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": "", "when": {"$expr": ""}}`. | | `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.`. 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ó: ```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": {} } } ] } ``` Envíala como `sequence.definition` con `"entry_node_id": "start"` y `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)