--- title: "Referência de nós de sequência de voz" description: "Consulte os passos disponíveis de forma geral para uma definição inline de sequência de voz, com cada tipo, seus campos, valores permitidos e resultados." --- # Referência de nós de sequência 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. Use esta referência para escrever o `sequence.definition` que você envia com [Criar chamada](/docs/guides/voice/create-calls#run-an-inline-sequence). Bird executa uma definição inline uma vez e não a salva. Para manter uma sequência, crie-a no [editor do painel](/docs/guides/voice/sequences/editor). ## Definição | Campo | Valor | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Array de objetos de nó. A ordem do array não afeta a execução. | | `settings` | Omita ou envie `{}`. Um objeto não vazio falha com `unsupported_contract`; um valor que não é um objeto falha com `invalid_envelope`. | | `presentation` | Layout e rótulos opcionais do editor. Não afeta a execução, mas conta para os limites de tamanho. | Cada nó tem estes campos: | Campo | Valor | | -------------- | -------------------------------------------------------------------------------------------------------------------- | | `id` | Único na definição. Começa com uma letra minúscula, seguida de letras minúsculas, dígitos ou `_`, até 64 caracteres. | | `type` | Um tipo de nó desta página, como `voice.say`. | | `type_version` | `1` para cada tipo de nó nesta página. | | `config` | Configuração que define a forma do nó, como os resultados declarados. Use `{}` quando o nó não tiver nenhuma. | | `input` | Valores que o nó usa ao ser executado. Use `{}` quando o nó não tiver nenhum. | | `connections` | Mapa de um nome de resultado para `{ "node_id": "", "port": "input" }`. | As conexões não podem formar um loop, e cada nó deve ser alcançável a partir de uma entrada. Um resultado ausente em `connections` fica desconectado. Resultados desconectados encerram a execução normalmente, exceto quando o nó indicar o contrário. ## Valores e expressões A maioria dos campos aceita JSON literais. Campos marcados com **binds** também aceitam `$expr` ou `$template`; campos marcados com **expr** também aceitam apenas `$expr`: - `{"$expr": "trigger.data.customer_name"}` retorna um valor tipado. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` retorna texto. Templates são arrays; `{{name}}` permanece como texto literal. Expressões usam CEL e podem ler estes valores: | Valor | Conteúdo | | -------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `trigger.data` | Os dados de entrada, correspondendo ao `data_schema` da entrada. | | `trigger.node_id` | O ID da entrada que iniciou esta visita. | | `trigger.type` | O tipo da entrada que iniciou esta visita, como `trigger.start_call`. | | `steps..output` | Saída de um nó concluído anteriormente nesta visita. | | `variables.` | Valores salvos por um nó `data.set` nesta visita. | | `execution.id`, `execution.started_at` | O ID da execução e seu horário de início. Use `string(execution.started_at)` em fala. | | `execution.call` | O `id` da chamada, `session_id`, e as partes originais `orig` e `dest`, cada uma podendo ser `null`. | Proteja valores opcionais antes de lê-los, por exemplo `has(trigger.data.name) ? trigger.data.name : 'caller'`. A macro `has` está disponível; `map`, `filter`, `all`, `exists` e `exists_one` não estão. ## Entrada ### `trigger.start_call` Onde uma chamada começa. `entry_node_id` na solicitação Create Call nomeia este nó. | Campo | Valor | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.data_schema` | Esquema de objeto JSON Schema (draft 2020-12) opcional para `trigger_data`. Apenas `$ref` local é suportado. Sem ele, a entrada aceita apenas `{}`. | | Resultado | `event`. | Os dados de entrada são limitados a 16 KiB. ## Fala e áudio ### `voice.say` | Campo | Valor | | ---------------- | ---------------------------------------------------------------- | | `input.text` | Obrigatório, **binds**. Texto a ser falado, no máximo 160 bytes. | | `input.language` | Obrigatório. Código de idioma da fala, como `en`. | | Resultado | `next`. | ### `voice.play` | Campo | Valor | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `input.asset_id` | Obrigatório. ID de um recurso de áudio disponível neste espaço de trabalho. Um recurso indisponível pode causar falha na chamada quando o passo é executado. | | Resultado | `next`. | ### `voice.tone` | Campo | Valor | | -------------------- | ---------------------------- | | `input.frequency_hz` | Obrigatório. `100` a `3000`. | | `input.duration_ms` | Obrigatório. `1` a `10000`. | | Resultado | `next`. | ### `logic.pause` Aguarda com a chamada conectada. | Campo | Valor | | ------------------- | --------------------------- | | `input.duration_ms` | Obrigatório. `1` a `60000`. | | Resultado | `next`. | ## Entrada por teclado ### `voice.gather` Reproduz prompts, que um pressionamento de tecla interrompe, e coleta dígitos do teclado. | Campo | Valor | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Obrigatório. Até 4 prompts. Cada um é `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` ou `{"type": "pause", "duration_ms"}`, com os mesmos limites do nó correspondente. As durações de tom e pausa juntas são no máximo 60.000 ms. O `text` do prompt aceita **binds**. | | `input.max_digits` | Obrigatório. `1` a `32`. | | `input.timeout_seconds` | Obrigatório. Segundos de espera pela primeira tecla, `1` a `10`. | | `input.inter_digit_timeout_seconds` | Obrigatório. Segundos de espera entre teclas, `1` a `5`. | | `input.finish_on_key` | Obrigatório. Um entre `0`–`9`, `*`, `#`, `A`–`D` que encerra a entrada, ou `null`. | | `input.matches` | Obrigatório. Mapa de um nome de resultado para os dígitos exatos que o selecionam, como `{"hours": "1"}`. Nomes e dígitos devem ser únicos. Um nome não pode ser `input`, `timeout` ou `fallback`. Os dígitos têm no máximo `max_digits` de comprimento e não podem conter `finish_on_key`. | | `input.private` | Opcional, padrão `false`. Quando `true`, os passos seguintes não conseguem ler os dígitos, e eles são omitidos do rastreamento. | | Resultados | Cada nome em `matches`, `timeout` quando nenhuma tecla é pressionada e `fallback` para qualquer outra entrada. | | Saída | `digits` e `reason`: `initial_timeout`, `max_digits`, `finish_key` ou `inter_digit_timeout`. | ## Lógica e dados ### `logic.branch` Verifica as condições em ordem e segue a primeira que for verdadeira. | Campo | Valor | | --------------------- | -------------------------------------------------------------------------------- | | `config.cases` | Obrigatório. Pelo menos um `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Obrigatório. Nome do outcome quando nenhum caso é verdadeiro. | | Outcomes | Cada `port` em `cases`, e `default_port`. | | Saída | `branch`: o nome do outcome selecionado. | ### `data.set` Salva valores para etapas posteriores na mesma visita. | Campo | Valor | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `input` | Objeto de valores, cada um dos quais aceita **binds**. Cada chave se torna `variables.`. Todo valor é calculado a partir das variáveis como estavam antes deste nó. | | Outcome | `next`. | | Output | O objeto salvo. | ## Chamadas e transferências ### `voice.dial` Liga para outro número e conecta à chamada atual. | Campo | Valor | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.to` | Obrigatório, **binds**. Número E.164, como `+12025550123`. | | `input.timeout_seconds` | Obrigatório, **expr**. Segundos de toque, `1` a `120`. | | Resultados | `success`, `busy`, `no_answer` e `failure`. `success` ocorre depois que a chamada conectada termina e o áudio da chamada original é restaurado, não quando o destino atende. Um `failure` não conectado falha a execução. | ### `logic.voice_goto` Inicia outra entrada na mesma definição. A nova visita recebe `trigger.data` novos e limpa as saídas e variáveis de etapas anteriores; a chamada continua. | Campo | Valor | | --------------------- | -------------------------------------------------------------------------- | | `input.entry_node_id` | Obrigatório. ID de um nó `trigger.start_call` nesta definição. | | `input.data` | Opcional, **expr**, padrão `{}`. Dados de entrada para o esquema desse nó. | | Resultados | Nenhum. | ## Encerramento da chamada ### `logic.exit` Encerra a chamada com um resultado. | Campo | Valor | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.status` | Obrigatório. `succeeded` ou `failed`. | | `config.reason` | Opcional, **expr**. Código estável de letras minúsculas, dígitos e `_`, começando com uma letra ou dígito, até 64 caracteres. Omita-o em vez de enviar `null`. | | `input.output` | Objeto obrigatório, que pode ser `{}`. Seus valores de nível superior aceitam **binds**. | | Resultados | Nenhum. | ### `voice.hangup` Encerra a chamada sem um resultado definido pelo autor. Não tem campos nem resultados. ## Etapas em acesso antecipado `voice.webhook`, `voice.record_start`, `voice.record_stop` e `logic.voice_goto` com `dependency_id` para correio de voz gerenciado ou gravação de chamadas estão em acesso antecipado e não estão documentados aqui. Para usá-los, é necessário acesso para o seu espaço de trabalho. ## Exemplo: transferir para uma pessoa Esta definição cumprimenta o destinatário, disca um número de suporte e registra se a transferência foi conectada: ```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": {} } } ] } ``` Envie como `sequence.definition` com `"entry_node_id": "start"` e `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)