Purpose

These operations manage Environment configuration; they do not start a customer conversation. Use the API task guide for a complete update. The concrete route is v1alpha1, served by realtime-api.voiceflow.com.

Authentication

Use a Voiceflow API key on your server. GET requires project.versions:READ; PATCH requires project:UPDATE. The target is an Environment version ID, not an alias. The operation examples use the realtime-api.voiceflow.com host.

Operations

Read Voice settings

Endpoint
GET
/v1alpha1/environment/{environmentID}/settings/voice

Authentication

authorization
string
header
required

Voiceflow API key

Path parameters

environmentID
string
required

Response

200 - application/json
voice
object
required

Error 401

Missing or invalid authentication.

Error 403

API key lacks the required project permission.

Error 404

Environment not found, or Environment has no Voice settings.

Update Voice settings

Endpoint
PATCH
/v1alpha1/environment/{environmentID}/settings/voice

Authentication

authorization
string
header
required

Voiceflow API key

Path parameters

environmentID
string
required

Request body

stt
object
tts
object
pronunciationDictionary
object[]
Maximum items: 500
failureMessage
string
hasCallRecording
boolean
audioCue
number
backgroundAudio
string
backgroundAudioSettings
object
audioSync
boolean
keypadInput
object
silenceTimeoutMs
number
maxDuration
object
callerIdentity
enum<string>

phone-number retains variables for returning callers; call uses a new runtime identity for each call. An omitted setting preserves phone-number behavior.

Available options: phone-number, call
localeOverrides
object[]

Replaces tts when the conversation locale matches an override.

hasProviderCallRecording
boolean

Response

204

Error 400

Body does not match the Voice settings schema. Unknown top-level fields are rejected.

Error 401

Missing or invalid authentication.

Error 403

API key lacks the required project permission.

Error 404

Environment not found, or Environment has no Voice settings.

Field behavior

  • Recognition: stt is a provider-discriminated object. Preserve its provider-specific fields when editing it.
  • Speech: tts is the default voice; localeOverrides selects a replacement by session locale. pronunciationDictionary, audioCue, backgroundAudio, backgroundAudioSettings and audioSync configure output.
  • Phone input: keypadInput contains enabled, delimiter (#, *) and timeoutInSeconds.
  • Call lifetime: maxDuration contains enabled, seconds and nullable message. silenceTimeoutMs is a legacy fallback in milliseconds: an enabled positive session.idleTimeout.timeoutMs takes precedence. Do not use this field as a substitute for Studio’s current Inactivity timeout.
  • Caller state: callerIdentity: "phone-number" retains returning-caller identity; "call" creates a new runtime identity for each call. Omitted retains phone-number behavior.
  • Recording: hasCallRecording and hasProviderCallRecording are separate fields. Creator disables recording when enabling PII redaction; do not infer that an arbitrary API-written combination is a supported privacy configuration.

PATCH merges top-level fields. keypadInput receives a nested merge; other supplied nested objects are replaced. A read returns { "voice": ... }; PATCH returns 204 without a body. A 404 also covers Environments without Voice settings.

Minimal update

A focused patch

This changes caller state without replacing stt or tts. Values are illustrative.

Errors and recovery

A 404 also means the Environment has no Voice settings. Resolve schema and permission failures before retrying. Read back the saved settings after a successful 204 response.

Use Voice configuration for shared behavior, Studio setup for the interface and Voice agents for execution contracts.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.