Voiceflow API key
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
Authentication
Path parameters
Response
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
Authentication
Voiceflow API key
Path parameters
Request body
phone-number retains variables for returning callers; call uses a new runtime identity for each call. An omitted setting preserves phone-number behavior.
phone-number, callReplaces tts when the conversation locale matches an override.
Response
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:
sttis a provider-discriminated object. Preserve its provider-specific fields when editing it. - Speech:
ttsis the default voice;localeOverridesselects a replacement by sessionlocale.pronunciationDictionary,audioCue,backgroundAudio,backgroundAudioSettingsandaudioSyncconfigure output. - Phone input:
keypadInputcontainsenabled,delimiter(#,*) andtimeoutInSeconds. - Call lifetime:
maxDurationcontainsenabled,secondsand nullablemessage.silenceTimeoutMsis a legacy fallback in milliseconds: an enabled positivesession.idleTimeout.timeoutMstakes 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:
hasCallRecordingandhasProviderCallRecordingare 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
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.
Related workflows
Use Voice configuration for shared behavior, Studio setup for the interface and Voice agents for execution contracts.