sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator module

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.CommandsSequenceCreator[source]

Immutable fluent creator of a sequence of SVAML commands.

Each method takes the same parameters as the matching helper and returns a new creator with the command appended, so a creator can be reused as the prefix of several sequences.

A creator is a sequence of commands, so it can be passed wherever a sequence of commands is expected, such as commands or the on_* handlers, without calling build().

Appends a command, such as one built with a helper or by hand.

Parameters:: command (SvamlCommandDict) – The command to append.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

Returns the commands as a list.

Returns:: The commands, in order.
Return type:: List[SvamlCommandDict]
Raises:: ValueError – If the start menu of a menu command or the target of one of its gotoMenu commands is not one of its menus.

answer

Answers an inbound call leg. This is a non-blocking command — execution continues to the next command in the sequence immediately after the answer is initiated.

Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

bridge_call

Adds the current call to a bridge, enabling bidirectional audio communication with other calls in the same session. This is a non-blocking command — execution continues to the next command in the sequence immediately after the call joins the bridge.

Bridges are created automatically when referenced by name. If a bridge with the specified name already exists, the call joins that bridge; otherwise, a new bridge is created.

Parameters:: name (str) – Name of the bridge to join. If no bridge with this name exists in the session, a new one is created automatically.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

dial

Initiates a new outbound call leg within the current session.

This is a non-blocking command — the next command in the sequence executes immediately while the call is being established in parallel. Call lifecycle events (answer, busy, reject, timeout, hangup, failure) are handled via the events property.

The from and to endpoint types should ideally match. If they differ, the platform attempts to convert the from value to be compatible with the to type. For example, PSTN supports only E.164 phone numbers, so a SIP address such as sip:46701234567@acme.se can be converted to an E.164 number. If the from value cannot be converted, it defaults to null (anonymous).

Parameters:

to (Union[str, BaseCallDestinationDict, CallDestinationDict]) – Call destination: a phone number in E.164 format, a SIP URI, a WebSocket endpoint for real-time audio streaming or the Voice Relay service for real-time speech-to-text and text-to-speech. A string is parsed with Destination.of().
from (UnsetOr[Union[str, BaseCallDestinationDict, CallOriginDict]]) – Call origin: a phone number in E.164 format or a SIP URI. A string is parsed with Destination.of().
name (UnsetOr[str]) – Identifier for this call leg within the session. Must be unique across all active call legs in the session. Other commands (e.g., hangup) can reference this name to target this specific leg.
timeout_duration_seconds (UnsetOr[int]) – Maximum time in seconds to wait for the call to be answered. If the timeout expires without an answer, the onTimeout event is triggered.
max_duration_seconds (UnsetOr[int]) – Maximum duration of the call in seconds. The call is terminated automatically when this limit is reached.
on_answer (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call is answered.
on_busy (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call is busy.
on_reject (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call is rejected.
on_timeout (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call is timed out.
on_hangup (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call is hung up.
on_failure (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when the call fails.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

hangup

Ends a call leg. This is a non-blocking command — execution continues to the next command in the sequence even though the call has been ended. The onHangup event is triggered for the call leg that was ended.

Any subsequent commands that target the ended call leg (such as messages or other media commands) are valid but will not be executed. Commands that operate independently — such as initiating a new call with dial — will execute normally. This makes it possible, for example, to end one call and immediately start another within the same sequence.

Parameters:: name (UnsetOr[str]) – Name of the call leg to end, as set by callName in the dial command. If omitted, the current call leg is ended.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

pause

Delays execution of the next command in the sequence for a specified duration. This is a blocking command — no further commands execute until the pause completes.

The pause does not affect call audio; the call remains connected and audio continues uninterrupted.

Parameters:: duration_milliseconds (int) – Duration of the pause in milliseconds.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

amd

AMD (Answering Machine Detection) command to detect what answered the call. Possible outcomes are: human, machine, beep, or unknown.

This is a non-blocking command — the next command in the sequence executes immediately while detection runs in parallel. Results are delivered via events, which defines different call flows depending on whether a human, machine, beep, or unknown entity answers the call.

Parameters:

on_human (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when a human is detected.
on_machine (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when a machine is detected.
on_beep (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when a beep is detected.
on_unknown (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to be executed when an unknown event is detected.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

custom_events

Triggers a mid-call event to the application backend, allowing it to return a new set of SVAML commands that control the remainder of the call flow.

This is a blocking command — execution pauses until a response is received from the event destination. The next command in the sequence runs only after the backend responds. Event requests use a 5-second timeout. If fallback_url is provided, a failed request is re-sent to it.

Parameters:

name (str) – Name for this custom event, between 1 and 64 characters, matching ^\S+$. When triggered, the event request’s event property contains this name prepended with call.customEvent..
url (str) – URL of the event destination to send the mid-call event to.
fallback_url (UnsetOr[str]) – Fallback URL used when the primary URL fails. A failed request is re-sent to this URL immediately. After repeated consecutive failures of the primary URL, requests are sent only here until the primary URL recovers.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

messages

Plays one or more messages on the call, sequentially in order. The messages are added right after with text, ssml and play, which add to this command until another method is called. Between 1 and 10 messages are required.

This is a non-blocking command — the next command in the sequence executes immediately while messages play in parallel.

Parameters:

name (UnsetOr[str]) – Name of the message sequence, between 1 and 32 characters, matching ^\S+$. Must be unique within the current call session. Can be referenced by stop_messages() to control this specific message sequence.
on_finish (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to execute when all messages in the sequence have finished playing.

Returns:

A new creator with the command appended.

Return type:

OpenMessagesStep

stop_messages

Stops a message sequence started by start(). It also cancels any messages with the same name that appear in the call session in the future.

This is a non-blocking command.

Parameters:: name (str) – Name of the message sequence to stop, as set by name in start(). Between 1 and 32 characters, matching ^\S+$.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

text

Plays a single text-to-speech message on the call. Shortcut for messages() with one Messages.text() message.

Parameters:

text (str) – The plain text to be synthesized into speech, at most 600 characters.
voice_name (Union[VoiceNameEnum, VoiceName]) – The name of the voice to use for text-to-speech synthesis. Use VoiceNameEnum to browse voices with their language, gender and pricing, or VoiceNameByLanguageEnum to browse them grouped by language.
name (UnsetOr[str]) – Name of the message sequence, between 1 and 32 characters, matching ^\S+$. Must be unique within the current call session. Can be referenced by stop_messages() to control this specific message sequence.
on_finish (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to execute when the message has finished playing.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

play

Plays a single audio file on the call. Shortcut for messages() with one Messages.play() message.

Parameters:

url (str) – URL of the media to play.
name (UnsetOr[str]) – Name of the message sequence, between 1 and 32 characters, matching ^\S+$. Must be unique within the current call session. Can be referenced by stop_messages() to control this specific message sequence.
on_finish (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – SVAML commands to execute when the message has finished playing.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

recording

Starts recording the call. This is a non-blocking command — execution continues to the next command in the sequence immediately after recording begins.

Parameters:

options (RecordingOptionsDict) – Recording options for this recording, built with options().
name (UnsetOr[str]) – Identifier for this recording within the session, between 1 and 32 characters, matching ^\S+$. Must be unique across active recordings in the session. Setting the recording name is useful for stopping the recording with stop(). If name is not set, recording can only be stopped when the call is disconnected.
on_finish (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – Commands to execute when the recording is successfully stopped. Note that this does not mean that the file is delivered to the configured destination yet.
on_failure (UnsetOr[Union[SvamlCommandDict, Sequence[SvamlCommandDict]]]) – Commands to execute if the recording fails to start. If omitted, failures are silently ignored and the call flow continues.

Returns:

A new creator with the command appended.

Return type:

CommandsSequenceCreator

stop_recording

Stops a recording previously started by start(). This is a non-blocking command — execution continues to the next command in the sequence immediately after the stop is initiated.

Parameters:: name (str) – Name of the recording to stop, as set by name in start(). Between 1 and 32 characters, matching ^\S+$.
Returns:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

menu

Defines a set of named menus and executes them starting from name. The menus are added right after with item. At least one menu is required.

This is a blocking command — execution waits for the menu to complete before proceeding to the next command.

Parameters:: name (str) – Name of the menu to execute first, between 1 and 16 characters. Must match the name of one of the menus.
Returns:: A new creator with the command appended.
Return type:: OpenMenuStep

goto_menu

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:: A new creator with the command appended.
Return type:: CommandsSequenceCreator

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.OpenMessagesStep[source]

Bases: _MessagesContent, CommandsHolder

Returned by messages. Not a sequence of commands yet: the command needs a first message, added with text, ssml or play.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.MessagesStep[source]

Bases: _MessagesContent, CommandsSequenceCreator

Creator whose text, ssml and play add a message to the messages command instead of appending a new command.

Any other method continues the sequence with a new command.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.OpenMenuStep[source]

Bases: _MenuContent, _MenuScope

Returned by menu. Not a sequence of commands yet: the command needs a first menu, added with item.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.MenuItemStep[source]

Bases: _MenuContent, _MenuScope, CommandsSequenceCreator

Creator whose prompt and repeat_prompt set the prompts of the last menu, and whose item adds another menu to the menu command.

Any other method continues the sequence with a new command, once the start menu and the gotoMenu targets of the command are checked.

prompt

Sets a prompt of the menu: the one played when the menu starts (prompt), also used when the menu is repeated unless the one for repeats (repeat_prompt) is set. The messages are added right after with text, ssml and play. Between 1 and 10 messages are required.

Parameters:: 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:: A new creator with the prompt set.
Return type:: OpenPromptStep

repeat_prompt

Sets a prompt of the menu: the one played when the menu starts (prompt), also used when the menu is repeated unless the one for repeats (repeat_prompt) is set. The messages are added right after with text, ssml and play. Between 1 and 10 messages are required.

Parameters:: 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:: A new creator with the repeat prompt set.
Return type:: OpenRepeatPromptStep

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.OpenPromptStep[source]

Bases: _PromptContent, _MenuScope

Returned by prompt. Not a sequence of commands yet: the prompt needs a first message, added with text, ssml or play.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.PromptStep[source]

Bases: _PromptContent, MenuItemStep

Creator whose text, ssml and play add a message to the prompt instead of appending a new command.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.OpenRepeatPromptStep[source]

Bases: _RepeatPromptContent, _MenuScope

Returned by repeat_prompt. Not a sequence of commands yet: the prompt needs a first message, added with text, ssml or play.

class sinch.domains.voice.helpers.v2.svaml.commands_sequence_creator.RepeatPromptStep[source]

Bases: _RepeatPromptContent, MenuItemStep

Creator whose text, ssml and play add a message to the repeat prompt instead of appending a new command.