Languages & Voice

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.

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.

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.

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.

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

Action	Endpoint	Scope
Browse the voice catalog	`GET /voices`	`agents:read`
Live facet counts	`GET /voices/facets`	`agents:read`
Natural-language voice search	`POST /voices/search`	`agents:read`
Assign a voice to an agent	`PUT /agents/{id}/voice`	`agents:write`
Set primary language / supported languages	`PATCH /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}'

const res = await fetch("https://builder.flowyte.com/api/v1/agents/AGENT_ID/voice", {
  method: "PUT",
  headers: {
    Authorization: "Bearer flowyte_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ voiceId: "VOICE_ID", language: "en" }),
});

import requests

requests.put(
    "https://builder.flowyte.com/api/v1/agents/AGENT_ID/voice",
    headers={"Authorization": "Bearer flowyte_sk_..."},
    json={"voiceId": "VOICE_ID", "language": "en"},
)

Voice and language are part of the agent’s draft. Publish the agent so phone and chat callers hear the change.

Get started

Concepts

Channels

Integrations

Guides

Trust & Security

Languages & Voice

Primary language and mirroring

How a voice is chosen

In the API

​Primary language and mirroring

​How a voice is chosen

​In the API

Primary language and mirroring

How a voice is chosen

In the API