Edit Agent Settings

curl --request PATCH \
  --url https://prod-api.ringg.ai/ca/api/v0/agent/v1 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "operation": "edit_agent_display_name",
  "agent_id": "00000000-0000-4000-8000-0000000000a1",
  "version_id": "00000000-0000-4000-8000-0000000000d1",
  "agent_display_name": "Updated Sales Assistant",
  "language": "en-US",
  "voice_id": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d",
  "secondary_voice_id": "00000000-0000-4000-8000-000000000102",
  "agent_prompt": "You are a helpful sales assistant.",
  "custom_variables": [
    "callee_name",
    "mobile_number",
    "company",
    "lead_source"
  ],
  "number_id": "00000000-0000-4000-8000-000000000109",
  "kb_id": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d",
  "whitelisted_domains": [
    "https://www.ringg.ai",
    "https://example.com"
  ],
  "voice_speed": 1.2,
  "chat_settings": {
    "whatsapp_session": {
      "idle_timeout_minutes": 1440,
      "max_duration_minutes": 4320
    }
  },
  "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"
      }
    }
  ],
  "intro_message": "Hello, this is Asha from Acme Lending.",
  "mute_during_intro": false,
  "mute_while_bot_speaking": false,
  "vocab": [
    "Acme",
    "EMI"
  ],
  "pre_query_response_phrases": [
    "One moment, let me check."
  ],
  "pre_query_phrase_probability": 0.5,
  "vad_settings": {
    "interruption_sensitivity": "default"
  },
  "call_config": {
    "voicemail": {
      "detect": true,
      "action": "end"
    },
    "max_call_length": 300
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/agent/v1"

payload = {
    "operation": "edit_agent_display_name",
    "agent_id": "00000000-0000-4000-8000-0000000000a1",
    "version_id": "00000000-0000-4000-8000-0000000000d1",
    "agent_display_name": "Updated Sales Assistant",
    "language": "en-US",
    "voice_id": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d",
    "secondary_voice_id": "00000000-0000-4000-8000-000000000102",
    "agent_prompt": "You are a helpful sales assistant.",
    "custom_variables": ["callee_name", "mobile_number", "company", "lead_source"],
    "number_id": "00000000-0000-4000-8000-000000000109",
    "kb_id": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d",
    "whitelisted_domains": ["https://www.ringg.ai", "https://example.com"],
    "voice_speed": 1.2,
    "chat_settings": { "whatsapp_session": {
            "idle_timeout_minutes": 1440,
            "max_duration_minutes": 4320
        } },
    "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" }
        }
    ],
    "intro_message": "Hello, this is Asha from Acme Lending.",
    "mute_during_intro": False,
    "mute_while_bot_speaking": False,
    "vocab": ["Acme", "EMI"],
    "pre_query_response_phrases": ["One moment, let me check."],
    "pre_query_phrase_probability": 0.5,
    "vad_settings": { "interruption_sensitivity": "default" },
    "call_config": {
        "voicemail": {
            "detect": True,
            "action": "end"
        },
        "max_call_length": 300
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operation: 'edit_agent_display_name',
    agent_id: '00000000-0000-4000-8000-0000000000a1',
    version_id: '00000000-0000-4000-8000-0000000000d1',
    agent_display_name: 'Updated Sales Assistant',
    language: 'en-US',
    voice_id: '3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d',
    secondary_voice_id: '00000000-0000-4000-8000-000000000102',
    agent_prompt: 'You are a helpful sales assistant.',
    custom_variables: ['callee_name', 'mobile_number', 'company', 'lead_source'],
    number_id: '00000000-0000-4000-8000-000000000109',
    kb_id: '7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d',
    whitelisted_domains: ['https://www.ringg.ai', 'https://example.com'],
    voice_speed: 1.2,
    chat_settings: {whatsapp_session: {idle_timeout_minutes: 1440, max_duration_minutes: 4320}},
    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'}
      }
    ],
    intro_message: 'Hello, this is Asha from Acme Lending.',
    mute_during_intro: false,
    mute_while_bot_speaking: false,
    vocab: ['Acme', 'EMI'],
    pre_query_response_phrases: ['One moment, let me check.'],
    pre_query_phrase_probability: 0.5,
    vad_settings: {interruption_sensitivity: 'default'},
    call_config: {voicemail: {detect: true, action: 'end'}, max_call_length: 300}
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/agent/v1', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "message": "Agent updated successfully!",
  "agent_id": "00000000-0000-4000-8000-0000000000a1"
}

{
  "message": "Selected voice does not support the specified language"
}

{
  "message": "Invalid credentials"
}

{
  "message": "These variables cannot be removed: callee_name, mobile_number"
}

{
  "message": "Agent not found"
}

{
  "message": "<string>"
}

{
  "message": "Failed to edit agent"
}

PATCH

agent

Edit Agent Settings

curl --request PATCH \
  --url https://prod-api.ringg.ai/ca/api/v0/agent/v1 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "operation": "edit_agent_display_name",
  "agent_id": "00000000-0000-4000-8000-0000000000a1",
  "version_id": "00000000-0000-4000-8000-0000000000d1",
  "agent_display_name": "Updated Sales Assistant",
  "language": "en-US",
  "voice_id": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d",
  "secondary_voice_id": "00000000-0000-4000-8000-000000000102",
  "agent_prompt": "You are a helpful sales assistant.",
  "custom_variables": [
    "callee_name",
    "mobile_number",
    "company",
    "lead_source"
  ],
  "number_id": "00000000-0000-4000-8000-000000000109",
  "kb_id": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d",
  "whitelisted_domains": [
    "https://www.ringg.ai",
    "https://example.com"
  ],
  "voice_speed": 1.2,
  "chat_settings": {
    "whatsapp_session": {
      "idle_timeout_minutes": 1440,
      "max_duration_minutes": 4320
    }
  },
  "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"
      }
    }
  ],
  "intro_message": "Hello, this is Asha from Acme Lending.",
  "mute_during_intro": false,
  "mute_while_bot_speaking": false,
  "vocab": [
    "Acme",
    "EMI"
  ],
  "pre_query_response_phrases": [
    "One moment, let me check."
  ],
  "pre_query_phrase_probability": 0.5,
  "vad_settings": {
    "interruption_sensitivity": "default"
  },
  "call_config": {
    "voicemail": {
      "detect": true,
      "action": "end"
    },
    "max_call_length": 300
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/agent/v1"

payload = {
    "operation": "edit_agent_display_name",
    "agent_id": "00000000-0000-4000-8000-0000000000a1",
    "version_id": "00000000-0000-4000-8000-0000000000d1",
    "agent_display_name": "Updated Sales Assistant",
    "language": "en-US",
    "voice_id": "3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d",
    "secondary_voice_id": "00000000-0000-4000-8000-000000000102",
    "agent_prompt": "You are a helpful sales assistant.",
    "custom_variables": ["callee_name", "mobile_number", "company", "lead_source"],
    "number_id": "00000000-0000-4000-8000-000000000109",
    "kb_id": "7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d",
    "whitelisted_domains": ["https://www.ringg.ai", "https://example.com"],
    "voice_speed": 1.2,
    "chat_settings": { "whatsapp_session": {
            "idle_timeout_minutes": 1440,
            "max_duration_minutes": 4320
        } },
    "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" }
        }
    ],
    "intro_message": "Hello, this is Asha from Acme Lending.",
    "mute_during_intro": False,
    "mute_while_bot_speaking": False,
    "vocab": ["Acme", "EMI"],
    "pre_query_response_phrases": ["One moment, let me check."],
    "pre_query_phrase_probability": 0.5,
    "vad_settings": { "interruption_sensitivity": "default" },
    "call_config": {
        "voicemail": {
            "detect": True,
            "action": "end"
        },
        "max_call_length": 300
    }
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    operation: 'edit_agent_display_name',
    agent_id: '00000000-0000-4000-8000-0000000000a1',
    version_id: '00000000-0000-4000-8000-0000000000d1',
    agent_display_name: 'Updated Sales Assistant',
    language: 'en-US',
    voice_id: '3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d',
    secondary_voice_id: '00000000-0000-4000-8000-000000000102',
    agent_prompt: 'You are a helpful sales assistant.',
    custom_variables: ['callee_name', 'mobile_number', 'company', 'lead_source'],
    number_id: '00000000-0000-4000-8000-000000000109',
    kb_id: '7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d',
    whitelisted_domains: ['https://www.ringg.ai', 'https://example.com'],
    voice_speed: 1.2,
    chat_settings: {whatsapp_session: {idle_timeout_minutes: 1440, max_duration_minutes: 4320}},
    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'}
      }
    ],
    intro_message: 'Hello, this is Asha from Acme Lending.',
    mute_during_intro: false,
    mute_while_bot_speaking: false,
    vocab: ['Acme', 'EMI'],
    pre_query_response_phrases: ['One moment, let me check.'],
    pre_query_phrase_probability: 0.5,
    vad_settings: {interruption_sensitivity: 'default'},
    call_config: {voicemail: {detect: true, action: 'end'}, max_call_length: 300}
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/agent/v1', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "message": "Agent updated successfully!",
  "agent_id": "00000000-0000-4000-8000-0000000000a1"
}

{
  "message": "Selected voice does not support the specified language"
}

{
  "message": "Invalid credentials"
}

{
  "message": "These variables cannot be removed: callee_name, mobile_number"
}

{
  "message": "Agent not found"
}

{
  "message": "<string>"
}

{
  "message": "Failed to edit agent"
}

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.

{
  "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.

{
  "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 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.

Authorizations

X-API-KEY

string

header

required

Headers

X-API-KEY

string

required

(Required) Your Ringg AI API key.

Example:

"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Body

application/json

operation

enum<string>

required

The setting to change. Each operation reads only its own fields; see the field descriptions.

Available options:

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"

agent_id

string

required

Example:

"00000000-0000-4000-8000-0000000000a1"

version_id

string

(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

string

Used with edit_agent_display_name.

Example:

"Updated Sales Assistant"

language

enum<string>

Used with edit_voice: the voice's language. The voice must support it.

Available options:

en-US,

en-IN,

hi-IN,

ta-IN,

te-IN,

kn-IN,

mr-IN,

gu-IN,

ar-AE

Example:

"en-US"

voice_id

string

Used with edit_voice.

Example:

"3b5c7d2a-8e9f-4a1b-9c6d-2e5f8a7b3c4d"

secondary_voice_id

string

Used with edit_voice: a second voice. Send an empty string to remove it.

Example:

"00000000-0000-4000-8000-000000000102"

agent_prompt

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}}.

Example:

"You are a helpful sales assistant."

custom_variables

string[]

Used with edit_custom_vars. Replaces the whole list. An outbound agent must keep callee_name and mobile_number, or the request returns 403.

Example:

[
  "callee_name",
  "mobile_number",
  "company",
  "lead_source"
]

number_id

string

Used with attach_inbound_number and remove_inbound_number.

Example:

"00000000-0000-4000-8000-000000000109"

kb_id

string

Used with attach_kb and remove_kb.

Example:

"7a9c2d5e-4f6b-1a2b-3c4d-5e6f7a8b9c0d"

whitelisted_domains

string[]

Used with edit_agent_whitelisted_domains. Replaces the list; it must keep https://www.ringg.ai.

Example:

[
  "https://www.ringg.ai",
  "https://example.com"
]

voice_speed

number

Used with edit_voice_speed.

Example:

1.2

chat_settings

object

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.

Show child attributes

event_subscriptions

object[]

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.

Show child attributes

intro_message

string

Used with edit_intro_message: the first message. Replaces the current one.

Example:

"Hello, this is Asha from Acme Lending."

mute_during_intro

boolean

Used with edit_noise_settings (required there): true stops the caller interrupting the first message.

Example:

false

mute_while_bot_speaking

boolean

Used with edit_noise_settings (required there): true stops the caller interrupting the agent at any time.

Example:

false

vocab

string[]

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

string[]

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

number

Used with edit_query_phrases (optional): how often a phrase is said, from 0 to 1.

Required range: 0 <= x <= 1

Example:

0.5

vad_settings

object

Used with edit_vad_settings. Replaces the current settings.

Show child attributes

call_config

object

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
}

Response

Successful Response: Agent updated successfully.

message

string

Example:

"Agent updated successfully!"

agent_id

string

Example:

"00000000-0000-4000-8000-0000000000a1"

Introduction

Agents

Inventory

Calling

Monitoring

Account

Edit Agent Settings

Operations and fields

Replace or merge

Webhook subscriptions

Notes

Authorizations

Headers

Body

Response

​Operations and fields

​Replace or merge

​Webhook subscriptions

​Notes

Authorizations

Headers

Body

Response

Operations and fields

Replace or merge

Webhook subscriptions

Notes