> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Voice through the API

> Prefer the interface? Configure Voice in Studio. Both methods update the same Voice configuration. This guide uses the exact v1alpha1 Voice settings contract.

Prefer the interface? [Configure Voice in Studio](/docs/guides/studio/voice/configure-voice). Both methods update the [same Voice configuration](/docs/documentation/build/voice).

## Before you begin

- A server-side Voiceflow API key with project version-read and project-update permissions.
- The Environment’s concrete version ID; this route does not resolve a display name or alias. Find it through [Environment APIs](/docs/api-reference/environmentpublicapi/get-environment).
- Existing Voice settings on that Environment, `curl` and `jq`.

This guide uses the exact `v1alpha1` [Voice settings contract](/docs/api-reference/environment/voice-settings). Do not substitute the stable Environment resource route.

## Update the configuration

### 1. Read and retain the current settings

```bash title="Read the current Voice settings"
export VF_API_KEY='YOUR_API_KEY'
export VF_ENVIRONMENT_ID='YOUR_ENVIRONMENT_VERSION_ID'
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1alpha1/environment/$VF_ENVIRONMENT_ID/settings/voice" \
  --header "Authorization: $VF_API_KEY" > voice-before.json
```

The response wraps configuration in `voice`. Keep this file to compare and restore your change. A `404` can mean that the Environment has no Voice settings, not just an incorrect ID.

### 2. Build a focused patch

```bash title="Change call limits while preserving other nested settings"
jq '{maxDuration: (.voice.maxDuration + {enabled: true, seconds: 1800, message: "Thanks for calling. Please call us again if you still need help."})}' \
  voice-before.json > voice-patch.json
curl --fail-with-body --silent --show-error --request PATCH \
  "https://realtime-api.voiceflow.com/v1alpha1/environment/$VF_ENVIRONMENT_ID/settings/voice" \
  --header "Authorization: $VF_API_KEY" \
  --header 'Content-Type: application/json' --data @voice-patch.json
```

This example sets a 30-minute maximum call duration. These are illustrative values, not defaults or recommended limits. `PATCH` merges top-level fields, but replaces supplied nested objects except `keypadInput`; merge existing `stt`, `tts` or `maxDuration` before changing a single nested field.

### 3. Read back and test

Repeat the GET into a new file and compare it with `voice-before.json`. A successful PATCH returns **204** with no JSON body. Call the draft over your actual phone or custom client and test the changed behavior before publishing.

## Verify the result

Confirm the returned settings contain your patch and retain unrelated provider options. Test that the duration limit and its End message apply to the intended call. A saved field does not prove that your intended Environment answered the test call.

## Restore or publish

PATCH only the changed fields from `voice-before.json` to restore them. Resolve `400` schema errors or `403` permission errors before retrying. Keep keys on your server. Use [Release a voice integration](/docs/guides/developers/voice/go-live) for publishing and routing.
