--- title: "Dokumentacja węzłów sekwencji głosowej" description: "Sprawdź ogólnie dostępne kroki dla wbudowanej definicji sekwencji głosowej, z każdym typem, jego polami, dozwolonymi wartościami i wynikami." --- # Dokumentacja węzłów sekwencji głosowej > **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. Użyj tej dokumentacji, aby napisać `sequence.definition`, który wysyłasz za pomocą [Create Call](/docs/guides/voice/create-calls#run-an-inline-sequence). Bird uruchamia definicję inline jednorazowo i nie zapisuje jej. Aby zachować sekwencję, zbuduj ją w [edytorze dashboardu](/docs/guides/voice/sequences/editor). ## Definicja | Pole | Wartość | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Tablica obiektów węzłów. Kolejność elementów tablicy nie wpływa na wykonanie. | | `settings` | Pomiń lub wyślij `{}`. Niepusty obiekt powoduje błąd `unsupported_contract`; wartość, która nie jest obiektem, powoduje błąd `invalid_envelope`. | | `presentation` | Opcjonalny układ i etykiety edytora. Nie wpływa na wykonanie, ale wlicza się do limitów rozmiaru. | Każdy węzeł ma następujące pola: | Pole | Wartość | | -------------- | --------------------------------------------------------------------------------------------------------- | | `id` | Unikalny w definicji. Zaczyna się od małej litery, potem małe litery, cyfry lub `_`, do 64 znaków. | | `type` | Typ węzła z tej strony, na przykład `voice.say`. | | `type_version` | `1` dla każdego typu węzła na tej stronie. | | `config` | Konfiguracja ustalająca kształt węzła, na przykład zadeklarowane wyniki. Użyj `{}`, gdy węzeł ich nie ma. | | `input` | Wartości używane przez węzeł podczas wykonywania. Użyj `{}`, gdy węzeł ich nie ma. | | `connections` | Mapa z nazwy wyniku do `{ "node_id": "", "port": "input" }`. | Połączenia nie mogą tworzyć pętli, a każdy węzeł musi być osiągalny z punktu wejścia. Wynik pominięty w `connections` jest niepodłączony. Niepodłączone wyniki kończą przebieg normalnie, chyba że węzeł określa inaczej. ## Wartości i wyrażenia Większość pól przyjmuje literalne JSON. Pola oznaczone **binds** przyjmują również `$expr` lub `$template`; pola oznaczone **expr** przyjmują również wyłącznie `$expr`: - `{"$expr": "trigger.data.customer_name"}` zwraca wartość typowaną. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` zwraca tekst. Szablony są tablicami; `{{name}}` pozostaje tekstem literalnym. Wyrażenia używają CEL i mogą odczytywać następujące wartości: | Wartość | Zawartość | | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | | `trigger.data` | Dane wejściowe, zgodne z `data_schema` wejścia. | | `trigger.node_id` | Identyfikator wejścia, które rozpoczęło tę wizytę. | | `trigger.type` | Typ wejścia, które rozpoczęło tę wizytę, na przykład `trigger.start_call`. | | `steps..output` | Wynik wcześniej ukończonego węzła w tej wizycie. | | `variables.` | Wartości zapisane przez węzeł `data.set` w tej wizycie. | | `execution.id`, `execution.started_at` | Identyfikator uruchomienia i czas jego rozpoczęcia. Użyj `string(execution.started_at)` w mowie. | | `execution.call` | `id` połączenia, `session_id` oraz oryginalne strony `orig` i `dest`, z których każda może być `null`. | Zabezpiecz wartości opcjonalne przed ich odczytaniem, na przykład `has(trigger.data.name) ? trigger.data.name : 'caller'`. Makro `has` jest dostępne; `map`, `filter`, `all`, `exists` i `exists_one` nie są dostępne. ## Wejście ### `trigger.start_call` Miejsce, w którym połączenie się rozpoczyna. `entry_node_id` w żądaniu Create Call wskazuje ten węzeł. | Pole | Wartość | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.data_schema` | Opcjonalny schemat obiektu JSON Schema (draft 2020-12) dla `trigger_data`. Obsługiwany jest tylko lokalny `$ref`. Bez niego wejście akceptuje jedynie `{}`. | | Wynik | `event`. | Dane wejściowe są ograniczone do 16 KiB. ## Mowa i dźwięk ### `voice.say` | Pole | Wartość | | ---------------- | ----------------------------------------------------------------- | | `input.text` | Wymagane, **binds**. Tekst do odczytania, maksymalnie 160 bajtów. | | `input.language` | Wymagane. Kod języka mowy, na przykład `en`. | | Wynik | `next`. | ### `voice.play` | Pole | Wartość | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.asset_id` | Wymagane. ID zasobu audio dostępnego w tym obszarze roboczym. Niedostępny zasób może spowodować niepowodzenie połączenia w momencie wykonania kroku. | | Wynik | `next`. | ### `voice.tone` | Pole | Wartość | | -------------------- | -------------------------- | | `input.frequency_hz` | Wymagane. `100` do `3000`. | | `input.duration_ms` | Wymagane. `1` do `10000`. | | Wynik | `next`. | ### `logic.pause` Czeka z aktywnym połączeniem. | Pole | Wartość | | ------------------- | ------------------------- | | `input.duration_ms` | Wymagane. `1` do `60000`. | | Wynik | `next`. | ## Wprowadzanie z klawiatury ### `voice.gather` Odtwarza komunikaty, które naciśnięcie klawisza przerywa, i zbiera cyfry z klawiatury. | Pole | Wartość | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Wymagane. Maksymalnie 4 komunikaty. Każdy to `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` lub `{"type": "pause", "duration_ms"}`, z takimi samymi limitami jak odpowiadający węzeł. Łączny czas trwania tonów i pauz wynosi najwyżej 60000 ms. `text` komunikatu obsługuje **binds**. | | `input.max_digits` | Wymagane. Od `1` do `32`. | | `input.timeout_seconds` | Wymagane. Sekundy oczekiwania na pierwszy klawisz, od `1` do `10`. | | `input.inter_digit_timeout_seconds` | Wymagane. Sekundy oczekiwania między klawiszami, od `1` do `5`. | | `input.finish_on_key` | Wymagane. Jeden z `0`–`9`, `*`, `#`, `A`–`D` kończący wprowadzanie, lub `null`. | | `input.matches` | Wymagane. Mapa z nazwy wyniku na dokładne cyfry, które go wybierają, na przykład `{"hours": "1"}`. Nazwy i cyfry muszą być unikalne. Nazwa nie może być `input`, `timeout` ani `fallback`. Cyfry mają co najwyżej `max_digits` znaków i nie mogą zawierać `finish_on_key`. | | `input.private` | Opcjonalne, domyślnie `false`. Gdy `true`, późniejsze kroki nie mogą odczytać cyfr, a cyfry są pomijane w śladzie. | | Wyniki | Każda nazwa w `matches`, `timeout` gdy żaden klawisz nie został naciśnięty, oraz `fallback` dla każdego innego wejścia. | | Wyjście | `digits` i `reason`: `initial_timeout`, `max_digits`, `finish_key` lub `inter_digit_timeout`. | ## Logika i dane ### `logic.branch` Sprawdza warunki po kolei i podąża za pierwszym, który jest prawdziwy. | Pole | Wartość | | --------------------- | --------------------------------------------------------------------------------- | | `config.cases` | Wymagane. Co najmniej jeden `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Wymagane. Nazwa wyniku, gdy żaden przypadek nie jest prawdziwy. | | Wyniki | Każdy `port` w `cases` oraz `default_port`. | | Dane wyjściowe | `branch`: nazwa wybranego wyniku. | ### `data.set` Zapisuje wartości dla późniejszych kroków w tej samej wizycie. | Pole | Wartość | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `input` | Obiekt wartości, z których każda obsługuje **binds**. Każdy klucz staje się `variables.`. Każda wartość jest obliczana na podstawie zmiennych w stanie sprzed tego węzła. | | Wynik | `next`. | | Output | Zapisany obiekt. | ## Połączenia i przekierowania ### `voice.dial` Dzwoni pod inny numer i łączy go z bieżącym połączeniem. | Pole | Wartość | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.to` | Wymagane, **binds**. Numer E.164, np. `+12025550123`. | | `input.timeout_seconds` | Wymagane, **expr**. Czas dzwonienia w sekundach, od `1` do `120`. | | Wyniki | `success`, `busy`, `no_answer` i `failure`. `success` następuje po zakończeniu połączonego połączenia i przywróceniu dźwięku oryginalnego połączenia, a nie w momencie odebrania przez odbiorcę. Niepodłączony `failure` powoduje niepowodzenie przebiegu. | ### `logic.voice_goto` Rozpoczyna nowe wejście w tej samej definicji. Nowa wizyta otrzymuje świeże `trigger.data` i czyści wyjścia oraz zmienne wcześniejszych kroków; połączenie trwa dalej. | Pole | Wartość | | --------------------- | ----------------------------------------------------------------------------- | | `input.entry_node_id` | Wymagane. ID węzła `trigger.start_call` w tej definicji. | | `input.data` | Opcjonalne, **expr**, domyślnie `{}`. Dane wejściowe dla schematu tego węzła. | | Wyniki | Brak. | ## Kończenie połączenia ### `logic.exit` Kończy połączenie z wynikiem. | Pole | Wartość | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.status` | Wymagane. `succeeded` lub `failed`. | | `config.reason` | Opcjonalne, **expr**. Stały kod złożony z małych liter, cyfr i `_`, zaczynający się od litery lub cyfry, do 64 znaków. Pomiń go zamiast wysyłać `null`. | | `input.output` | Wymagany obiekt, który może być `{}`. Jego wartości najwyższego poziomu obsługują **binds**. | | Wyniki | Brak. | ### `voice.hangup` Kończy połączenie bez zdefiniowanego wyniku. Nie ma pól ani rezultatów. ## Kroki we wczesnym dostępie `voice.webhook`, `voice.record_start`, `voice.record_stop` i `logic.voice_goto` z `dependency_id` do zarządzanej poczty głosowej lub nagrywania rozmów są w fazie wczesnego dostępu i nie są tu udokumentowane. Korzystanie z nich wymaga dostępu dla Twojego obszaru roboczego. ## Przykład: przekierowanie do osoby Ta definicja wita odbiorcę, wybiera numer wsparcia i rejestruje, czy przekierowanie zostało połączone: ```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": {} } } ] } ``` Wyślij ją jako `sequence.definition` z `"entry_node_id": "start"` i `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)