Agents

Voices and language

Give an agent one voice or several, set the default, tune the speech engine per voice, and turn diacritization on for a Fusha voice.

An agent always carries at least one voice and can carry several, one per accent you want it to speak with. Each voice has its own speech settings. They all live on the Voice tab, under Used Voices, described as The voice your agent speaks with.

What you need

  • An agent that is not archived. Every control on this tab is disabled while the agent is archived.
  • A voice in the workspace voice library. You do not create voices here; you pick them from the library.

Steps

Step 1: Open the Voice tab

Open the agent and select Voice. The count above the list reads, for example, 2 voices, and the cards are shown two at a time with arrows below them when there are more.

Each card shows the voice's display name, its dialect, a preview you can play, and the actions Make default, Voice Settings and Remove. The voice currently serving as the default shows Default instead of Make default.

Step 2: Add a voice

Press + Add voice and choose one from the picker. It is the same picker the Text to Speech page uses, and it loads up to 100 voices from the library.

A voice already on the agent is ignored rather than added twice. A newly added voice arrives on the default settings, and it becomes the default voice only if it is the first voice on the agent.

Step 3: Choose the default voice

Press Make default on the card you want. Exactly one voice is the default at any time, and setting a new one clears the flag on the old one.

The default is the voice the agent opens with. It switches to the others during a conversation when dialect detection is on.

Step 4: Tune the voice

Press Voice Settings on a card. A sheet titled Voice & speech opens with that voice at the top and a Voice Settings block underneath holding Reset, which puts this voice back to the defaults.

Control What it is Range Default
cfg A guidance scale, shown beside the slider as Guidance and passed to the speech engine unchanged 1.0 to 5.0 2.0
speed The reading pace, shown as a multiplier beside the word Normal 0.5 to 2.0 1.0
num_steps The diffusion step count, offered as five buttons 16, 32, 48, 64 or 128 48
Diacritization Adds diacritics to the text before it is spoken, ON or OFF Fusha voices only OFF

The two sliders move in steps of 0.5, so the portal offers 0.5, 1, 1.5 and 2 for speed. The agents API accepts any value inside the range.

Leave cfg and num_steps at their defaults unless you are tuning against your own listening tests.

Step 5: Turn on diacritization for a Fusha voice

The Diacritization control appears only on a voice whose dialect is fusha. Turn it ON when the agent reads Modern Standard Arabic and you want the text diacritised before it is spoken.

Diacritization applies to a Fusha voice and to no other, whatever is stored on the entry.

Step 6: Remove a voice

Press Remove. The button is disabled when the agent has only one voice left. Removing the default voice hands the default to whichever voice is now first in the list.

Get it right

The voice fixes the accent; the prompt fixes the words. To serve callers in several dialects, add a voice for each one and let the agent switch, rather than describing the switch in prose that no voice can carry out.

Recommended

  • Add an Egyptian voice and a Fusha voice to the agent, make the Egyptian one the default, and turn on dialect detection.
  • Write the language rule in Personality: reply in Egyptian Arabic unless the caller speaks English.

Less effective

  • One Fusha voice, with a prompt that tells the agent to "answer in the caller's accent". The words change; the accent does not.

Worked example

An Acme agent serves Cairo and Riyadh. You add an Egyptian voice and a Saudi voice, press Make default on the Egyptian one, and leave both on the default speech settings.

On the Tools tab you turn on dialect detection. On Persona you add one line: reply in the caller's dialect of Arabic, English only if they use English. The next call opens in Egyptian, and a Saudi caller is answered in the Saudi voice from the turn the dialect is recognised.

What happens next

There is no save button. Adding a voice, removing one and changing the default save straight away. Tuning saves when you close the Voice & speech sheet.

The next conversation uses the new voices and settings. A call already running finishes on the settings it started with.

If a voice is retired, calls use a similar voice. The voice card shows a red note naming it until you pick another voice. If no similar voice exists, calls have no voice until you pick another.

Language comes from the voice

You do not pick a language for an agent. Each voice carries its language and its dialect in the library, and the agent's entry takes both from there. Voices land on one of the dialects in the speech catalogue, today egyptian, emirati, saudi, kuwaiti, qatari, omani, lebanese, syrian, iraqi, fusha, american or british. Older English voices may still carry english. The English dialects american, british and english are language en; every other dialect is language ar.

The voice decides the accent, not the words. What language the agent replies in is a prompt decision, and the two can disagree: an Arabic prompt read by an English voice still comes out with English pronunciation. Write the language rule into the persona and pick the voice to match it.

Text channels have no voice

Nothing on this tab changes a conversation on WhatsApp, Slack, a helpdesk or Genesys chat: a text conversation is not spoken, so the voice list, the speed and the diacritization switch have no effect on it.

You still need at least one voice on an agent that only serves text channels.

Limits

Limit Value Applies to
Voices per agent At least 1, no upper limit voices
Default voices Exactly 1 isDefault
The same voice twice Refused voiceId
Speaking rate 0.5 to 2.0, default 1.0 speed
Guidance scale 1.0 to 5.0, default 2.0 cfg
Diffusion steps 16, 32, 48, 64 or 128, default 48 numSteps
Diacritization Off by default, applied only on a fusha voice tashkeel
Voices loaded into the picker 100 The add dialog
Voice cards per page 2 The Used Voices list

Troubleshooting

Exactly one voice can be the default

The save carried two entries flagged as default. The portal's own screens cannot produce this, so it reaches you through the agents API. Send exactly one, or send none and the first entry is promoted.

At least one voice is required

The save carried an empty voice list. An agent cannot exist without a voice.

Voice ... appears more than once

The full message names the id, as in Voice 66e5ef3a9c1d2b4f8a7e6c01 appears more than once. The same voice is in the list twice. Remove the duplicate.

The card shows an id instead of a name

That voice is no longer in the library, so there is no display name, no dialect and no preview for it. The agent can still start a conversation, but the entry has no voice behind it. Remove it and add a current voice.

Diacritization is missing from the sheet

The voice is not a Fusha voice. The control is offered on dialect fusha only.

Remove is greyed out

The agent has one voice left. Add the replacement first, then remove the old one.

FAQ

Does diacritization work on an Egyptian or Saudi voice?

No. It is applied on a Fusha voice only.

Does adding a second voice change which voice answers first?

No. The agent opens on the default voice, and a voice you add later is not the default unless you make it one.

Can two agents use the same voice?

Yes. Voices belong to the workspace library, and an agent keeps its own tuning, so the same voice can sound different on two agents.

Do voice settings cost anything to change?

No. Changing them is free. A call is charged for the time it is connected; speaking is covered by that price.

Why is my agent's speech still the old speed on a live call?

Because the call took its settings when it started. Hang up and start a new conversation to hear the change.

Is the voice list the same as the Voices page?

The picker reads the same workspace library. The agent's list is the subset this agent may speak with.