Skip to main content
Every agent speaks a primary language and can mirror the caller’s language mid-call. Separately, it has a voice — the identity it speaks with. Language and voice are set independently: one agent can answer in around 40 languages while keeping the same voice.

​
Primary language and mirroring

An agent holds a primaryLanguage (a BCP-47 code like en, es, or fr) plus a list of languages it supports. The greeting and default behavior use the primary language. When a caller speaks a different supported language, the agent can switch to it for the rest of the conversation — no separate flow required.
Set primaryLanguage and languages when you create the agent, or update them later with PATCH /agents/{id}. Mirroring works across the supported set; pick the languages you actually want to serve.

​
How a voice is chosen

A voice is a catalog entry with a normalized set of facets — language, accent, gender, age, category, and mood descriptorTags. You find a voice three ways, then assign it.
1

Browse the catalog

GET /voices returns the catalog, narrowed by any combination of facets (all AND-combined): language, accent, region, gender, age, category, tone, useCase, or free-text q.
2

Count as you narrow

GET /voices/facets returns live counts per facet (“Female · 142”) over the same filters, so a picker can show how each chip shrinks the result set.
3

Search in plain language

POST /voices/search turns a phrase like “calm older british woman for support” into facets and returns the resolved filters plus a short ranked shortlist to audition.
4

Assign it

PUT /agents/{id}/voice assigns a voiceId to the agent for a language (defaults to the primary language). This is the one-call way to set the voice.
A voice carries a previewUrl to audition it, supportedLanguages it can speak, capabilities (which fine-tuning settings the voice supports and its safe speed band), and verifiedLanguages — languages the voice is explicitly verified for, with a localized preview.
Per-language voices are stored in the agent’s voiceMap, and the primary-language voice is also its defaultVoiceId. Assigning a voice for one language never changes the others.

​
In the API

ActionEndpointScope
Browse the voice catalogGET /voicesagents:read
Live facet countsGET /voices/facetsagents:read
Natural-language voice searchPOST /voices/searchagents:read
Assign a voice to an agentPUT /agents/{id}/voiceagents:write
Set primary language / supported languagesPATCH /agents/{id}agents:write
curl https://builder.flowyte.com/api/v1/voices/search \
  -H "Authorization: Bearer flowyte_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"calm older british woman for support","limit":5}'
Voice and language are part of the agent’s draft. Publish the agent so phone and chat callers hear the change.