--- title: "Referensi node urutan suara" description: "Cari langkah-langkah yang tersedia secara umum untuk definisi sequence voice inline, lengkap dengan setiap tipe, field, nilai yang diizinkan, dan outcome-nya." --- # Referensi node urutan suara > **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. Gunakan referensi ini untuk menulis `sequence.definition` yang Anda kirim dengan [Buat Panggilan](/docs/guides/voice/create-calls#run-an-inline-sequence). Bird menjalankan definisi inline sekali dan tidak menyimpannya. Untuk menyimpan urutan, buat di [editor dasbor](/docs/guides/voice/sequences/editor). ## Definisi | Field | Nilai | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Array objek node. Urutan array tidak memengaruhi eksekusi. | | `settings` | Abaikan atau kirim `{}`. Objek yang tidak kosong gagal dengan `unsupported_contract`; nilai yang bukan objek gagal dengan `invalid_envelope`. | | `presentation` | Tata letak dan label editor opsional. Tidak memengaruhi eksekusi tetapi dihitung dalam batas ukuran. | Setiap node memiliki field berikut: | Field | Nilai | | -------------- | ---------------------------------------------------------------------------------------------------------------------- | | `id` | Unik dalam definisi. Diawali huruf kecil, lalu huruf kecil, digit, atau `_`, maksimal 64 karakter. | | `type` | Tipe node dari halaman ini, misalnya `voice.say`. | | `type_version` | `1` untuk setiap tipe node di halaman ini. | | `config` | Pengaturan yang menentukan bentuk node, seperti outcome yang dideklarasikan. Gunakan `{}` jika node tidak memilikinya. | | `input` | Nilai yang digunakan node saat dijalankan. Gunakan `{}` jika node tidak memilikinya. | | `connections` | Pemetaan dari nama outcome ke `{ "node_id": "", "port": "input" }`. | Koneksi tidak boleh membentuk loop, dan setiap node harus dapat dijangkau dari entry. Outcome yang tidak ada di `connections` dianggap tidak terhubung. Outcome yang tidak terhubung mengakhiri eksekusi secara normal, kecuali jika node menentukan sebaliknya. ## Nilai dan ekspresi Sebagian besar field menerima JSON literal. Field bertanda **binds** juga menerima `$expr` atau `$template`; field bertanda **expr** hanya menerima `$expr`: - `{"$expr": "trigger.data.customer_name"}` mengembalikan nilai bertipe. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` mengembalikan teks. Template berupa array; `{{name}}` tetap berupa teks literal. Ekspresi menggunakan CEL dan dapat membaca nilai berikut: | Nilai | Isi | | -------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `trigger.data` | Data entry, sesuai dengan `data_schema` dari entry tersebut. | | `trigger.node_id` | ID entry yang memulai kunjungan ini. | | `trigger.type` | Tipe entry yang memulai kunjungan ini, seperti `trigger.start_call`. | | `steps..output` | Output dari node yang telah selesai sebelumnya dalam kunjungan ini. | | `variables.` | Nilai yang disimpan oleh node `data.set` dalam kunjungan ini. | | `execution.id`, `execution.started_at` | ID proses dan waktu mulainya. Gunakan `string(execution.started_at)` dalam ucapan. | | `execution.call` | `id` panggilan, `session_id`, dan pihak asal `orig` serta `dest`, yang masing-masing dapat berupa `null`. | Periksa nilai opsional sebelum membacanya, misalnya `has(trigger.data.name) ? trigger.data.name : 'caller'`. Makro `has` tersedia; `map`, `filter`, `all`, `exists`, dan `exists_one` tidak tersedia. ## Entry ### `trigger.start_call` Tempat panggilan dimulai. `entry_node_id` dalam permintaan Create Call menamai node ini. | Field | Nilai | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.data_schema` | Opsional. Skema objek JSON Schema (draft 2020-12) untuk `trigger_data`. Hanya `$ref` lokal yang didukung. Tanpa skema ini, entry hanya menerima `{}`. | | Outcome | `event`. | Data entry dibatasi hingga 16 KiB. ## Ucapan dan audio ### `voice.say` | Field | Nilai | | ---------------- | --------------------------------------------------------- | | `input.text` | Wajib, **binds**. Teks yang diucapkan, maksimal 160 byte. | | `input.language` | Wajib. Kode bahasa ucapan, seperti `en`. | | Outcome | `next`. | ### `voice.play` | Field | Nilai | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `input.asset_id` | Wajib. ID aset audio yang tersedia di workspace ini. Aset yang tidak tersedia dapat membuat panggilan gagal saat langkah ini dijalankan. | | Outcome | `next`. | ### `voice.tone` | Field | Nilai | | -------------------- | --------------------------- | | `input.frequency_hz` | Wajib. `100` hingga `3000`. | | `input.duration_ms` | Wajib. `1` hingga `10000`. | | Outcome | `next`. | ### `logic.pause` Menunggu dengan panggilan tetap terhubung. | Field | Nilai | | ------------------- | -------------------------- | | `input.duration_ms` | Wajib. `1` hingga `60000`. | | Outcome | `next`. | ## Input keypad ### `voice.gather` Memutar prompt, yang dapat diinterupsi oleh penekanan tombol, dan mengumpulkan digit keypad. | Field | Nilai | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Wajib. Maksimal 4 prompt. Masing-masing berupa `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}`, atau `{"type": "pause", "duration_ms"}`, dengan batasan yang sama seperti node yang sesuai. Total durasi tone dan pause maksimal 60.000 ms. `text` prompt **binds**. | | `input.max_digits` | Wajib. `1` hingga `32`. | | `input.timeout_seconds` | Wajib. Detik menunggu tombol pertama, `1` hingga `10`. | | `input.inter_digit_timeout_seconds` | Wajib. Detik menunggu antar tombol, `1` hingga `5`. | | `input.finish_on_key` | Wajib. Salah satu dari `0`–`9`, `*`, `#`, `A`–`D` yang mengakhiri input, atau `null`. | | `input.matches` | Wajib. Pemetaan dari nama outcome ke digit persis yang memilihnya, seperti `{"hours": "1"}`. Nama dan digit harus unik. Nama tidak boleh `input`, `timeout`, atau `fallback`. Digit maksimal sepanjang `max_digits` dan tidak boleh mengandung `finish_on_key`. | | `input.private` | Opsional, default `false`. Jika `true`, langkah berikutnya tidak dapat membaca digit tersebut, dan digit dihilangkan dari trace. | | Outcome | Setiap nama dalam `matches`, `timeout` saat tidak ada tombol yang ditekan, dan `fallback` untuk input lainnya. | | Output | `digits` dan `reason`: `initial_timeout`, `max_digits`, `finish_key`, atau `inter_digit_timeout`. | ## Logika dan data ### `logic.branch` Memeriksa kondisi secara berurutan dan mengikuti kondisi pertama yang bernilai benar. | Field | Nilai | | --------------------- | ------------------------------------------------------------------------- | | `config.cases` | Wajib. Minimal satu `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Wajib. Nama outcome ketika tidak ada case yang bernilai benar. | | Outcome | Setiap `port` dalam `cases`, dan `default_port`. | | Output | `branch`: nama outcome yang dipilih. | ### `data.set` Menyimpan nilai untuk langkah-langkah selanjutnya dalam kunjungan yang sama. | Field | Nilai | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input` | Objek berisi nilai, masing-masing **binds**. Setiap key menjadi `variables.`. Setiap nilai dihitung dari variabel sebagaimana kondisinya sebelum node ini. | | Outcome | `next`. | | Output | Objek yang disimpan. | ## Panggilan dan transfer ### `voice.dial` Menelepon nomor lain dan menghubungkannya ke panggilan saat ini. | Field | Nilai | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.to` | Wajib, **binds**. Nomor E.164, misalnya `+12025550123`. | | `input.timeout_seconds` | Wajib, **expr**. Detik untuk berdering, `1` sampai `120`. | | Outcome | `success`, `busy`, `no_answer`, dan `failure`. `success` mengikuti setelah panggilan yang terhubung berakhir dan audio panggilan asal dipulihkan, bukan saat tujuan menjawab. `failure` yang tidak terhubung menggagalkan eksekusi. | ### `logic.voice_goto` Memulai entry lain dalam definisi yang sama. Kunjungan baru mendapatkan `trigger.data` baru dan menghapus output serta variabel dari langkah sebelumnya; panggilan tetap berlanjut. | Field | Nilai | | --------------------- | ----------------------------------------------------------------------- | | `input.entry_node_id` | Wajib. ID node `trigger.start_call` dalam definisi ini. | | `input.data` | Opsional, **expr**, default `{}`. Data entry untuk skema node tersebut. | | Outcome | Tidak ada. | ## Mengakhiri panggilan ### `logic.exit` Mengakhiri panggilan dengan hasil. | Field | Nilai | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.status` | Wajib. `succeeded` atau `failed`. | | `config.reason` | Opsional, **expr**. Kode stabil berupa huruf kecil, digit, dan `_`, diawali huruf atau digit, maksimal 64 karakter. Kosongkan alih-alih mengirim `null`. | | `input.output` | Objek wajib, yang boleh berupa `{}`. Nilai level teratasnya **bind**. | | Outcome | Tidak ada. | ### `voice.hangup` Mengakhiri panggilan tanpa hasil yang ditulis. Node ini tidak memiliki field maupun outcome. ## Langkah akses awal `voice.webhook`, `voice.record_start`, `voice.record_stop`, dan `logic.voice_goto` dengan `dependency_id` untuk pesan suara terkelola atau perekaman panggilan masih dalam akses awal dan belum didokumentasikan di sini. Penggunaannya memerlukan akses untuk workspace Anda. ## Contoh: transfer ke seseorang Definisi ini menyapa penerima, menghubungi nomor dukungan, dan mencatat apakah transfer berhasil tersambung: ```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": {} } } ] } ``` Kirim sebagai `sequence.definition` dengan `"entry_node_id": "start"` dan `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)