> ## Documentation Index > Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md > The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id. > API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only. > Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling. > To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md > Change one setting on an existing agent per request, such as its prompt, voice, knowledge base, inbound number or webhook subscriptions, by operation name. # Edit Agent Settings export const RelatedTopics = ({items}) =>
Related topics
{items.map(([title, href]) => {title} )}
; Each request names an `operation` and carries the field that operation needs, so a prompt edit cannot overwrite the voice or the webhooks by accident. ## Operations and fields | `operation` | Field to send | | - | - | | `edit_prompt` | `agent_prompt` | | `edit_call_config` | `call_config` | | `edit_agent_display_name` | `agent_display_name` | | `edit_intro_message` | `intro_message` | | `edit_voice` | `voice_id`, plus `language` (a voice must support the language); optional `secondary_voice_id` | | `edit_voice_speed` | `voice_speed` | | `edit_noise_settings` | `mute_during_intro` and `mute_while_bot_speaking`, both required | | `edit_vocab` | `vocab` | | `edit_query_phrases` | `pre_query_response_phrases`, optional `pre_query_phrase_probability` | | `edit_vad_settings` | `vad_settings` | | `edit_custom_vars` | `custom_variables` | | `attach_kb`, `remove_kb` | `kb_id` | | `attach_inbound_number`, `remove_inbound_number` | `number_id` | | `edit_agent_whitelisted_domains` | `whitelisted_domains` (web agents) | | `edit_chat_settings` | `chat_settings` (WhatsApp agents) | | `edit_event_subscriptions` | `event_subscriptions` | `agent_id` is required on every request. Without `version_id`, the change applies to the agent's active version; send `version_id` to change another version. An unknown operation, or a missing field, returns `422`. ## Replace or merge * `edit_prompt` replaces the whole prompt. Send every section; a section you leave out is deleted. * `edit_call_config` merges: only the keys you send change, and nested objects such as `voicemail` merge key by key. * `edit_custom_vars`, `edit_vocab`, `edit_query_phrases`, `edit_vad_settings`, `edit_agent_whitelisted_domains` and `edit_event_subscriptions` replace the current value with the one you send. An outbound agent must keep `callee_name` and `mobile_number` in `custom_variables`, or the request returns `403`. ```json theme={null} { "operation": "edit_call_config", "agent_id": "your-agent-id", "call_config": { "max_call_length": 300, "voicemail": { "detect": true, "action": "end" } } } ``` ## Webhook subscriptions `edit_event_subscriptions` replaces the agent's whole subscription list with the one you send. Read the current list first and send it back with your change, or you will delete the subscriptions you left out. ```json theme={null} { "operation": "edit_event_subscriptions", "agent_id": "your-agent-id", "event_subscriptions": [ { "event_type": ["all_processing_completed"], "callback_url": "https://api.example.com/webhooks/ringg", "method_type": "POST", "headers": { "Authorization": "Bearer your-webhook-receiver-token" } } ] } ``` Each event type can have up to 4 subscriptions on one agent. Call events (`call_started`, `call_ringing`, `call_ongoing`, `call_completed`, `recording_completed`) apply to voice agents and `chat_completed` to WhatsApp agents; subscribing to an event the agent's channel never sends returns `400`. ## Notes * Place one test [individual call](/api-reference/calling/individual-calls/initiate-individual-call) after a change, before the agent runs a campaign. * Call settings such as the calling window and voicemail handling are changed with `edit_call_config`, or in the dashboard under [Call settings](/documentation/build-agents/customize-agent-behaviour/call-settings). ## OpenAPI ````yaml patch /agent/v1 openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send your workspace API key in the X-API-KEY header from server-side code only. Requests and responses are JSON. version: 2.0.0 contact: name: Ringg AI support email: admin@ringg.ai url: https://docs.ringg.ai servers: - url: https://prod-api.ringg.ai/ca/api/v0 security: [] tags: - name: workspace description: Endpoints for managing your workspace. - name: agent description: Endpoints for managing agents. - name: calling description: Endpoints for making and managing calls. - name: campaign description: Endpoints for managing campaigns. - name: analytics description: Endpoints for accessing call analytics and performance metrics. - name: termination description: Endpoints for terminating active calls using different methods. - name: knowledgebase description: Endpoints for managing knowledge bases. paths: /agent/v1: patch: tags: - agent summary: Edit Agent Settings description: >- Updates one setting of an existing agent per request. Each operation requires specific fields. Without `version_id`, the change applies to the agent's active version. operationId: editAssistant parameters: - name: X-API-KEY in: header description: (Required) Your Ringg AI API key. required: true schema: type: string example: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx requestBody: required: true content: application/json: schema: type: object required: - operation - agent_id properties: operation: type: string enum: - attach_inbound_number - remove_inbound_number - attach_kb - remove_kb - edit_custom_vars - edit_voice - edit_prompt - edit_call_config - edit_noise_settings - edit_agent_display_name - edit_intro_message - edit_query_phrases - edit_dtmf_settings - edit_vad_settings - edit_agent_whitelisted_domains - edit_voice_speed - edit_vocab - edit_chat_settings - edit_event_subscriptions example: edit_agent_display_name description: >- The setting to change. Each operation reads only its own fields; see the field descriptions. agent_id: type: string example: 00000000-0000-4000-8000-0000000000a1 version_id: type: string description: >- (Optional) Agent version to change. Without it, the active version is changed; when an A/B test is live, the most recently updated version. Must belong to the agent, or the request returns 404. example: 00000000-0000-4000-8000-0000000000d1 agent_display_name: type: string example: Updated Sales Assistant description: Used with `edit_agent_display_name`. language: type: string enum: - en-US - en-IN - hi-IN - ta-IN - te-IN - kn-IN - mr-IN - gu-IN - ar-AE example: en-US description: >- Used with `edit_voice`: the voice's language. The voice must support it. voice_id: type: string example: 3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d description: Used with `edit_voice`. secondary_voice_id: type: string example: 00000000-0000-4000-8000-000000000102 description: >- Used with `edit_voice`: a second voice. Send an empty string to remove it. agent_prompt: oneOf: - type: string example: You are a helpful sales assistant. - type: object properties: prompt_sections: type: array items: type: object properties: section_title: type: string section_content: type: string description: >- Used with `edit_prompt`. Replaces the whole prompt: send every section, because a section you leave out is deleted. Variables are written `@{{name}}` or `{{name}}`. custom_variables: type: array items: type: string example: - callee_name - mobile_number - company - lead_source description: >- Used with `edit_custom_vars`. Replaces the whole list. An outbound agent must keep `callee_name` and `mobile_number`, or the request returns 403. number_id: type: string example: 00000000-0000-4000-8000-000000000109 description: >- Used with `attach_inbound_number` and `remove_inbound_number`. kb_id: type: string example: 7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d description: Used with `attach_kb` and `remove_kb`. whitelisted_domains: type: array items: type: string example: - https://www.ringg.ai - https://example.com description: >- Used with `edit_agent_whitelisted_domains`. Replaces the list; it must keep `https://www.ringg.ai`. voice_speed: type: number example: 1.2 description: Used with `edit_voice_speed`. chat_settings: type: object description: >- Used with `operation: "edit_chat_settings"`. `whatsapp_session` sets how long a WhatsApp agent's chats stay open. Fields you leave out keep their current values. properties: whatsapp_session: type: object description: >- WhatsApp chat session timeouts. Send both fields: one you leave out is reset to its default. The maximum length must be at least the idle timeout. Applies to chats that open after the change. properties: idle_timeout_minutes: type: integer minimum: 5 maximum: 1440 default: 180 description: >- End the chat after this many minutes with no message from the customer. example: 1440 max_duration_minutes: type: integer minimum: 60 maximum: 10080 default: 1440 description: >- Start a new chat once a chat is this many minutes old. example: 4320 event_subscriptions: type: array description: >- Used with `operation: "edit_event_subscriptions"`. The agent's complete list of webhook subscriptions. The list you send replaces the existing one, so include every subscription you want to keep. items: type: object properties: event_type: type: array description: >- Events delivered to this callback URL. An event type can have up to 4 subscriptions on one agent. `call_started`, `call_ringing`, `call_ongoing`, `call_completed` and `recording_completed` apply to voice agents and `chat_completed` to WhatsApp agents; subscribing an agent to an event its channel never sends returns 400. items: type: string enum: - call_started - call_ringing - call_ongoing - call_completed - chat_completed - recording_completed - platform_analysis_completed - client_analysis_completed - all_processing_completed example: - all_processing_completed callback_url: type: string description: HTTPS endpoint that receives the events. example: https://api.example.com/webhooks/ringg method_type: type: string enum: - GET - POST - PUT - PATCH description: HTTP method Ringg uses when calling your endpoint. example: POST headers: type: object additionalProperties: type: string description: >- Headers Ringg sends to your endpoint with every event, for example a token your receiver checks. example: Authorization: Bearer your-webhook-receiver-token intro_message: type: string description: >- Used with `edit_intro_message`: the first message. Replaces the current one. example: Hello, this is Asha from Acme Lending. mute_during_intro: type: boolean description: >- Used with `edit_noise_settings` (required there): `true` stops the caller interrupting the first message. example: false mute_while_bot_speaking: type: boolean description: >- Used with `edit_noise_settings` (required there): `true` stops the caller interrupting the agent at any time. example: false vocab: type: array items: type: string description: >- Used with `edit_vocab`: words the agent should recognise. Replaces the list; at most 100 words in total. example: - Acme - EMI pre_query_response_phrases: type: array items: type: string description: >- Used with `edit_query_phrases`: phrases the agent may say while it looks something up. Replaces the list. example: - One moment, let me check. pre_query_phrase_probability: type: number minimum: 0 maximum: 1 description: >- Used with `edit_query_phrases` (optional): how often a phrase is said, from 0 to 1. example: 0.5 vad_settings: type: object description: >- Used with `edit_vad_settings`. Replaces the current settings. properties: interruption_sensitivity: type: string enum: - default - sensitive - strict example: default call_config: type: object description: >- Used with `edit_call_config`. Merged into the agent's call settings: only the keys you send change, and nested objects such as `voicemail` merge key by key. Takes the same keys as `call_config` on Create Agent, such as `call_time`, `max_call_length`, `idle_timeout_warning`, `idle_timeout_end` and `voicemail`. `idle_timeout_warning` must stay below `idle_timeout_end`. example: voicemail: detect: true action: end max_call_length: 300 responses: '200': description: 'Successful Response: Agent updated successfully.' content: application/json: schema: type: object properties: message: type: string example: Agent updated successfully! agent_id: type: string example: 00000000-0000-4000-8000-0000000000a1 '400': description: Bad Request - Invalid parameters or request format. content: application/json: schema: type: object properties: message: type: string example: Selected voice does not support the specified language '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Invalid credentials '403': description: >- Forbidden - For example, `edit_custom_vars` without `callee_name` or `mobile_number` on an outbound agent. content: application/json: schema: type: object properties: message: type: string example: >- These variables cannot be removed: callee_name, mobile_number '404': description: Not Found - Agent or agent version not found. content: application/json: schema: type: object properties: message: type: string example: Agent not found '422': description: >- Validation Error - An unknown operation, or a field missing or of the wrong type for the operation. content: application/json: schema: type: object properties: message: type: string '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: message: type: string example: Failed to edit agent ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.