sinch.domains.voice.helpers.v2.svaml.menu module

class sinch.domains.voice.helpers.v2.svaml.menu.Menu[source]

Bases: object

Helpers to build the menu SVAML commands.

static create(
name: str,
item: NamedMenuItemDict,
*items: NamedMenuItemDict,
) → MenuCommandDict[source]

Defines a set of named menus and executes them starting from name. This is a blocking command — execution waits for the menu to complete before proceeding to the next command.

Each menu item configures prompts, input collection, timeout handling, and repeat behavior.

Parameters:

  • name (str) – Name of the menu to execute first, between 1 and 16 characters. Must match the name of one of the menu items.

  • item (NamedMenuItemDict) – First menu definition, built with item().

  • items (NamedMenuItemDict) – Further menu definitions. Menu names must be unique.

Returns:

The menu command.

Return type:

MenuCommandDict

Raises:

ValueError – If a menu name is duplicated, or if name or the target of a goto() is not one of the menu items.

static item(
name: str,
*,
prompt: MenuPromptDict | Unset = <sinch.core.sentinel.Unset object>,
repeat_prompt: MenuPromptDict | Unset = <sinch.core.sentinel.Unset object>,
input_timeout_duration_seconds: int | Unset = <sinch.core.sentinel.Unset object>,
repeat_count: int | Unset = <sinch.core.sentinel.Unset object>,
minimum_input_length: int | Unset = <sinch.core.sentinel.Unset object>,
maximum_input_length: int | Unset = <sinch.core.sentinel.Unset object>,
terminating_sequence: str | Unset = <sinch.core.sentinel.Unset object>,
input_methods: List[Literal['DTMF'] | str] | Unset = <sinch.core.sentinel.Unset object>,
matches: Mapping[str,
~collections.abc.Sequence[~sinch.domains.voice.models.v2.svaml.types.amd_command_dict.AmdCommandDict | ~sinch.domains.voice.models.v2.svaml.types.dial_command_dict.DialCommandDict | ~sinch.domains.voice.models.v2.svaml.types.messages_command_dict.MessagesCommandDict | ~sinch.domains.voice.models.v2.svaml.types.stop_messages_command_dict.StopMessagesCommandDict | ~sinch.domains.voice.models.v2.svaml.types.custom_event_command_dict.CustomEventCommandDict | ~sinch.domains.voice.models.v2.svaml.types.hangup_command_dict.HangupCommandDict | ~sinch.domains.voice.models.v2.svaml.types.answer_command_dict.AnswerCommandDict | ~sinch.domains.voice.models.v2.svaml.types.pause_command_dict.PauseCommandDict | ~sinch.domains.voice.models.v2.svaml.types.start_recording_command_dict.StartRecordingCommandDict | ~sinch.domains.voice.models.v2.svaml.types.stop_recording_command_dict.StopRecordingCommandDict | ~sinch.domains.voice.models.v2.svaml.types.bridge_call_command_dict.BridgeCallCommandDict | ~sinch.domains.voice.models.v2.svaml.types.menu_command_dict.MenuCommandDict | ~sinch.domains.voice.models.v2.svaml.types.goto_menu_command_dict.GotoMenuCommandDict]] | ~sinch.core.sentinel.Unset=<sinch.core.sentinel.Unset object>,
on_failure: AmdCommandDict | DialCommandDict | MessagesCommandDict | StopMessagesCommandDict | CustomEventCommandDict | HangupCommandDict | AnswerCommandDict | PauseCommandDict | StartRecordingCommandDict | StopRecordingCommandDict | BridgeCallCommandDict | MenuCommandDict | GotoMenuCommandDict | Sequence[AmdCommandDict | DialCommandDict | MessagesCommandDict | StopMessagesCommandDict | CustomEventCommandDict | HangupCommandDict | AnswerCommandDict | PauseCommandDict | StartRecordingCommandDict | StopRecordingCommandDict | BridgeCallCommandDict | MenuCommandDict | GotoMenuCommandDict] | Unset = <sinch.core.sentinel.Unset object>,
) → NamedMenuItemDict[source]

Defines a single menu step, including prompts, input handling rules, input-to-command matches, and failure handling.

Each collected input is matched against the values in matches. If no match succeeds, the on_failure commands are executed.

If no match succeeds and on_failure is not defined, a call.menu event including the collected input is sent to the event destination when the service call behavior is EVENT_DESTINATION.

Parameters:

  • name (str) – Name of the menu, between 1 and 16 characters. Used as the start menu in create() and as the target of goto().

  • prompt (UnsetOr[MenuPromptDict]) – Prompt played when this menu starts. This prompt is also used as the repeat prompt when repeat_prompt is not defined for the menu.

  • repeat_prompt (UnsetOr[MenuPromptDict]) – Prompt played when the menu is repeated. Repeats occur when input times out or when the provided input does not match any menu match item.

  • input_timeout_duration_seconds (UnsetOr[int]) – Maximum number of seconds to wait for user input before the input attempt times out, between 1 and 60. Defaults to 5.

  • repeat_count (UnsetOr[int]) – Maximum number of times the menu is repeated, between 0 and 10. A repeat occurs when input times out or when the provided input does not match any menu match item. Defaults to 2.

  • minimum_input_length (UnsetOr[int]) – Minimum number of input characters required before the menu evaluates the collected input, between 1 and 100. Defaults to 1.

  • maximum_input_length (UnsetOr[int]) – Maximum number of input characters that triggers the menu to evaluate the collected input, between 1 and 100. Defaults to 1.

  • terminating_sequence (UnsetOr[str]) – Character sequence that signals the end of input and triggers immediate evaluation, at most 10 characters, matching ^[0-9*#]+$. Useful when variable-length input is allowed and shorter valid options should be submitted without waiting for timeout or maximum length. The terminating sequence value is included in the evaluated input.

  • input_methods (UnsetOr[List[Union[Literal["DTMF"], str]]]) –

    Input methods accepted for this menu when collecting user input. Defaults to ["DTMF"].

    • DTMF: Collect input from keypad tones (Dual-Tone Multi-Frequency).

  • matches (UnsetOr[Mapping[str, Sequence[SvamlCommandDict]]]) – Items matched against the collected input, at most 50. Each key is a literal or a regular expression string, between 1 and 256 characters, and its value is the SVAML commands to execute. Keys are evaluated sequentially in the order defined; the first key that matches the input triggers its commands. Use \* to match the DTMF star tone (*).

  • on_failure (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands executed when the menu fails to collect a matching input. This handler runs after the repeat limit is reached without any input matching a menu match item.

Returns:

The named menu item.

Return type:

NamedMenuItemDict

static prompt(
message: SayMessageDict | PlayMessageDict,
*messages: SayMessageDict | PlayMessageDict,
allow_barge_in: bool | Unset = <sinch.core.sentinel.Unset object>,
) → MenuPromptDict[source]

Prompt configuration for menu playback, including prompt messages and barge-in behavior.

Parameters:

  • message (MessageDict) – First message to play, built with Messages.text(), Messages.ssml() or Messages.play().

  • messages (MessageDict) – Further messages to play in order, up to 10 messages in total.

  • allow_barge_in (UnsetOr[bool]) – Controls whether input can interrupt prompt playback. When enabled, playback stops as soon as input is detected and the input is evaluated immediately if matching conditions are met. When disabled, input is still collected during playback and evaluated after playback finishes. Defaults to True.

Returns:

The menu prompt.

Return type:

MenuPromptDict

static goto(
name: str,
) → GotoMenuCommandDict[source]

Switches execution to another menu within the current menu context. The menu name must be a menu defined in the menu command. This is a blocking command — execution waits for the menu to complete before proceeding to the next command.

This command can only be used within a menu execution context, in the matches or on_failure of a item().

Parameters:

name (str) – Name of the target menu to execute next, between 1 and 16 characters. Must match the name of one of the items of the menu.

Returns:

The gotoMenu command.

Return type:

GotoMenuCommandDict