--- title: "Referenz der Voice-Sequence-Nodes" description: "Nachschlagewerk für die allgemein verfügbaren Schritte einer Inline-Voice-Sequence-Definition, mit jedem Typ, seinen Feldern, erlaubten Werten und Ergebnissen." --- # Referenz der Voice-Sequence-Nodes > **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. Verwenden Sie diese Referenz, um die `sequence.definition` zu schreiben, die Sie mit [Anruf erstellen](/docs/guides/voice/create-calls#run-an-inline-sequence) senden. Bird führt eine Inline-Definition einmalig aus und speichert sie nicht. Um eine Sequence dauerhaft zu behalten, erstellen Sie sie im [Dashboard-Editor](/docs/guides/voice/sequences/editor). ## Definition | Feld | Wert | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schema_version` | `1`. | | `expression_environment` | `"bird.cel.v1"`. | | `nodes` | Array aus Node-Objekten. Die Reihenfolge im Array hat keinen Einfluss auf die Ausführung. | | `settings` | Weglassen oder `{}` senden. Ein nicht leeres Objekt schlägt mit `unsupported_contract` fehl; ein Wert, der kein Objekt ist, schlägt mit `invalid_envelope` fehl. | | `presentation` | Optionales Editor-Layout und Bezeichnungen. Hat keinen Einfluss auf die Ausführung, zählt aber zum Größenlimit. | Jeder Node hat diese Felder: | Feld | Wert | | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `id` | Eindeutig in der Definition. Beginnt mit einem Kleinbuchstaben, dann Kleinbuchstaben, Ziffern oder `_`, bis zu 64 Zeichen. | | `type` | Ein Node-Typ von dieser Seite, z. B. `voice.say`. | | `type_version` | `1` für jeden Knotentyp auf dieser Seite. | | `config` | Konfiguration, die die Form des Knotens festlegt, z. B. deklarierte Outcomes. Verwenden Sie `{}`, wenn der Knoten keine hat. | | `input` | Werte, die der Knoten bei der Ausführung verwendet. Verwenden Sie `{}`, wenn der Knoten keine hat. | | `connections` | Zuordnung von einem Outcome-Namen zu `{ "node_id": "", "port": "input" }`. | Verbindungen dürfen keine Schleife bilden, und jeder Knoten muss von einem Einstiegspunkt aus erreichbar sein. Ein Outcome, das in `connections` fehlt, ist nicht verbunden. Nicht verbundene Outcomes beenden den Durchlauf normal, sofern ein Knoten nichts anderes vorgibt. ## Werte und Ausdrücke Die meisten Felder akzeptieren literale JSON. Mit **binds** gekennzeichnete Felder akzeptieren auch `$expr` oder `$template`; mit **expr** gekennzeichnete Felder akzeptieren nur `$expr`: - `{"$expr": "trigger.data.customer_name"}` gibt einen typisierten Wert zurück. - `{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]}` gibt Text zurück. Templates sind Arrays; `{{name}}` bleibt literaler Text. Ausdrücke verwenden CEL und können diese Werte lesen: | Wert | Inhalt | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `trigger.data` | Die Entry-Daten, passend zum `data_schema` des Entry. | | `trigger.node_id` | Die ID des Entry, der diesen Visit gestartet hat. | | `trigger.type` | Der Typ des Entry, der diesen Visit gestartet hat, zum Beispiel `trigger.start_call`. | | `steps..output` | Ausgabe eines zuvor abgeschlossenen Node in diesem Visit. | | `variables.` | Werte, die ein `data.set`-Node in diesem Visit gespeichert hat. | | `execution.id`, `execution.started_at` | Die Ausführungs-ID und deren Startzeit. Verwenden Sie `string(execution.started_at)` in Sprachausgaben. | | `execution.call` | `id`, `session_id` des Anrufs sowie die ursprünglichen Parteien `orig` und `dest`, die jeweils `null` sein können. | Prüfen Sie optionale Werte, bevor Sie sie lesen, zum Beispiel `has(trigger.data.name) ? trigger.data.name : 'caller'`. Das Makro `has` ist verfügbar; `map`, `filter`, `all`, `exists` und `exists_one` sind es nicht. ## Entry ### `trigger.start_call` Hier beginnt ein Anruf. `entry_node_id` im Create-Call-Request benennt diesen Knoten. | Feld | Wert | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.data_schema` | Optionales JSON-Schema-Objektschema (Draft 2020-12) für `trigger_data`. Nur lokale `$ref` werden unterstützt. Ohne Angabe akzeptiert der Entry nur `{}`. | | Outcome | `event`. | Eingabedaten sind auf 16 KiB begrenzt. ## Sprache und Audio ### `voice.say` | Feld | Wert | | ---------------- | ---------------------------------------------------------------- | | `input.text` | Erforderlich, **binds**. Zu sprechender Text, maximal 160 Bytes. | | `input.language` | Erforderlich. Sprachcode für die Sprachausgabe, z. B. `en`. | | Outcome | `next`. | ### `voice.play` | Feld | Wert | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.asset_id` | Erforderlich. ID eines Audio-Assets, das in diesem Workspace verfügbar ist. Ein nicht verfügbares Asset kann den Anruf bei der Ausführung des Schritts fehlschlagen lassen. | | Ergebnis | `next`. | ### `voice.tone` | Feld | Wert | | -------------------- | ------------------------------- | | `input.frequency_hz` | Erforderlich. `100` bis `3000`. | | `input.duration_ms` | Erforderlich. `1` bis `10000`. | | Ergebnis | `next`. | ### `logic.pause` Wartet bei verbundenem Anruf. | Feld | Wert | | ------------------- | ------------------------------ | | `input.duration_ms` | Erforderlich. `1` bis `60000`. | | Ergebnis | `next`. | ## Tastatureingabe ### `voice.gather` Spielt Ansagen ab, die ein Tastendruck unterbricht, und sammelt Tastatureingaben. | Feld | Wert | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.prompts` | Erforderlich. Bis zu 4 Prompts. Jeder ist `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` oder `{"type": "pause", "duration_ms"}`, mit denselben Beschränkungen wie der entsprechende Node. Ton- und Pausendauer zusammen betragen höchstens 60.000 ms. Prompt `text` **binds**. | | `input.max_digits` | Erforderlich. `1` bis `32`. | | `input.timeout_seconds` | Erforderlich. Sekunden Wartezeit auf die erste Taste, `1` bis `10`. | | `input.inter_digit_timeout_seconds` | Erforderlich. Sekunden Wartezeit zwischen Tasten, `1` bis `5`. | | `input.finish_on_key` | Erforderlich. Eines von `0`–`9`, `*`, `#`, `A`–`D`, das die Eingabe beendet, oder `null`. | | `input.matches` | Erforderlich. Zuordnung von einem Outcome-Namen zu den exakten Ziffern, die ihn auswählen, z. B. `{"hours": "1"}`. Namen und Ziffern müssen eindeutig sein. Ein Name darf nicht `input`, `timeout` oder `fallback` sein. Ziffern sind höchstens `max_digits` lang und dürfen `finish_on_key` nicht enthalten. | | `input.private` | Optional, Standard `false`. Bei `true` können spätere Schritte die Ziffern nicht lesen, und sie werden im Trace weggelassen. | | Outcomes | Jeder Name in `matches`, `timeout` wenn keine Taste gedrückt wird, und `fallback` für jede andere Eingabe. | | Output | `digits` und `reason`: `initial_timeout`, `max_digits`, `finish_key` oder `inter_digit_timeout`. | ## Logik und Daten ### `logic.branch` Prüft Bedingungen der Reihe nach und folgt der ersten, die zutrifft. | Feld | Wert | | --------------------- | ---------------------------------------------------------------------------------- | | `config.cases` | Erforderlich. Mindestens ein `{"port": "", "when": {"$expr": ""}}`. | | `config.default_port` | Erforderlich. Outcome-Name, wenn kein Fall zutrifft. | | Outcomes | Jeder `port` in `cases` und `default_port`. | | Output | `branch`: der ausgewählte Outcome-Name. | ### `data.set` Speichert Werte für spätere Schritte im selben Visit. | Feld | Wert | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input` | Objekt mit Werten, von denen jeder **binds** unterstützt. Jeder Schlüssel wird zu `variables.`. Jeder Wert wird aus den Variablen berechnet, wie sie vor diesem Node waren. | | Outcome | `next`. | | Output | Das gespeicherte Objekt. | ## Anrufe und Weiterleitungen ### `voice.dial` Ruft eine andere Nummer an und verbindet sie mit dem aktuellen Anruf. | Feld | Wert | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input.to` | Erforderlich, **binds**. E.164-Nummer, z. B. `+12025550123`. | | `input.timeout_seconds` | Erforderlich, **expr**. Sekunden, die es klingelt, `1` bis `120`. | | Ergebnisse | `success`, `busy`, `no_answer` und `failure`. `success` folgt, nachdem der verbundene Anruf endet und das Audio des ursprünglichen Anrufs wiederhergestellt ist, nicht wenn das Ziel abnimmt. Ein nicht verbundenes `failure` lässt den Durchlauf fehlschlagen. | ### `logic.voice_goto` Startet einen weiteren Entry in derselben Definition. Der neue Visit erhält frische `trigger.data` und löscht die Ausgaben und Variablen vorheriger Schritte; der Anruf läuft weiter. | Feld | Wert | | --------------------- | ------------------------------------------------------------------------------ | | `input.entry_node_id` | Erforderlich. ID eines `trigger.start_call`-Knotens in dieser Definition. | | `input.data` | Optional, **expr**, Standard `{}`. Eingabedaten für das Schema dieses Knotens. | | Ergebnisse | Keine. | ## Anruf beenden ### `logic.exit` Beendet den Anruf mit einem Ergebnis. | Feld | Wert | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `config.status` | Erforderlich. `succeeded` oder `failed`. | | `config.reason` | Optional, **expr**. Stabiler Code aus Kleinbuchstaben, Ziffern und `_`, beginnend mit einem Buchstaben oder einer Ziffer, bis zu 64 Zeichen. Lassen Sie ihn weg, statt `null` zu senden. | | `input.output` | Erforderliches Objekt, das `{}` sein kann. Seine Werte auf oberster Ebene unterstützen **binds**. | | Outcomes | Keine. | ### `voice.hangup` Beendet den Anruf ohne ein verfasstes Ergebnis. Der Knoten hat keine Felder und keine Outcomes. ## Early-Access-Schritte `voice.webhook`, `voice.record_start`, `voice.record_stop` und `logic.voice_goto` mit `dependency_id` für verwaltete Voicemail oder Anrufaufzeichnung befinden sich im Early Access und sind hier nicht dokumentiert. Die Nutzung erfordert Zugang für Ihren Workspace. ## Beispiel: Weiterleitung an eine Person Diese Definition begrüßt den Empfänger, wählt eine Supportnummer und protokolliert, ob die Weiterleitung verbunden wurde: ```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": {} } } ] } ``` Senden Sie es als `sequence.definition` mit `"entry_node_id": "start"` und `"trigger_data": {}`. ## Related resources - [Voice sequences](/docs/guides/voice/sequence-builder) (docs)