> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent's voice > Change how an agent sounds and what it listens for. Only the fields sent change. A request with a list (`languages`, `pronunciations`, `transcription_keywords`) replaces it whole, so it needs `If-Match`. Answers with the agent's whole voice. Applies from the next call. ## OpenAPI ````yaml /api-reference/v1/openapi.json patch /v1/agents/{id}/voice openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/agents/{id}/voice: patch: tags: - Agents summary: Update an agent's voice description: >- Change how an agent sounds and what it listens for. Only the fields sent change. A request with a list (`languages`, `pronunciations`, `transcription_keywords`) replaces it whole, so it needs `If-Match`. Answers with the agent's whole voice. Applies from the next call. operationId: update_agent_voice parameters: - description: The agent's ID. in: path name: id required: true schema: description: The agent's ID. title: Id type: string - description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). in: header name: If-Match required: false schema: anyOf: - type: string - type: 'null' description: >- The `ETag` from your last read: the change is made only if the resource still has it, otherwise `412`. Optional, except that a change replacing a list needs it (`428` without it). title: If-Match - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentVoiceUpdate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentVoice' description: Successful Response headers: ETag: description: >- The resource's current version. Send it as `If-Match` to change it only if it's unchanged. schema: type: string Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The resource doesn't exist, or belongs to another organization. '412': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `If-Match` isn't the resource's current `ETag`: it changed since you read it. '428': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The change replaces a list and came without `If-Match`. Read the resource, then send its `ETag`. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: AgentVoiceUpdate: additionalProperties: false description: >- What to change. Only the fields sent change; a list sent replaces the stored one, so send `If-Match`. properties: background_sound: anyOf: - description: >- Known values: `off`, `office`, `soft_office`. More can be added, so handle values you don't recognize. type: string x-extensible-enum: - 'off' - office - soft_office - type: 'null' description: Ambient sound played behind the voice. `null` resets it to `off`. title: Background Sound background_volume: anyOf: - exclusiveMinimum: 0 maximum: 1 type: number - type: 'null' description: >- The background sound volume, above 0, up to 1. `null` resets it to the 0.2 default. title: Background Volume languages: anyOf: - items: type: string type: array - type: 'null' description: >- The languages the agent listens for, as language codes, in order. Only those the transcriber and voice support. `null` resets them to the voice's language or the transcriber's default. title: Languages pronunciations: anyOf: - items: $ref: '#/components/schemas/PronunciationUpdate' type: array - type: 'null' description: >- All the pronunciations: words left out are removed, and `null` removes them all. title: Pronunciations speed: anyOf: - type: number - type: 'null' description: >- How fast the voice speaks, where 1.0 is its natural pace, within the voice's provider's range (0.5 to 1.5 for most voices). `null` resets it to 1.0. title: Speed transcription_keywords: anyOf: - items: type: string type: array - type: 'null' description: >- All the words the agent listens for especially closely: each once, not blank. title: Transcription Keywords voice_id: anyOf: - type: string - type: 'null' description: >- The voice to speak with: a public voice, or one of your organization's. Changing it keeps only the languages it speaks, and brings `speed` into its provider's range. title: Voice Id title: AgentVoiceUpdate type: object AgentVoice: additionalProperties: false description: How an agent sounds and what it listens for. properties: agent_id: description: The agent's ID. title: Agent Id type: string background_sound: description: >- Ambient sound played behind the voice. Known values: `off`, `office`, `soft_office`. More can be added, so handle values you don't recognize. title: Background Sound type: string x-extensible-enum: - 'off' - office - soft_office background_volume: description: The background sound volume, from 0 to 1. title: Background Volume type: number languages: anyOf: - items: type: string type: array - type: 'null' description: >- The languages the agent listens for, as language codes such as `en` or `es`. `null` when none is chosen: the transcriber's default languages apply. title: Languages object: const: agent_voice default: agent_voice description: The type of this object, always `agent_voice`. title: Object type: string pronunciations: description: How the agent should say particular words. items: $ref: '#/components/schemas/Pronunciation' title: Pronunciations type: array speed: description: How fast the voice speaks, where 1.0 is its natural pace. title: Speed type: number transcription_keywords: description: >- Words the agent listens for especially closely, such as names or product terms. items: type: string title: Transcription Keywords type: array voice_id: anyOf: - type: string - type: 'null' description: The voice the agent speaks with. `null` when none is chosen. title: Voice Id required: - object - agent_id - voice_id - speed - languages - background_sound - background_volume - pronunciations - transcription_keywords title: AgentVoice type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object PronunciationUpdate: additionalProperties: false properties: ipa: anyOf: - type: string - type: 'null' description: >- How to say it in the International Phonetic Alphabet. Only some voices use it. A word needs a `pronunciation`, an `ipa`, or both. title: Ipa pronunciation: anyOf: - type: string - type: 'null' description: How to say it, spelled out in plain letters, such as `fone-lee`. title: Pronunciation word: description: >- The word, as it appears in what the agent says. It can't be a `__placeholder__`. title: Word type: string required: - word title: PronunciationUpdate type: object Pronunciation: additionalProperties: false properties: ipa: anyOf: - type: string - type: 'null' description: >- How to say it in the International Phonetic Alphabet. Only some voices use it. `null` when none is set. title: Ipa pronunciation: anyOf: - type: string - type: 'null' description: >- How to say it, spelled out in plain letters, such as `fone-lee`. `null` when none is set. title: Pronunciation word: description: The word, as it appears in what the agent says. title: Word type: string required: - word - pronunciation - ipa title: Pronunciation type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.