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 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.

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": "<target>", "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.<id>.output`	Ausgabe eines zuvor abgeschlossenen Node in diesem Visit.
`variables.<key>`	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": "<name>", "when": {"$expr": "<boolean>"}}`.
`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.<key>`. 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:

Codebeispiel

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

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Voice sequences

Verwandte Ressourcen