Aculab Module

Run your Process over a phone call — text-to-speech prompts, speech and keypad input, call transfer, recording, and live transcription.

The Aculab Module connects your Workspace to Aculab Cloud telephony. When someone dials your Aculab number, a Session starts on the AculabVoice Channel: Output Tasks are spoken to the caller with an AWS Polly voice, Input Tasks listen for speech or keypad digits, and dedicated voice Tasks handle recording, call rejection, pauses, and live transcription. The Module requires Environment configuration — each Environment holds its own voice, language, and webhook credentials.

How it works

A phone call is a conversation between the caller and your Process. When a call arrives, Aculab Cloud notifies the platform, a Session starts on the AculabVoice Channel, and the Token moves through your diagram exactly as it does on chat:

1. The caller hears your Output Tasks. Each Output message is rendered to speech with the voice configured for the Environment (or the voice mapped to the call's language).
2. The caller answers your Input Tasks. Recognized speech — or the digits the caller presses — is saved into the Session variable you choose, ready for later Tasks to read as {name}.
3. Logic Tasks run unchanged. SwitchTask, JSTask, OpenAIChatCompletionTask, and other generic Tasks behave exactly as they do on any other Channel, so the same diagram can serve chat users and voice callers.
4. The call ends when the Token reaches an EndTask (optional goodbye message, then hang-up), a SendToAgentTask (the caller is transferred to a human), or an AculabRejectTask (the call is refused before it is even answered).

Recording and live transcription add a second, parallel data path: they can trigger a handler workflow — a separate Process that runs once per recorded file or per recognized phrase, without interrupting the call. See Handler workflows.

Quick start

You need an Aculab Cloud account with an Inbound Service and a phone number attached (cloud.aculab.com).

1. Configure the Module's Environment configuration. In the Environment you will deploy into, open the Aculab Module configuration and set at least Default TTS Voice, Default Language, and Webhook Service Password.
2. Build a minimal Process in the Process Editor: StartTask → OutputTask (Message: Hi! What's your name?) → InputTask (Variable: name) → OutputTask (Message: Hello, {name}. Goodbye!) → EndTask.
3. Deploy the Process to that Environment. The deploy panel shows the Environment's public webhook URLs — copy the start URL, which ends with your Environment token: …/api/AculabModule/Aculab/start/<environment-token>.
4. Point Aculab at your Process. In Aculab Cloud, open Telephony → Inbound Service → your service and paste the start URL into Application URL (method POST). Under Advanced → Authentication, set the password to the same value as Webhook Service Password (and the username to Webhook Service Username if you set one — any username works otherwise). Also paste the error URL (…/error/<environment-token>) into the Error Page URL so call failures appear in your Workspace activity feed.
5. Call your number. The bot greets you, asks your name, repeats it back, and hangs up.

Configuration

Set these in the Module's Environment configuration — each Environment supplies its own voices, languages, and webhook credentials.

Field	Type	Required	Description
Default TTS Voice	dropdown	No	Voice used for all spoken prompts when no language mapping matches. Default: English US Female Polly Joanna Neural.
Default Language	string	No	Speech-recognition language tag, e.g. en-US. Default: en-US.
Timeout Message	string	No	Played when the caller doesn't answer an Input prompt in time. Default: Sorry, I didn't catch that.
Invalid Input Message	string	No	Played when the caller's answer can't be recognized. Default: Sorry, I didn't understand.
Filter Profanity	boolean	No	Masks profanity in recognized speech with asterisks. Default: off.
Max Recognition Alternatives	number	No	Ranked transcription candidates returned per phrase (1–3). Default: 1.
Webhook Service Username	string	No	Optional Basic-Auth username check for inbound webhooks. Empty = any username is accepted.
Webhook Service Password	password	Yes (Production)	Basic-Auth password every inbound Aculab webhook must present. See below.
Language-to-Voice Mapping	list	No	Per-language voice overrides. Empty list = Default TTS Voice is always used.

Default TTS Voice

The AWS Polly voice used by Output, Input, and End Tasks when no Language-to-Voice Mapping row matches the call's language. Pick from the dropdown — every standard and neural voice supported by Aculab Cloud is listed. Default: English US Female Polly Joanna Neural.

Default Language

IETF language tag used for speech recognition on every Input Task. Examples: en-US, it-IT, fr-FR, de-DE. Default: en-US. If you clear it, the language set on the Session is used instead, falling back to en-US.

Webhook authentication

Every Workspace connects its own Aculab Cloud account, so the webhook credential is also per Environment: the Webhook Service Password you set here must match the Authentication password on the Aculab Inbound Service (Inbound Service → Advanced → Authentication; keep the SSL certificate check enabled).

• What it protects. The password gates all call webhooks for the Environment: the start call, every mid-call continuation (speech results, digits, recording results, transfer results), the error callback, and the transcription / recording-available events. Mid-call callbacks are matched back to the Environment that started the call and checked against the same password. A wrong or missing credential is rejected with 401 Unauthorized.
• Webhook Service Username is optional. When set, the username Aculab sends must match it too. When empty, any username is accepted and only the password is checked.
• Production enforces a password. If the Webhook Service Password is empty in a Production deployment, the platform refuses every Aculab webhook for that Environment — calls fail until you set a password. An empty password is accepted only in non-production Environments, for development.
• The Environment token in the webhook URL is an identifier, not a secret — the password is the only credential.

Timeout Message

Prompt played when the caller doesn't respond to an Input Task in time, before the question is asked again. Supports {variable} placeholders. Default: Sorry, I didn't catch that. Set it in the language your callers speak.

Invalid Input Message

Prompt played when the caller's answer can't be recognized, before the question is asked again. Supports {variable} placeholders. Default: Sorry, I didn't understand.

Filter Profanity

When on, recognized speech containing profanity is masked with asterisks. Applies to every Input Task and to live transcription unless overridden per Task. Default: off.

Max Recognition Alternatives

How many ranked transcription candidates are produced per phrase (1–3). Default: 1. Input Tasks store the top candidate; raise this only if a downstream Task does its own fuzzy matching on the alternatives.

Language-to-Voice Mapping

Optional list of (Language, TTS Voice) rows. The first row whose Language equals the call's language (case-insensitive, exact — en does not match en-US) wins; otherwise the Default TTS Voice is used. Set the call's language upstream with LanguageTask from the Standard Module.

Language	TTS Voice
en-US	English US Female Polly Joanna Neural
it-IT	Italian Italy Female Polly Bianca Neural
fr-FR	French France Female Polly Lea Neural

Limits

• Inbound webhook bodies larger than 64 KB are rejected.

Tasks

The Module ships two kinds of Tasks:

1. Voice implementations of the standard Tasks — StartTask, OutputTask, InputTask, and EndTask get voice behavior when the Session runs on the AculabVoice Channel. The same diagram runs over chat or voice depending on which Channel started it.
2. Voice-only Tasks — advanced input, DTMF capture, recording, pauses, call rejection, transfer, and live transcription.

Output fields ("Store in Variable"): type a variable name without braces (for example reply) and the Task saves its result there; any later Task can read it as {reply}.

StartTask (Channel: AculabVoice)

Handles the initial setup when a call arrives.

Properties

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

Behavior

1. A Session starts when Aculab delivers an inbound call to the Environment's start webhook.
2. The dialled number is recorded on the Session so later Tasks can read which of your numbers was called.

OutputTask (Channel: AculabVoice)

Speaks a message to the caller using text-to-speech.

Properties

Property	Type	Required	Example	Description
Message	string	Yes	Welcome to ACME support, {name}.	The text spoken to the caller. Supports {variable} placeholders. If the resolved text is empty, nothing is spoken.

Behavior

1. The Task resolves {variable} placeholders against the current Session data.
2. The result is spoken with the Environment's Default TTS Voice (or the mapped voice for the call's language) and recorded in the conversation history.

InputTask (Channel: AculabVoice)

Plays a prompt, then listens for the caller to speak and stores the recognized text.

Properties

Property	Type	Required	Example	Description
Message	string	No	Please say your account name.	Prompt played before listening. Supports {variable} placeholders.
Variable	string	Yes	reply	Store variable — type the name without braces; the recognized text is saved there and read later as {reply}.

Behavior

1. The prompt is spoken, then the call listens using the Environment's Default Language.
2. If the caller stays silent, the Timeout Message plays and the prompt repeats. If the speech can't be recognized, the Invalid Input Message plays and the prompt repeats.
3. The recognized text is saved to the configured variable and the Token continues.

EndTask (Channel: AculabVoice)

Plays an optional goodbye message, then hangs up and ends the Session.

Properties

Property	Type	Required	Example	Description
Message	string	No	Thanks for calling. Goodbye!	Spoken before hanging up. Supports {variable} placeholders. Empty = silent hang-up.

SendToAgentTask (Channel: AculabVoice)

Transfers the live call to a phone number — typically a human agent.

Properties

Property	Type	Required	Example	Description
Destination (phone number)	string	Yes	+15551234567 or {agentNumber}	E.164 phone number or extension to dial. Supports {variable} placeholders. Must be a number Aculab can dial, not a URL or integration name.
Waiting Message	string	No	Please hold while we connect you.	Spoken to the caller while the agent's phone is ringing. Supports {variable} placeholders.
Timeout (seconds)	number	No	120	Max seconds to wait for the agent to answer (0–3600). Default: 300; 0 also falls back to 300.
Additional Data	list	No	customerName / {name}	Key-value pairs passed to the agent leg as call metadata. Values support {variable} placeholders.

Behavior

1. The waiting message (if any) is spoken, then the destination number is dialled and the caller is bridged to it.
2. When the agent leg ends, the Session variable AgentConnectedSeconds holds how long the caller and agent were connected (when Aculab reports it), so a following Task can branch on whether the transfer succeeded.

AculabInputTask (Channel: AculabVoice)

Advanced voice input — speech and/or keypad digits, word-hint biasing, custom timeouts, and barge-in. Use the plain InputTask for simple speech-only prompts.

Properties

Property	Type	Required	Example	Description
Prompt Message	string	Yes	Press 1 for sales or say 'support'.	Played before listening. Supports {variable} placeholders.
Variable	string	Yes	choice	Store variable — receives the recognized speech, or the entered digits when nothing was spoken. A second variable named choice_type is also written with speech or digits, so a SwitchTask can branch on how the caller answered. Pick a name that doesn't clash with an existing variable.
Enable Speech	boolean	No	checked	The caller may speak a response. Default: on.
Enable DTMF	boolean	No	checked	The caller may press digits as well as (or instead of) speaking. Default: off.
Word Hints (comma-separated)	string	No	yes,no,operator,sales,support	Biases speech recognition toward expected words or short phrases. Single words or short phrases without commas only — yes, please is split into two hints.
Allow Barge-In	boolean	No	checked	The caller can interrupt the prompt by speaking or pressing a digit. Default: off.
Initial Timeout (seconds)	number	No	10	Seconds to wait for the caller's first sound after the prompt (0–120). Default: 0 = Aculab's default.
Digit Count	number	No	1	Number of digits to collect when DTMF is enabled (0–32). Default: 0 = unlimited, which requires an End Digit.
End Digit	string	No	#	Single digit that ends digit entry. Valid: 0–9, *, #.
Help Digit	string	No	*	Single digit that replays the prompt when pressed. Valid: 0–9, *, #.
Valid Digits	string	No	12340	Set of digits accepted, concatenated with no separators. Empty = all digits accepted.

AculabGetDigitsTask (Channel: AculabVoice)

Keypad-only input. Plays a prompt and collects the digits the caller presses — for PINs, account numbers, and IVR menu keys.

Properties

Property	Type	Required	Example	Description
Prompt Message	string	Yes	Enter your 4-digit PIN.	Played before listening for digits. Supports {variable} placeholders.
Variable	string	Yes	pin	Store variable — receives the entered digits as a string, read later as {pin}. The end digit is not included.
Digit Count	number	No	4	Exact number of digits to collect (0–32). Default: 1. 0 = unlimited, which requires an End Digit.
End Digit	string	Conditional	#	Single digit terminating entry. Valid: 0–9, *, #. Required when Digit Count is 0.
Help Digit	string	No	*	Digit that replays the prompt when pressed. Valid: 0–9, *, #.
Valid Digits	string	No	0123456789	Concatenated set of digits accepted. Empty = all digits accepted.
Initial Timeout (seconds)	number	No	15	Seconds to wait for the first digit after the prompt (0–120). Default: 0 = Aculab's default.

AculabRecordTask (Channel: AculabVoice)

Records the caller's voice to a media file on Aculab Cloud — for voicemail, complaint capture, and compliance recording.

Properties

Property	Type	Required	Example	Description
Prompt Before Recording	string	No	Please leave a message after the beep.	Played before recording starts. Supports {variable} placeholders. Empty = silent start.
Variable	string	Yes	recording	Store variable — receives the recording details: Filename, SecondsDuration, ContainsSound, Reason, BargeInDigit, FileAvailable. Read downstream as {recording.Filename}, {recording.SecondsDuration}, etc.
Beep On Start	boolean	No	checked	Plays a beep before recording begins. Default: on.
Max Duration (seconds)	number	No	120	Hard cap on the recording length (1–600). Default: 60.
Stop After Silence (seconds)	number	No	5	Stops recording after this many seconds of silence (0–60). Default: 5; 0 = never stop on silence.
Initial Silence Timeout (seconds)	number	No	10	How long to wait for the caller's first sound before giving up (0–60). Default: 0 = Aculab's default.
Barge-In Digits	string	No	#	Digits the caller can press to stop recording, concatenated with no separators.
Recording Id	string	No	voicemail-{execution.Id}	Optional identifier surfaced back in the result. Supports {variable} placeholders.
Handler Workflow Token	string	No	b3f2…-guid	Optional Environment token of a separate handler Process that runs once when the recorded file becomes downloadable. Empty = the availability event is only logged. See Handler workflows.

Behavior

1. The prompt (if any) and beep play, then recording starts. It stops at the duration cap, after the silence threshold, or when a barge-in digit is pressed.
2. The Token resumes immediately with the recording details in the configured variable. At that moment FileAvailable may still be false — the file can take seconds to minutes to become downloadable.
3. When the file is downloadable, the Handler Workflow Token Process (if set) runs once on the AculabRecordingAvailable Channel, independently of the call.

AculabSleepTask (Channel: AculabVoice)

Pauses the call for a number of seconds without playing audio — for example between two prompts, to give the caller a moment.

Properties

Property	Type	Required	Example	Description
Seconds	number	Yes	2	How long the call pauses (1–300). Default: 1.

AculabRejectTask (Channel: AculabVoice)

Rejects the inbound call before it is answered — for blocked numbers, business-hours gating, or fraud filters. Distinct from EndTask, which hangs up an answered call.

Properties

Property	Type	Required	Example	Description
Cause	dropdown	Yes	busy	Reason returned to the carrier. One of: rejected, busy, noanswer, unobtainable, changed, outoforder, barred, nochannels, congestion. Default: rejected.
Raw Cause Override	string	No	486	Protocol-specific clearing cause (e.g. a SIP response code) passed straight through. When set, it overrides Cause.

AculabStartTranscriptionTask (Channel: AculabVoice)

Starts live transcription of the call audio. Phrases are delivered to the platform while the call continues, and can each trigger a handler Process. Pair with AculabStopTranscriptionTask before hang-up.

Properties

Property	Type	Required	Example	Description
Transcription Mode	dropdown	No	Mixed	Mixed = both parties combined, Inbound = caller only, Outbound = bot only, Separate = both, tagged by direction. Default: Mixed.
Transcription Id	string	No	{execution.Id}	Optional identifier echoed back on every transcription event. Supports {variable} placeholders.
Enable Profanity Filter	boolean	No	checked	Masks profanity in transcribed phrases. Independent of the Environment-level Filter Profanity setting. Default: off.
Handler Workflow Token	string	No	b3f2…-guid	Optional Environment token of a separate handler Process that runs once per recognized phrase on the AculabTranscription Channel. Empty = phrases are only logged. See Handler workflows.

AculabStopTranscriptionTask (Channel: AculabVoice)

Stops a transcription previously started with AculabStartTranscriptionTask. Place it before EndTask so the final phrase is flushed before hang-up.

Properties

Property	Type	Required	Example	Description
(none)	—	—	—	This Task has no configurable properties.

Handler workflows

Recording and transcription can each trigger a handler workflow: a completely separate Process, authored, deployed, and versioned on its own, that runs while (or after) the call continues.

Source Task	When the handler runs	Channel of the handler Session
AculabStartTranscriptionTask	Once per recognized phrase, while the call is still running	AculabTranscription
AculabRecordTask	Once per recording, when the file becomes downloadable	AculabRecordingAvailable

The mental model. The call doesn't wait for the handler, can't read its result, and doesn't share Session variables with it. The only relationship is the Root Execution Id link: every handler Session is tagged with the voice call's Session id, so the audit view groups "this call plus every handler run it triggered" as one logical unit.

To set one up:

1. Deploy the handler Process first and copy its Environment token from the deploy panel.
2. Paste that token into Handler Workflow Token on AculabStartTranscriptionTask (or AculabRecordTask) in the voice Process and deploy it.
3. Each event now starts an independent handler Session. The event data Aculab sends is available to the handler's Tasks via {variable} placeholders — a transcription event carries fields such as transcription (with the recognized alternatives), id, and completed; a recording-available event carries filename and id.

Design rules for handler Processes:

• Use generic Tasks — JSTask, OpenAIChatCompletionTask, MLNetTask, and the Standard Module's default StartTask / EndTask. They run the same on every Channel. Don't use an OutputTask expecting speech: a handler Session is not a phone call, so there is no caller to speak to.
• Don't try to change the parent call. Handler Sessions can't write the call's Session variables. If the call must react to handler output, go through an external store (database row, HTTP endpoint) the call polls.
• Handler errors never reach the caller. Failures are recorded in the Logs; the call continues. There is no retry — a failed handler run for a phrase or recording is lost.
• Both Processes must be in the same Workspace. A handler token from another Workspace is rejected with error 5005 RootExecutionInvalid.

If you leave Handler Workflow Token empty, events are still received and logged — useful for observability without a handler.

warning

A live transcription producing 30 phrases per minute on a 10-minute call triggers 300 handler Sessions, each counting toward your Service Plan's execution limits — and, if the handler calls an LLM, toward its cost. Enable transcription handlers selectively, or batch phrases (e.g. have the handler write them to a database and summarize once per call).

Common recipes

Route callers through an IVR menu

The caller presses or says their choice, a SwitchTask routes them, and each branch transfers to the right team.

1. OutputTask — Message: Welcome to ACME. Press 1 or say 'sales', press 2 or say 'support'.
2. AculabInputTask — Variable: choice, Enable Speech: on, Enable DTMF: on, Digit Count: 1, Word Hints: sales,support.
3. SwitchTask (Standard Module) — compares {choice}; label one outgoing Sequence Flow 1 (also match sales) and the other 2 (also match support).
4. SendToAgentTask (sales branch) — Destination: +15551230001, Waiting Message: Connecting you to sales.
5. SendToAgentTask (support branch) — Destination: +15551230002, Waiting Message: Connecting you to support.
6. EndTask — Message: Thanks for calling. Goodbye!

Score caller sentiment live with a handler workflow

The call transcribes itself while it runs; each recognized phrase triggers a separate handler Process that scores sentiment with an LLM.

1. In the voice Process, place AculabStartTranscriptionTask right after StartTask — Transcription Mode: Mixed, Handler Workflow Token: the handler's Environment token — and AculabStopTranscriptionTask just before EndTask.
2. In the handler Process (deployed separately, same Workspace), JSTask (JavaScript Module) pulls the phrase text out of the transcription event and stores it in text, skipping non-final phrases.
3. OpenAIChatCompletionTask (OpenAI Module) — Model: gpt-4o-mini, User Message: Score the sentiment of this sentence from 0 to 10. Reply with the number only: {text}, Output Variable: score.
4. EndTask ends the handler Session. Each phrase appears in the audit grouped under the voice call's Root Execution Id.

Best practices

1. Set the webhook password before going live — Production refuses Aculab webhooks for an Environment with an empty Webhook Service Password, so set it (and the matching Aculab console value) as part of deployment, not after.
2. Localize the retry messages — set Timeout Message and Invalid Input Message in your callers' language, or they hear the English defaults regardless of Default Language.
3. Bias recognition with Word Hints — for menu-style questions, list the answers you expect (yes,no,operator); accuracy improves markedly on short utterances.
4. Prefer AculabGetDigitsTask for codes — PINs and account numbers are far more reliable as keypad input than as speech.
5. Stop transcription before hanging up — place AculabStopTranscriptionTask before EndTask so the final phrase is delivered.
6. Configure the error webhook — point Aculab's Error Page URL at …/error/<environment-token> so platform-side call failures land in your Workspace activity feed instead of disappearing.
7. Gate expensive handlers — every transcription phrase is a Session (and possibly an LLM call); enable handlers only on calls that need them.

Troubleshooting

The phone rings but the bot never speaks

The Aculab Inbound Service's Application URL doesn't match the start URL shown in the deploy panel (…/api/AculabModule/Aculab/start/<environment-token>), or the call is being rejected — check Aculab Cloud's request log (Telephony → Logs) for the response code.

Aculab's log shows 401 Unauthorized

The credentials Aculab sends don't match the Environment's Webhook Service Password (or Webhook Service Username, when set). Set the same values in Aculab Cloud → Inbound Service → Advanced → Authentication.

Aculab's log shows 403 Forbidden

The Environment has no Aculab Module configuration saved. Open the Module's Environment configuration and save at least Default TTS Voice and Default Language.

Calls fail in Production with "webhook authentication is not configured"

The Environment's Webhook Service Password is empty. Production refuses unauthenticated Aculab webhooks — set a password in the Environment configuration and mirror it in the Aculab console.

The wrong voice speaks despite a Language-to-Voice Mapping

The call's language doesn't exactly match any mapping row — the match is case-insensitive but exact, so en won't match en-US. Widen the mapping or set the language upstream with LanguageTask.

The handler workflow never runs

Check, in order: the Handler Workflow Token is the handler's Environment token from its deploy panel; the handler Process is deployed; both Processes are in the same Workspace (a cross-Workspace token fails with error 5005); and the Logs for handler-side errors — handler failures never surface in the call itself.

Reference

Channels

Channel	When a Session uses it
AculabVoice	An inbound phone call.
AculabTranscription	A handler Session triggered by a recognized phrase.
AculabRecordingAvailable	A handler Session triggered by a recording becoming downloadable.

Webhook URLs

All URLs are shown in the deploy panel. <environment-token> is the deployed Environment's public token; the per-call continuation URLs are generated automatically — you only ever configure the start and error URLs in the Aculab console.

Path	Configure in Aculab console	Authentication
POST /api/AculabModule/Aculab/start/{environment-token}	Application URL — starts a Session for each inbound call.	Basic Auth (Webhook Service Password / Username).
POST /api/AculabModule/Aculab/next/{executionId}	No — generated per call to deliver speech, digit, recording, and transfer results.	Basic Auth, checked against the same Environment password.
POST /api/AculabModule/Aculab/error/{environment-token}	Error Page URL (recommended) — records Aculab-reported call errors in the Workspace activity feed.	Basic Auth, same as start.
POST /api/AculabModule/Aculab/error	Legacy error hook — accepts the report and writes a short note to the platform log only. Prefer error/{environment-token}.	None.
POST /api/AculabModule/Aculab/end	Final Page (optional) — plain acknowledgement, performs no work; you can leave it unset.	None.
POST /api/AculabModule/Aculab/transcription/{executionId}[/{handlerToken}]	No — generated by AculabStartTranscriptionTask. Delivers each phrase; with a handler token, also starts a handler Session.	Basic Auth, same Environment password.
POST /api/AculabModule/Aculab/recording-available/{executionId}[/{handlerToken}]	No — generated by AculabRecordTask. Fires when the file is downloadable; with a handler token, also starts a handler Session.	Basic Auth, same Environment password.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required Task field is empty or invalid (e.g. SendToAgent Destination, Reject Cause, a malformed digit). See full details
4001	ModuleException	Unhandled telephony error. See full details
4008	ModuleMissingConfiguration	The Environment's Aculab configuration is missing or incomplete. See full details
4009	ModuleInputEmpty	The recognized speech was empty. See full details
4012	ModuleInvalidData	Aculab sent a malformed payload. See full details
5005	RootExecutionInvalid	The handler workflow's Workspace doesn't match the voice call's Workspace. See full details

See Error Codes for the full list.