Referentie voor voice-sequence-nodes

Waarschuwing: Voice-sequences zijn in preview. Stappen, entry-data en het formaat van de sequencedefinitie kunnen veranderen op manieren die bestaande sequences en API-verzoeken breken.

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 nodetype op deze pagina, behalve `3` voor `voice.dial`.
`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 verzoek Oproep aanmaken benoemt deze node.

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.
Outcome	`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` binds.
`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 ondersteunen. Elke sleutel wordt `variables.<key>`. Elke waarde wordt berekend op basis van de variabelen zoals ze waren vóór deze node.
Outcome	`next`.
Output	Het opgeslagen object.

Gesprekken en doorverbindingen

`voice.dial`

Belt een telefoonnummer of een nummer op een van de inkomende SIP-trunks van je werkruimte, of laat een belgroep overgaan, en verbindt dit met het huidige gesprek. Gebruik type_version 3.

Veld	Waarde
`input.type`	Vereist. `pstn` om een telefoonnummer te bellen, `sip_trunk` om een nummer te bellen via een van je inkomende SIP-trunks, of `ring_group` om de online leden van een belgroep te laten overgaan.
`input.pstn`	Vereist als `type` `pstn` is, en anders weggelaten. Object met `dest` en optioneel `orig`.
`input.sip_trunk`	Vereist als `type` `sip_trunk` is, en anders weggelaten. Object met `trunk_id`, `dest` en optioneel `orig`.
`input.ring_group`	Vereist wanneer `type` `ring_group` is, en anders weggelaten. Object met `ring_group_id`.
`trunk_id`	Vereist in `sip_trunk`. ID van een inkomende SIP-trunk in je werkruimte, zoals `spt_01jzj6c0p4f8b3x2m9k7q5r1tw`. Alleen een letterlijke waarde.
`ring_group_id`	Vereist in `ring_group`. ID van een belgroep in je werkruimte, inclusief de standaardgroep, zoals `vrg_01jzj6c0p4f8b3x2m9k7q5r1tw`. Alleen een letterlijke waarde.
`dest`	Vereist, binds. Voor `pstn` het E.164-nummer dat je belt, zoals `+12025550123`. Voor `sip_trunk` een nummer, extensie of naam, zoals `1001`: 1 tot 64 letters, cijfers en `+*._-`. De inkomende routering van de trunk levert het gesprek af alsof het voor deze waarde binnenkwam.
`orig`	Optioneel, binds. Als je de eigenschap `orig` weglaat, toont het gesprek het Bird-nummer dat bij een inkomend gesprek is gekozen, of het oorspronkelijke nummer bij een uitgaand gesprek. Gebruik voor `pstn` een nummerweergave van de werkruimte of het E.164-nummer van de geldige inkomende beller. Nummers van inkomende bellers worden zonder ondertekening verstuurd en kunnen door de ontvangende provider worden gefilterd. Voor `sip_trunk` accepteert het dezelfde waarden als `dest`, zoals `sales`.
`input.timeout_seconds`	Vereist voor `pstn` en `sip_trunk`, en weggelaten voor `ring_group`, expr. Aantal seconden wachten op een antwoord, inclusief failover tussen trunkgateways, `1` tot `120`. Onbeantwoorde gesprekken volgen `no_answer`; een beantwoord gesprek is niet beperkt.
Outcomes	`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 SIP-trunk die het gesprek weigert of doorstuurt, selecteert `failure`. Een niet-verbonden `failure` laat de run mislukken. Bij een ring group betekent `busy` dat de leden bezet waren, weigerden of in een ander gesprek zaten, `no_answer` dat niemand binnen 60 seconden opnam of niemand online was, en `failure` dat Bird de groep niet kon laten overgaan.

Versie 2 heeft geen ring_group-doel en vereist altijd timeout_seconds. Elke invoer van versie 2 is ook geldig in versie 3, dus als je een stap upgradet, verandert er verder niets.

Versie 1 neemt het nummer in input.to en heeft geen orig. Stappen die deze versie gebruiken, blijven werken. Als je een stap van versie 1 in de editor upgradet, verhuist de waarde van to naar pstn.dest.

`logic.voice_goto`

Start een andere 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 `{}`. Entry-data voor het schema van die node.
Outcomes	Geen.

Automations

`automation.send_event`

Stuurt een applicatie-event naar een Automation zonder op een run te wachten. Het gesprek gaat door zodra het event in de wachtrij staat; of er een run start, zie je alleen in Automations.

Veld	Waarde
`input.automation_id`	Vereist. ID van een automation in deze werkruimte.
`input.event`	Vereist. De eventnaam van de automation: 1 tot 128 letters, cijfers, punten, underscores of koppeltekens.
`input.data`	Optioneel, standaard `{}`. De volledige data van het event. De waarden op het hoogste niveau ondersteunen binds, of het hele object kan één `$expr` zijn. Dieper geneste waarden blijven letterlijk. De hele `input` is maximaal 16 KiB.
Outcomes	`success` zodra het event in de wachtrij staat, of `failure` als dat niet lukt. Geen van beide meldt de run van de automation. Een niet-verbonden `failure` laat de run mislukken.

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 accepteren binds.
Outcomes	Geen.

`voice.hangup`

Beëindigt het gesprek zonder een zelf opgegeven resultaat. Het heeft geen velden en geen outcomes.

Zie Applicatiedata gebruiken in een voice-sequence voor voice.webhook.

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": 3,
      "config": {},
      "input": { "type": "pstn", "pstn": { "dest": "+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