Referencia de nodos de secuencia de voz
Advertencia: Las secuencias de voz están en versión preliminar. Los pasos, los datos de entrada y el formato de definición de secuencias pueden cambiar de formas que rompan las secuencias existentes y las solicitudes API.
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 de esta página, excepto 3 para voice.dial. |
config | Configuración que fija la forma del nodo, como los resultados 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 resultado a { "node_id": "<target>", "port": "input" }. |
Las conexiones no deben formar un ciclo, y cada nodo debe ser alcanzable desde una entrada. Un resultado omitido de connections queda sin conectar. Los resultados 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 indicaciones. Cada una 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 de la indicación 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 de la traza. |
| 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 un número de teléfono o a un número de uno de los troncales SIP entrantes de tu espacio de trabajo, o hace sonar un grupo de timbre, y lo conecta a la llamada actual. Usa type_version 3.
| Campo | Valor |
|---|---|
input.type | Obligatorio. pstn para llamar a un número de teléfono, sip_trunk para llamar a un número a través de uno de tus troncales SIP entrantes, o ring_group para hacer sonar a los miembros conectados de un grupo de timbre. |
input.pstn | Obligatorio cuando type es pstn; en otro caso, se omite. Objeto con dest y orig opcional. |
input.sip_trunk | Obligatorio cuando type es sip_trunk; en otro caso, se omite. Objeto con trunk_id, dest y orig opcional. |
input.ring_group | Obligatorio cuando type es ring_group; se omite en los demás casos. Objeto con ring_group_id. |
trunk_id | Obligatorio en sip_trunk. ID de un troncal SIP entrante de tu espacio de trabajo, como spt_01jzj6c0p4f8b3x2m9k7q5r1tw. Solo admite un valor literal. |
ring_group_id | Obligatorio en ring_group. ID de un grupo de timbre de tu espacio de trabajo, incluido su grupo predeterminado, como vrg_01jzj6c0p4f8b3x2m9k7q5r1tw. Solo admite un valor literal. |
dest | Obligatorio, binds. Para pstn, el número E.164 al que llamar, como +12025550123. Para sip_trunk, un número, una extensión o un nombre, como 1001: de 1 a 64 letras, dígitos y +*._-. El enrutamiento entrante del troncal entrega la llamada como si hubiera llegado para este valor. |
orig | Opcional, binds. Si omites la propiedad orig, la llamada muestra el número Bird marcado en una llamada entrante o el número de origen en una llamada saliente. Para pstn, usa un identificador de llamada del espacio de trabajo o el número E.164 válido de quien llama. Los números de quien llama se envían sin firmar y el operador receptor puede filtrarlos. Para sip_trunk, admite los mismos valores que dest, como sales. |
input.timeout_seconds | Obligatorio para pstn y sip_trunk, y se omite para ring_group, expr. Segundos de espera para que contesten, incluida la conmutación por error entre pasarelas del troncal, de 1 a 120. Las llamadas sin respuesta toman no_answer; una llamada contestada no tiene límite. |
| Resultados | success, busy, no_answer y failure. success se sigue después de que la llamada conectada termina y se restaura el audio de la llamada original, no cuando el destino contesta. Un tronco SIP que rechaza o desvía la llamada selecciona failure. Un failure no conectado hace fallar la ejecución. En un grupo de timbrado, busy significa que sus miembros estaban ocupados, rechazaron la llamada o estaban en otra llamada; no_answer significa que nadie contestó en 60 segundos o que nadie estaba en línea; y failure significa que Bird no pudo hacer sonar el grupo. |
La versión 2 no tiene destino ring_group y siempre requiere timeout_seconds. Toda entrada válida en la versión 2 también es válida en la versión 3, así que actualizar un paso no cambia nada más.
La versión 1 recibe el número en input.to y no tiene orig. Los pasos que la usan siguen ejecutándose. Cuando actualizas un paso de la versión 1 en el editor, su valor de to pasa a pstn.dest.
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. |
Automations
automation.send_event
Envía un evento de aplicación a una Automation sin esperar a que se ejecute. La llamada continúa en cuanto el evento entra en la cola; solo puedes ver en Automations si se inicia una ejecución.
| Campo | Valor |
|---|---|
input.automation_id | Obligatorio. ID de una automatización de este espacio de trabajo. |
input.event | Obligatorio. El nombre del evento de la automatización: de 1 a 128 letras, dígitos, puntos, guiones bajos o guiones. |
input.data | Opcional, por defecto {}. Todos los datos del evento. Sus valores de nivel superior aceptan bind, o el objeto completo puede ser un único $expr. Los valores anidados a más profundidad permanecen literales. El input completo ocupa como máximo 16 KiB. |
| Resultados | success cuando el evento queda en cola, o failure si no se puede poner en cola. Ninguno de los dos informa de la ejecución de la automatización. Un failure no conectado hace fallar la ejecución. |
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.
Consulta Usar datos de aplicación en una secuencia de voz para voice.webhook.
Ejemplo: transferir a una persona
Esta definición saluda al destinatario, marca un número de soporte y registra si la transferencia se conectó:
{
"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": {} }
}
]
}Envíala como sequence.definition con "entry_node_id": "start" y "trigger_data": {}.
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.