> ## Documentation Index > Fetch the complete documentation index at: https://docs.teamfollowup.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the public API base URL: https://api.teamfollowup.ai/api. > Authenticate public API requests with Authorization: Bearer YOUR_API_KEY. > Use product-owned terms: agents, campaigns, projects (GoHighLevel sub-accounts), contacts, calls, outcomes, skills, cadences, phone numbers. > Scope requests by locationId rather than projectName. > Read the guide linked from each API reference group before recommending an endpoint. # Voices > The voices your agents speak with: the curated catalogue, voices your agency adds to its own library, and voices other agencies added. Pick one by voiceId and tune speed and background sound on the agent. 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`: | `source` | What it is | | --------- | ------------------------------------------------------------------------------------------- | | `own` | A voice your agency added, under the name you gave it. | | `shared` | A voice another agency added that this agent can speak with, under the provider's own name. | | `curated` | The platform's catalogue, with attributes and a preview clip. | 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: | Field | Meaning | | ----------------- | ----------------------------------------------------------------------- | | `voiceId` | The id you send when selecting a voice. | | `voiceName` | Display name, for example `Kate (US)`. Empty when `isCustom` is `true`. | | `gender` | `male`, `female`, or empty when the provider does not say. | | `accent` | Accent label, for example `normal` or `southern`. | | `age` | Age band, for example `young` or `middle_aged`. | | `previewAudioUrl` | A relative URL for a short sample. Play it before you commit. | | `source` | `own`, `shared` or `curated`, as above. | 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: | Status | `error` | Means | | ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `409` | `VOICE_ALLOWANCE` | Your plan's allowance is used up. Remove a voice or upgrade. | | `409` | `VOICE_CAPACITY` | New voices are temporarily unavailable. Contact support. | | `409` | `VOICE_ALREADY_SHARED` | The voice is already on the account: another agency added it, or you added and later removed it. It is in your list as `shared` and nothing is spent. `references.voiceId` is the id to select. | | `404` | `NOT_FOUND` | No voice with that id to add, or on removal, the voice is not in your library. | | `400` | `VALIDATION` | The library refused the request, for example because the voice is already in it. | ## 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: | Field | Does | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `speed` | How fast the agent talks. Slightly slower than natural reads as calm and clear over a phone line. | | `temperature` | How much the delivery varies from one sentence to the next. Higher is livelier and less predictable. | | `ambientSound` | A background bed under the voice: `coffee-shop`, `convention-hall`, `summer-outdoor`, `mountain-outdoor`, `static-noise` or `call-center`. A quiet office bed makes a call sound like it came from a desk, not a server. | | `ambientSoundVolume` | How loud that bed is. | 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](/agents/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](/split-testing/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 * [List voices](/api-reference/voices/list-voices) and [Get voice](/api-reference/voices/get-voice) * [List added voices](/api-reference/voices/list-added-voices), [Search for a voice to add](/api-reference/voices/search-for-a-voice-to-add) and [Add a voice](/api-reference/voices/add-a-voice) * [Preview removing a voice](/api-reference/voices/preview-removing-a-voice) and [Remove a voice](/api-reference/voices/remove-a-voice) * [Update agent](/api-reference/agents/update-agent) sets `config.voice` and `config.language` * Every field above is defined in the [Glossary](/glossary#voices) ## Related * [The voice](/agents/voice) is the dashboard view of these settings. * [Agent split tests](/split-testing/overview) is how you test one voice against another.