> ## 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 settings > Change an agent's settings. Only the fields sent change, and `null` resets a field to the default calls use. Answers with all of the agent's settings. Applies from the next call. The web app shows the change and its author at once. ## OpenAPI ````yaml /api-reference/v1/openapi.json patch /v1/agents/{id}/settings 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}/settings: patch: tags: - Agents summary: Update settings description: >- Change an agent's settings. Only the fields sent change, and `null` resets a field to the default calls use. Answers with all of the agent's settings. Applies from the next call. The web app shows the change and its author at once. operationId: update_agent_settings 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/AgentSettingsUpdate' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/AgentSettings' 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. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- `sms_setup_required`: texting after calls can't be turned on before one of the agent's phone numbers is registered for texting in the web app. '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. '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: AgentSettingsUpdate: additionalProperties: false description: The settings to change. Only the fields sent change. properties: advanced: $ref: '#/components/schemas/AgentAdvancedSettingsUpdate' description: Listening and response fine-tuning. call: $ref: '#/components/schemas/AgentCallSettingsUpdate' description: Timing and silence handling on calls. compliance: $ref: '#/components/schemas/AgentComplianceSettingsUpdate' description: Recording. title: AgentSettingsUpdate type: object AgentSettings: additionalProperties: false description: >- How an agent handles calls: timing, recording and compliance, and fine-tuning. properties: advanced: $ref: '#/components/schemas/AgentAdvancedSettings' description: Listening and response fine-tuning. agent_id: description: The agent's ID. title: Agent Id type: string call: $ref: '#/components/schemas/AgentCallSettings' description: Timing and silence handling on calls. compliance: $ref: '#/components/schemas/AgentComplianceSettings' description: Recording and compliance. object: const: agent_settings default: agent_settings description: The type of this object, always `agent_settings`. title: Object type: string required: - object - agent_id - call - compliance - advanced title: AgentSettings 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 AgentAdvancedSettingsUpdate: additionalProperties: false properties: interruption_word_count: anyOf: - maximum: 4 minimum: 1 type: integer - type: 'null' description: >- How many words the caller has to say to interrupt the agent, 1 to 4. `null` resets it to the default calls use. title: Interruption Word Count is_smart_endpointing_enabled: anyOf: - type: boolean - type: 'null' description: >- Whether the agent judges from what the caller said, not only from silence, when they have finished speaking. `null` resets it to the default calls use. title: Is Smart Endpointing Enabled knowledge_top_k: anyOf: - maximum: 10 minimum: 1 type: integer - type: 'null' description: >- How many knowledge base passages the agent looks at when it answers a question, 1 to 10. `null` resets it to the default calls use. title: Knowledge Top K noise_filter: anyOf: - description: >- Known values: `phonely`, `none`, `krisp`, `ai_coustics`. More can be added, so handle values you don't recognize. type: string x-extensible-enum: - phonely - none - krisp - ai_coustics - type: 'null' description: >- How background noise on the caller's side is filtered. `null` resets it to the default calls use. title: Noise Filter response_delay_seconds: anyOf: - maximum: 0.4 minimum: 0.05 type: number - type: 'null' description: >- How long the agent waits after the caller stops before it replies, 0.05 to 0.4 seconds. `null` resets it to the default calls use. title: Response Delay Seconds smart_endpointing_wait_seconds: anyOf: - exclusiveMinimum: 0 maximum: 4 type: number - type: 'null' description: >- With smart endpointing, the longest the agent waits for the caller to finish: above 0, up to 4 seconds. Kept while smart endpointing is off. `null` resets it to the default calls use. title: Smart Endpointing Wait Seconds transcriber: anyOf: - type: string - type: 'null' description: >- The speech-to-text engine, one of those the web app offers the agent. Changing it keeps only the agent's languages it supports. `null` resets it to the default calls use. title: Transcriber title: AgentAdvancedSettingsUpdate type: object AgentCallSettingsUpdate: additionalProperties: false properties: is_sms_continuation_enabled: anyOf: - type: boolean - type: 'null' description: >- Whether the agent can carry on the conversation by text message after the call. Turning it on needs one of the agent's phone numbers registered for texting (`409 sms_setup_required` otherwise). `null` resets it to the default calls use. title: Is Sms Continuation Enabled is_time_limit_message_skipped: anyOf: - type: boolean - type: 'null' description: >- Whether the call ends at the time limit without `time_limit_message`. `null` resets it to the default calls use. title: Is Time Limit Message Skipped is_transfer_tone_enabled: anyOf: - type: boolean - type: 'null' description: >- Whether a tone plays when a transferred person joins the call. `null` resets it to the default calls use. title: Is Transfer Tone Enabled silence_check_message: anyOf: - type: string - type: 'null' description: >- What the agent says when it checks in, up to 200 characters. Kept in either mode. `null` or blank text resets it to the default calls use. title: Silence Check Message silence_check_mode: anyOf: - description: >- Known values: `fixed`, `ai_generated`. More can be added, so handle values you don't recognize. type: string x-extensible-enum: - fixed - ai_generated - type: 'null' description: >- How the agent checks in: `fixed` or `ai_generated`. `null` resets it to the default calls use. title: Silence Check Mode silence_check_prompt: anyOf: - type: string - type: 'null' description: >- The instruction the agent writes its check-in from, up to 200 characters. Kept in either mode. `null` or blank text resets it to the default calls use. title: Silence Check Prompt silence_check_retries: anyOf: - maximum: 5 minimum: 1 type: integer - type: 'null' description: >- How many times the agent checks in before it ends the call, 1 to 5. `null` resets it to the default calls use. title: Silence Check Retries silence_timeout_seconds: anyOf: - maximum: 45 minimum: 3 type: number - type: 'null' description: >- How long the caller can stay silent before the agent checks in, 3 to 45 seconds. `null` resets it to the default calls use. title: Silence Timeout Seconds time_limit_message: anyOf: - type: string - type: 'null' description: >- What the agent says when a call reaches the time limit, up to 300 characters. `null` or blank text resets it to the default calls use. title: Time Limit Message time_limit_minutes: anyOf: - maximum: 60 minimum: 0.25 type: number - type: 'null' description: >- The longest a call can last, 0.25 to 60 minutes. `null` resets it to the default calls use. title: Time Limit Minutes time_zone: anyOf: - type: string - type: 'null' description: >- The time zone, as an IANA name such as `America/Los_Angeles`. `null` resets it to the default calls use. title: Time Zone title: AgentCallSettingsUpdate type: object AgentComplianceSettingsUpdate: additionalProperties: false properties: is_recording_enabled: anyOf: - type: boolean - type: 'null' description: >- Whether calls are recorded. `null` resets it to the default calls use. title: Is Recording Enabled is_transfer_recorded: anyOf: - type: boolean - type: 'null' description: >- Whether recording continues after a call is transferred. It can only be turned on while recording is on; turning recording off leaves it as it is. `null` resets it to the default calls use. title: Is Transfer Recorded title: AgentComplianceSettingsUpdate type: object AgentAdvancedSettings: additionalProperties: false properties: interruption_word_count: description: How many words the caller has to say to interrupt the agent. title: Interruption Word Count type: integer is_smart_endpointing_enabled: description: >- Whether the agent judges from what the caller said, not only from silence, when they have finished speaking. title: Is Smart Endpointing Enabled type: boolean knowledge_top_k: description: >- How many knowledge base passages the agent looks at when it answers a question. title: Knowledge Top K type: integer noise_filter: description: >- How background noise on the caller's side is filtered. `phonely` is Phonely's recommended filter. Known values: `phonely`, `none`, `krisp`, `ai_coustics`, `viva`. More can be added, so handle values you don't recognize. title: Noise Filter type: string x-extensible-enum: - phonely - none - krisp - ai_coustics - viva response_delay_seconds: description: How long the agent waits after the caller stops before it replies. title: Response Delay Seconds type: number smart_endpointing_wait_seconds: description: >- With smart endpointing, the longest the agent waits for the caller to finish. title: Smart Endpointing Wait Seconds type: number transcriber: description: >- The speech-to-text engine that hears the caller. `phonely` is Phonely's recommended engine. title: Transcriber type: string required: - noise_filter - transcriber - response_delay_seconds - interruption_word_count - is_smart_endpointing_enabled - smart_endpointing_wait_seconds - knowledge_top_k title: AgentAdvancedSettings type: object AgentCallSettings: additionalProperties: false properties: is_sms_continuation_enabled: description: >- Whether the agent can carry on the conversation by text message after the call. title: Is Sms Continuation Enabled type: boolean is_time_limit_message_skipped: description: >- Whether the call ends at the time limit without `time_limit_message`. title: Is Time Limit Message Skipped type: boolean is_transfer_tone_enabled: description: Whether a tone plays when a transferred person joins the call. title: Is Transfer Tone Enabled type: boolean silence_check_message: anyOf: - type: string - type: 'null' description: >- What the agent says when it checks in, in `fixed` mode. `null` when it is empty. title: Silence Check Message silence_check_mode: description: >- How the agent checks in: with `silence_check_message`, or with words it writes from `silence_check_prompt`. Known values: `fixed`, `ai_generated`. More can be added, so handle values you don't recognize. title: Silence Check Mode type: string x-extensible-enum: - fixed - ai_generated silence_check_prompt: anyOf: - type: string - type: 'null' description: >- The instruction the agent writes its check-in from, in `ai_generated` mode. `null` when it is empty. title: Silence Check Prompt silence_check_retries: description: How many times the agent checks in before it ends the call. title: Silence Check Retries type: integer silence_timeout_seconds: description: How long the caller can stay silent before the agent checks in. title: Silence Timeout Seconds type: number time_limit_message: anyOf: - type: string - type: 'null' description: >- What the agent says when a call reaches the time limit. `null` when it is empty. title: Time Limit Message time_limit_minutes: description: The longest a call can last. title: Time Limit Minutes type: number time_zone: description: >- The agent's time zone, as an IANA name such as `America/Los_Angeles`. title: Time Zone type: string required: - time_zone - silence_timeout_seconds - silence_check_retries - silence_check_mode - silence_check_message - silence_check_prompt - time_limit_minutes - time_limit_message - is_time_limit_message_skipped - is_transfer_tone_enabled - is_sms_continuation_enabled title: AgentCallSettings type: object AgentComplianceSettings: additionalProperties: false properties: is_hipaa_enabled: description: >- Whether the agent handles calls under HIPAA. Only Phonely can change it; it's read-only here. title: Is Hipaa Enabled type: boolean is_recording_enabled: description: Whether calls are recorded. title: Is Recording Enabled type: boolean is_transfer_recorded: description: Whether recording continues after a call is transferred. title: Is Transfer Recorded type: boolean required: - is_recording_enabled - is_transfer_recorded - is_hipaa_enabled title: AgentComplianceSettings 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.