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. Bird executa uma definição inline uma vez e não a salva. Para manter uma sequência, crie-a no editor do painel.

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": "<target>", "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.<id>.output`	Saída de um nó concluído anteriormente nesta visita.
`variables.<key>`	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": "<name>", "when": {"$expr": "<boolean>"}}`.
`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.<key>`. 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:

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

Envie como sequence.definition com "entry_node_id": "start" e "trigger_data": {}.

Continue com a documentação, guias e exemplos sobre este tópico.

Voice sequences

Recursos relacionados