Skip to main content
The voice is the first thing a lead hears and the last thing they forget. An agent points at one voice by voiceId, picked from its voice list: the curated catalogue, the voices your agency added to its own library, and voices other agencies added.

​
The voice list

List voices returns every voice an agent can speak with. Each row has a source: Your own voices come first, then shared ones, then the catalogue. Which own and shared voices an agent can play depends on the agent, so pass its agentId. Every row reads as: Filter the list with accent, gender, region and age as query parameters. The filters narrow the curated catalogue only. Own and shared voices have no attributes and no preview clip, so they are always listed. The detail endpoint returns one voice from your list, with two more fields: region (a regional grouping such as US, UK, AU or ES) and isCustom, which is true for a voice that is not in the curated catalogue. Such a voice is described by gender, accent and age, never by name. Any id not in your list is a 404. If the provider cannot be reached to describe a voice from your list that is not in the curated catalogue, the detail endpoint still answers 200, with degraded: true and a voice carrying the id alone. Read that as “unknown right now”, not “gone”.

​
Your voice library

Your agency can add voices from the provider’s public voice library, up to your plan’s allowance.
  • Find a voice. Search with a query: a name, a description, or a provider voice id, which matches exactly. Each hit has a providerVoiceId, name and description. Search needs voices:write even though it changes nothing, because it spends calls to the provider.
  • Add it. Send the providerVoiceId, and a displayName of up to 200 characters if you want your own label. The label is shown only to your agency. The response is the whole library, so no second read is needed.
  • Read the library. Each added voice has its providerVoiceId, displayName, addedAt and voiceIds, the ids that select it on an agent. Use the one List voices returns for the agent you are setting. used, limit and remaining report the allowance. limit and remaining are empty (null) when your plan has no limit.
  • Remove it. Preview first: agentCount, agentNames and fallbackVoiceId say which agents would move and to which voice. Removing moves every agent on the voice to the default voice, then frees the slot. The response reports reassignedAgents, and incompleteAgents counts agents that could not be moved. A non-zero incompleteAgents is work to do: those agents are still on the removed voice.
An add can be refused even when the request is well formed:

​
Shared voices

A voice one agency adds is offered to other agencies too, as shared. The label that agency gave it stays with them; everyone else sees the provider’s own name. Not every agency sees every shared voice: which ones an agent can speak with depends on the agent. A shared voice is selected like any other. It does not count against your allowance, and it is not yours to remove.

​
Choosing a voice for an agent

Set config.voice.voiceId on the agent. Four more settings live beside it and shape how the voice comes across: Two related settings sit under config.language: language, and denoisingMode, which cleans up what the agent hears. no-denoise leaves the lead’s audio alone, noise-cancellation removes background noise, and noise-and-background-speech-cancellation also filters out other people talking near the lead. The dashboard walk-through of these settings is in The voice.

​
Custom voices

Our team can put an agent on a voice that is not in your voice list. The dashboard shows it as Custom voice. On the agent, its voice.voiceId reads custom, next to isCustom: true and the voice’s gender, accent and age. The voice’s own id and name are not returned.
  • Sending voiceId: "custom" back keeps the voice, so saving the whole voice block leaves it in place.
  • Setting any other voiceId replaces it, and you can’t set it back yourself.
  • It isn’t copied onto a new agent or a split test variant. Cloning the agent with everything, or adding a variant, is refused with a 403 until the agent is on a voice from your list. Our team can set up variants that share it.

​
Testing a voice

Preview audio tells you how a voice reads a sentence. It does not tell you how leads respond to it. To find that out, run two variants of the agent that differ only in voice and compare their results. See Run a split test.

​
Boundaries

  • A curated voiceId works on any agent in your agency. An own or shared voice’s id works on the agents List voices returns it for.
  • Own and shared voices have no preview clip, and the attribute filters never hide them.
  • The allowance counts the voices you added. Shared voices are free to use.
  • Voice settings belong to the agent, not the campaign. Two campaigns on one agent sound the same.
  • In a split test, the voice block is one of the per-variant settings, so variants may sound different.
  • A voice our team set outside your list stays on the agent until someone picks a different one. It cannot be picked again from the dashboard afterwards.

​
In the API