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

Gebruik deze referentie om de sequence.definition te schrijven die je meestuurt met Oproep aanmaken. Bird voert een inline definitie eenmalig uit en slaat deze niet op. Wil je een sequence bewaren, maak deze dan in de dashboard-editor.

Definitie

Veld	Waarde
`schema_version`	`1`.
`expression_environment`	`"bird.cel.v1"`.
`nodes`	Array van node-objecten. De volgorde van de array heeft geen effect op de uitvoering.
`settings`	Laat het weg of stuur `{}`. Een niet-leeg object geeft `unsupported_contract`; een waarde die geen object is, geeft `invalid_envelope`.
`presentation`	Optionele editorindeling en labels. Heeft geen effect op de uitvoering, maar telt mee voor de maximale grootte.

Elke node heeft deze velden:

Veld	Waarde
`id`	Uniek binnen de definitie. Begint met een kleine letter, daarna kleine letters, cijfers of `_`, maximaal 64 tekens.
`type`	Een nodetype van deze pagina, zoals `voice.say`.
`type_version`	`1` voor elk knooppunttype op deze pagina.
`config`	Configuratie die de vorm van het knooppunt vastlegt, zoals gedeclareerde outcomes. Gebruik `{}` als het knooppunt er geen heeft.
`input`	Waarden die het knooppunt gebruikt bij uitvoering. Gebruik `{}` als het knooppunt er geen heeft.
`connections`	Map van een outcome-naam naar `{ "node_id": "<target>", "port": "input" }`.

Verbindingen mogen geen lus vormen en elk knooppunt moet bereikbaar zijn vanuit een entry. Een outcome die niet in connections staat, is niet verbonden. Niet-verbonden outcomes beëindigen de run normaal, tenzij een knooppunt anders aangeeft.

Waarden en expressies

De meeste velden accepteren letterlijke JSON. Velden met binds accepteren ook $expr of $template; velden met expr accepteren alleen $expr:

{"$expr": "trigger.data.customer_name"} retourneert een getypeerde waarde.
{"$template": ["Hello ", {"$expr": "trigger.data.customer_name"}, "."]} geeft tekst terug. Templates zijn arrays; {{name}} blijft letterlijke tekst.

Expressies gebruiken CEL en kunnen deze waarden lezen:

Waarde	Inhoud
`trigger.data`	De entry-data, overeenkomend met het `data_schema` van de entry.
`trigger.node_id`	Het ID van de entry die dit bezoek heeft gestart.
`trigger.type`	Het type van de entry die dit bezoek heeft gestart, zoals `trigger.start_call`.
`steps.<id>.output`	Output van een eerder voltooide node in dit bezoek.
`variables.<key>`	Waarden opgeslagen door een `data.set`-node in dit bezoek.
`execution.id`, `execution.started_at`	Het run-ID en de starttijd ervan. Gebruik `string(execution.started_at)` in spraak.
`execution.call`	De `id`, `session_id` van het gesprek en de oorspronkelijke partijen `orig` en `dest`, die elk `null` kunnen zijn.

Controleer optionele waarden voordat je ze uitleest, bijvoorbeeld has(trigger.data.name) ? trigger.data.name : 'caller'. De macro has is beschikbaar; map, filter, all, exists en exists_one niet.

Entry

`trigger.start_call`

Waar een gesprek begint. entry_node_id in het Create Call-verzoek benoemt dit knooppunt.

Veld	Waarde
`config.data_schema`	Optioneel JSON Schema (draft 2020-12) objectschema voor `trigger_data`. Alleen lokale `$ref` wordt ondersteund. Zonder dit schema accepteert de entry alleen `{}`.
Outcome	`event`.

Entry-data is beperkt tot 16 KiB.

Spraak en audio

`voice.say`

Veld	Waarde
`input.text`	Vereist, binds. Uit te spreken tekst, maximaal 160 bytes.
`input.language`	Vereist. Taalcode voor spraak, zoals `en`.
Outcome	`next`.

`voice.play`

Veld	Waarde
`input.asset_id`	Vereist. ID van een audio-asset dat beschikbaar is in deze werkruimte. Een niet-beschikbaar asset kan het gesprek laten mislukken wanneer de stap wordt uitgevoerd.
Uitkomst	`next`.

`voice.tone`

Veld	Waarde
`input.frequency_hz`	Vereist. `100` tot `3000`.
`input.duration_ms`	Vereist. `1` tot `10000`.
Outcome	`next`.

`logic.pause`

Wacht terwijl het gesprek verbonden is.

Veld	Waarde
`input.duration_ms`	Vereist. `1` tot `60000`.
Outcome	`next`.

Toetsenbordinvoer

`voice.gather`

Speelt prompts af, die door een toetsdruk worden onderbroken, en verzamelt toetsenbordcijfers.

Veld	Waarde
`input.prompts`	Vereist. Maximaal 4 prompts. Elk is `{"type": "say", "text", "language"}`, `{"type": "play", "asset_id"}`, `{"type": "tone", "frequency_hz", "duration_ms"}` of `{"type": "pause", "duration_ms"}`, met dezelfde limieten als de bijbehorende node. De duur van tonen en pauzes samen is maximaal 60.000 ms. Prompt `text` bindt.
`input.max_digits`	Vereist. `1` tot `32`.
`input.timeout_seconds`	Vereist. Seconden wachten op de eerste toets, `1` tot `10`.
`input.inter_digit_timeout_seconds`	Vereist. Seconden wachten tussen toetsen, `1` tot `5`.
`input.finish_on_key`	Vereist. Een van `0`–`9`, `*`, `#`, `A`–`D` die de invoer beëindigt, of `null`.
`input.matches`	Vereist. Map van een outcome-naam naar de exacte cijfers die deze selecteren, zoals `{"hours": "1"}`. Namen en cijfers moeten uniek zijn. Een naam kan niet `input`, `timeout` of `fallback` zijn. Cijfers zijn maximaal `max_digits` lang en mogen geen `finish_on_key` bevatten.
`input.private`	Optioneel, standaard `false`. Bij `true` kunnen latere stappen de cijfers niet lezen en worden ze weggelaten uit de trace.
Outcomes	Elke naam in `matches`, `timeout` wanneer er geen toets wordt ingedrukt, en `fallback` voor alle andere invoer.
Output	`digits` en `reason`: `initial_timeout`, `max_digits`, `finish_key` of `inter_digit_timeout`.

Logica en data

`logic.branch`

Controleert voorwaarden op volgorde en volgt de eerste die waar is.

Veld	Waarde
`config.cases`	Vereist. Minimaal één `{"port": "<name>", "when": {"$expr": "<boolean>"}}`.
`config.default_port`	Vereist. Naam van de outcome wanneer geen case waar is.
Outcomes	Elke `port` in `cases`, en `default_port`.
Output	`branch`: de geselecteerde outcome-naam.

`data.set`

Slaat waarden op voor latere stappen in hetzelfde bezoek.

Veld	Waarde
`input`	Object met waarden, die elk binds. Elke sleutel wordt `variables.<key>`. Elke waarde wordt berekend op basis van de variabelen zoals ze waren vóór dit knooppunt.
Outcome	`next`.
Output	Het opgeslagen object.

Gesprekken en doorverbindingen

`voice.dial`

Belt een ander nummer en verbindt het met het huidige gesprek.

Veld	Waarde
`input.to`	Vereist, binds. E.164-nummer, zoals `+12025550123`.
`input.timeout_seconds`	Vereist, expr. Aantal seconden overgaan, `1` tot `120`.
Uitkomsten	`success`, `busy`, `no_answer` en `failure`. `success` volgt nadat het verbonden gesprek is beëindigd en de audio van het oorspronkelijke gesprek is hersteld, niet wanneer de bestemming opneemt. Een niet-verbonden `failure` laat de run mislukken.

`logic.voice_goto`

Start een nieuwe entry in dezelfde definitie. Het nieuwe bezoek krijgt verse trigger.data en wist eerdere stapuitvoer en variabelen; het gesprek gaat door.

Veld	Waarde
`input.entry_node_id`	Vereist. ID van een `trigger.start_call`-node in deze definitie.
`input.data`	Optioneel, expr, standaard `{}`. Invoergegevens voor het schema van die node.
Uitkomsten	Geen.

Het gesprek beëindigen

`logic.exit`

Beëindigt het gesprek met een resultaat.

Veld	Waarde
`config.status`	Vereist. `succeeded` of `failed`.
`config.reason`	Optioneel, expr. Stabiele code van kleine letters, cijfers en `_`, beginnend met een letter of cijfer, maximaal 64 tekens. Laat het weg in plaats van `null` te sturen.
`input.output`	Vereist object, dat `{}` kan zijn. De waarden op het hoogste niveau ondersteunen binds.
Outcomes	Geen.

`voice.hangup`

Beëindigt het gesprek zonder een opgesteld resultaat. Het heeft geen velden en geen uitkomsten.

Stappen in early access

voice.webhook, voice.record_start, voice.record_stop en logic.voice_goto met dependency_id voor beheerde voicemail of gespreksopname zijn in early access en worden hier niet beschreven. Om ze te gebruiken heb je toegang nodig voor je werkruimte.

Voorbeeld: doorverbinden naar een persoon

Deze definitie begroet de ontvanger, belt een supportnummer en registreert of de doorverbinding is gelukt:

Codevoorbeeld

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

Verstuur het als sequence.definition met "entry_node_id": "start" en "trigger_data": {}.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Voice sequences

Gerelateerde bronnen