ACS Module

Run automated phone calls on Azure Communication Services with TTS prompts and DTMF capture.

The ACS Module drives outbound and inbound voice calls through Azure Communication Services Call Automation. Each call step on the AcsPhone Channel — starting the call, speaking a synthesized message, collecting a keypad digit, and hanging up — is handled by this Module, so you can build IVR menus, outbound notifications, and voice surveys in the same BPMN editor you use for chat and Slack workflows. It requires Environment configuration: an Azure Communication Services connection and a text-to-speech provider (Azure Speech or OpenAI).

How it works

When a call is started or received on the AcsPhone Channel, the engine creates a Session and starts a Token through the Process. The live call stays bound to the Session for its entire lifetime, so every Task can address it.

At the Start Event the Module records the call details on the Session and writes the Module's Default Language into the Language Session variable so downstream Tasks pick it up. Each OutputTask converts its message to speech through the configured TTS provider and plays the audio over the call. Each InputTask speaks a prompt and then listens for a keypad (DTMF) digit — the caller's digit is written into the configured variable when it arrives. At the End Event the Module hangs up the call.

If a Session ends abnormally before reaching the End Event, the Module automatically hangs up the dangling call so the Azure connection does not stay open and keep billing. No configuration is needed to enable this behavior.

Configuration

The ACS Module is configured per Environment — each Environment supplies its own Azure Communication Services credentials and TTS settings. Set these values in the Module's Environment configuration. The connection settings are required to reach Azure Communication Services; the Text-to-Speech settings select how prompts are synthesized.

Field	Type	Required	Description
ACS Connection String	string	Yes*	Azure Communication Services connection string (endpoint=https://...;accesskey=...).
ACS Endpoint	string	Yes*	Azure Communication Services endpoint URL (e.g. https://myacs.communication.azure.com). Used when no connection string is provided.
ACS Access Key	string	Yes*	Azure Communication Services access key. Used together with the ACS Endpoint.
Callback Base URL	string	Yes	Base URL where Azure Communication Services delivers call event notifications (e.g. https://myapp.azurewebsites.net).
Default Language	string	No	Default language for call interactions. One of it-IT, en-US, en-GB, de-DE, fr-FR, es-ES. Default: it-IT.
Timeout Message	string	No	Message played when the caller does not respond in time. Supports {variable} placeholders. Default: Non ho ricevuto risposta. Riprova più tardi.
Invalid Input Message	string	No	Message played when the caller provides invalid input. Supports {variable} placeholders. Default: Input non valido. Riprova.
Goodbye Message	string	No	Message played when the call ends. Supports {variable} placeholders. Default: Grazie per aver chiamato. Arrivederci.
Max Call Duration (seconds)	integer	No	Maximum allowed call duration before automatic hangup (60–7200). Default: 1800.
Enable Call Recording	boolean	No	When enabled, calls are recorded and stored in blob storage. Default: off.
Webhook Shared Secret	string	No	Shared secret used to verify the signature of incoming call event notifications. Notifications that fail the check are rejected, so configure the same secret on the system that sends them. Default: empty.
Audio SAS TTL (seconds)	integer	No	How long (in seconds) a synthesized audio link stays valid for playback on the call (60–3600). Keep it short to limit exposure if the link leaks. Default: 900.
TTS Provider	string	Yes	Text-to-speech engine. One of Azure or OpenAI. Default: Azure.
Azure Speech Endpoint	string	No	Azure Cognitive Services Speech endpoint URL (e.g. https://italynorth.api.cognitive.microsoft.com). Required when TTS Provider is Azure.
Azure Speech Key	string	No	Azure Cognitive Services Speech subscription key. Required when TTS Provider is Azure.
Azure Speech Region	string	No	Azure region where the Speech resource is deployed. Default: italynorth.
Default Voice	string	No	Default neural voice (e.g. it-IT-ElsaNeural, en-US-JennyNeural). Default: it-IT-ElsaNeural.
Audio Format	string	No	PCM audio format for synthesized speech. One of Riff24Khz16BitMonoPcm, Riff16Khz16BitMonoPcm, Riff8Khz16BitMonoPcm. Default: Riff16Khz16BitMonoPcm.
OpenAI API Key	string	No	OpenAI API key (sk-...). Required when TTS Provider is OpenAI.
Model	string	No	OpenAI TTS model. One of tts-1, tts-1-hd (tts-1-hd offers higher quality). Default: tts-1.
Voice	string	No	Voice persona. One of alloy, echo, fable, onyx, nova, shimmer. Default: nova.
Speed	number	No	Playback speed multiplier (0.25–4.0). Default: 1.0.
Blob Storage Connection String	string	No	Azure Blob Storage connection string used to store synthesized audio files.
Audio Container Name	string	No	Blob container name for synthesized audio files. Default: acs-audio.

* Provide either the ACS Connection String or the pair ACS Endpoint + ACS Access Key.

warning

The Module refuses to execute any Task unless at least one credential path is filled in. If both the ACS Connection String and the ACS Endpoint + ACS Access Key pair are empty, every Task on the AcsPhone Channel stops with a configuration error and the call cannot proceed.

Tasks

All four Tasks are channel-specific implementations for the AcsPhone Channel. They use the same Task types as the Standard Module — the property panel in the BPMN Editor is identical to the chat versions; only the runtime behavior differs.

StartTask (Channel: AcsPhone)

Initializes the call context when a Session begins on the AcsPhone Channel.

Properties

Property	Type	Required	Example	Description
(none)	—	—	—	The StartTask has no configurable properties.

Behavior

1. Checks that the Session is bound to a live call and that the ACS connection is configured.
2. Records the call connection details and the call start time on the Session.
3. Writes the Module's Default Language into the Language Session variable so downstream Tasks use it for speech synthesis.

Example

An outbound notification call begins. The Start Event records the call start time 2026-05-28T09:15:00Z and sets {Language} = en-US for the rest of the Process. The next OutputTask uses that language when it synthesizes the greeting.

OutputTask (Channel: AcsPhone)

Speaks a message to the caller using the configured TTS provider.

Properties

Property	Type	Required	Example	Description
Output Message	string	Yes	Welcome back, {userName}. Press 1 to hear your balance.	The text spoken to the caller. Supports {variable} placeholders for dynamic values.

Behavior

1. Checks that the Session is bound to a live call, that the Output Message is non-empty, and that the ACS connection is configured.
2. Resolves every {variable} placeholder against the current Session variables.
3. Converts the text to audio with the active TTS provider, honoring the Voice and Language Session variables if present (otherwise falling back to the Default Language).
4. Plays the audio to the caller over the live call.

Example

After collecting {userName} in an earlier InputTask, an OutputTask with Output Message Welcome back, {userName}. Press 1 to hear your balance. synthesizes that line in the active language and plays it to the caller. The Token then continues to the next node.

InputTask (Channel: AcsPhone)

Plays a prompt and waits for a keypad (DTMF) digit from the caller.

Properties

Property	Type	Required	Example	Description
Prompt Message	string	Yes	Press 1 for booking, 2 to cancel.	Prompt spoken to the caller before digit recognition starts. Supports {variable} placeholders.
Store in Variable	string	Yes	{userChoice}	On the AcsPhone Channel, type the variable as a {name} reference. The captured digit is written there when the caller presses a key.

Behavior

1. Checks that the Session is bound to a live call, that the Prompt Message is non-empty, that Store in Variable is a {name} reference, and that the ACS connection is configured.
2. Resolves {variable} placeholders in the prompt and converts it to audio with the active TTS provider, honoring the Voice and Language Session variables if set.
3. Plays the prompt and starts keypad recognition for a single digit, with a 5-second initial silence window. The caller can press a key while the prompt is still playing.
4. The Token waits at this node; when the digit arrives, it is written into the configured variable and the Token resumes.

Example

An IVR menu plays Prompt Message Press 1 for booking, 2 to cancel. with Store in Variable {userChoice}. The caller presses 1; {userChoice} now holds 1, and a downstream SwitchTask routes the Token to the booking branch.

EndTask (Channel: AcsPhone)

Hangs up the call when the Token reaches the End Event.

Properties

Property	Type	Required	Example	Description
(none)	—	—	—	The EndTask has no configurable properties on the AcsPhone Channel.

Behavior

1. Checks that the Session is bound to a live call and that the ACS connection is configured.
2. If the call is already terminated, the Task exits cleanly with no action.
3. Otherwise it ends the call for all parties and the Session closes.

To speak a farewell to the caller, place an OutputTask with your goodbye text immediately before the End Event.

Example

After the IVR has played its goodbye message through a final OutputTask, the Token reaches the End Event. The Module ends the call, Azure tears the connection down, and the Session closes.

Common recipes

Route callers through a keypad menu

Greet the caller, collect a single digit, and branch the call with the Standard Module's SwitchTask.

1. InputTask — Prompt Message Welcome! Press 1 for bookings, 2 to cancel an appointment., Store in Variable {menuChoice}. The caller's digit lands in {menuChoice}.
2. SwitchTask (Standard Module) — Variable to evaluate {menuChoice}; Case 1: Value 1, Branch booking; Case 2: Value 2, Branch cancel; Default branch other. Label the outgoing Sequence Flows booking, cancel, and other.
3. OutputTask, one per branch — booking speaks You can book online or stay on the line., cancel speaks the cancellation instructions, and other speaks Sorry, that key is not on the menu.
4. EndTask — hangs up the call and closes the Session.

Confirm an appointment with an outbound reminder call

Format the stored appointment time with the Date Module, speak it to the customer, and capture their confirmation.

1. FormatDate (Date Module) — Input date {appointmentUtc}, Pattern dddd d MMMM HH:mm, Locale en-US, Time zone Europe/Rome, Output variable appointmentText. {appointmentText} becomes e.g. Monday 25 May 14:30.
2. OutputTask — Output Message Hello {customerName}, this is a reminder of your appointment on {appointmentText}.
3. InputTask — Prompt Message Press 1 to confirm, or 2 if you need to reschedule., Store in Variable {confirmChoice}.
4. SwitchTask (Standard Module) — Variable to evaluate {confirmChoice}; Case: Value 1, Branch confirmed; Default branch other.
5. OutputTask, one per branch — confirmed speaks Great, see you then!; other speaks No problem, an operator will call you back.
6. EndTask — hangs up and closes the Session.

Best practices

1. Prefer a single connection string — provide the ACS Connection String in the Module's Environment configuration; one secret is simpler to rotate than the separate Endpoint + Access Key pair.
2. Set Default Language to match your Default Voice — speech synthesis falls back to the Default Language when no Language variable is set on the Session; aligning them avoids accent mismatches.
3. Bound Max Call Duration for outbound campaigns — automated outbound workflows should cap call length so a stuck Session cannot rack up Azure minutes indefinitely.
4. Validate keypad input before branching — the InputTask captures a single digit; pair it with a SwitchTask on the captured variable and handle unexpected digits via the Default branch.
5. Keep prompts short — every OutputTask costs a TTS synthesis; long monologues add latency and cost. Break long messages across multiple OutputTasks.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required Task field (e.g. the message to speak) is empty. See full details
4006	ModuleGenericException	The call context is missing or invalid (e.g. no live call bound to the Session). See full details
4008	ModuleMissingConfiguration	The ACS connection is not configured for the Environment. See full details