Set voice
Set the voice used at runtime (a voice id from list_voices). Pass both the voice id and the human-readable name so the editor displays the latter. Don't guess a voiceId: when the user describes a voice ('warmer Australian woman'), call `list_voices` to get real candidates, let the operator choose one (in the app, through `ask_user`), then set it. Pass voiceProvider from the same list_voices row, since a mismatched id and provider is rejected.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/operations/set_voice" \ -H "Content-Type: application/json" \ -d '{ "voiceId": "string", "agent": "string" }'{}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Set vocabulary POST
Set the agent's transcription vocabulary specialisation: 'general' (default) or 'medical'. Medical makes the runtime prefer a medical speech recognition variant so clinical vocabulary (medication names, anatomy, procedures) is transcribed more accurately. Agent-scoped (applies across versions), stored on agents.settings.vocabulary. Medical only takes effect on a speech recognition model that has a medical variant; the Hearing page shows which ones do, so switch the agent's model there if it has none. Use when the user says 'this is a medical clinic', 'transcribe medical terms', or 'switch back to general vocabulary'.
Set widget theme POST
Theme the agent's website chat widget (the launcher bubble and chat panel installed with widget.js). Fields: `accent` (hex; launcher, send button, the visitor's own bubbles), `surface` (hex; panel background), `text` (hex; main text colour), `radius` (px 0-24), `font` (system | helvetica | verdana | trebuchet | rounded | georgia | times | palatino | mono; system fonts only), `mode` (light | dark | auto, where auto follows the visitor's light/dark preference), `teaser` (optional line shown once per visitor in a bubble beside the launcher, max 120 characters; off by default), `welcomePrompts` (up to 4 tappable starters under the greeting, each max 60 characters, e.g. ['Prices', 'Opening hours']; a tap sends that text as the visitor's first message; replaces the list, [] removes them), `nudges` (up to 8 follow-up questions, each max 120 characters; while the panel is open and the visitor is quiet, the next one appears as the agent's message every `nudgeDelaySeconds`, in order, each once per conversation, stopping when staff reply or the list runs out; replaces the list, [] turns them off), `nudgeDelaySeconds` (5-120, default 10). Send only what changes; each field merges. null (or an empty teaser) resets that field to the default. Stored on the agent, not the draft: the live widget picks it up on its next page load, no publish needed. An installer's `data-accent` on the snippet still overrides the accent. The header name and avatar come from set_branding (displayName) and the uploaded logo, not from here.