MCP is live.Set upAsk the community
OmniDimension
Agents

Update agent

Update an existing agent. Send only the fields you want to change. `post_call_actions` replaces the agent's email, webhook, Omni CRM, Cloud WhatsApp and workflow actions as one set, but only when you send at least one of those types. Google Sheets, Slack, Salesforce, HubSpot and Zoho Bigin actions are replaced only when their key is sent, and kept otherwise. If a sent action gives a variable key a new prompt, kept actions that use the same key take the new prompt too. To add, change or remove one action without touching the others, use `/agents/{agent_id}/post-call-actions`. > **Voicemail detection is an access-gated feature** that we turn on per account. If it isn't enabled for yours yet, [request access](https://omnidim.io/contact-us?reason=product&lock=1) before configuring the `voicemail` object below.

PUT/agents/
Path parameters
agent_idrequired
Body
21 fields
·

Reseller keys only: act as one of your clients by its user id. Omit it to act on your own account. [How acting for a client works](/docs/reseller/your-clients/acting-as-clients).

Name for the agent.

curl -X PUT 'https://omnidim.io/api/v1/agents/{agent_id}' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": 1234,
  "name": "Customer Support Agent",
  "welcome_message": "Hello! How can I help you today?",
  "dynamic_variables": {
    "customer_name": "Jane Doe",
    "order_id": "ORD-12345"
  },
  "context_breakdown": [
    {
      "title": "Purpose",
      "body": "This agent helps customers with product inquiries and support issues.",
      "is_enabled": true
    }
  ],
  "timezone": "America/New_York",
  "transcriber": {
    "provider": "deepgram_stream",
    "model": "nova-3",
    "language": "en-US",
    "silence_timeout_ms": 400,
    "interruption_min_words": 2,
    "max_call_duration_in_sec": 600
  },
  "model": {
    "model": "gpt-4.1-mini",
    "temperature": 0.7
  },
  "voice": {
    "provider": "eleven_labs",
    "voice_id": "JBFqnCBsd6RMkjVDRZzb",
    "speech_speed": 1
  },
  "web_search": {
    "provider": "DuckDuckGo"
  },
  "post_call_actions": {
    "email": {
      "recipients": [
        "support@example.com"
      ],
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ],
      "trigger_call_statuses": [
        "completed",
        "voicemail_detected"
      ]
    },
    "webhook": {
      "url": "https://your-webhook-endpoint.com/omnidim-callback",
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ],
      "trigger_call_statuses": [
        "completed",
        "failed"
      ]
    },
    "omni_crm": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "cloud_whatsapp": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ],
      "template_variables": [
        {
          "index": "1",
          "extracted_var": "customer_name"
        }
      ],
      "templates": [
        {
          "usage_description": "Send when the caller books an appointment.",
          "variable_mappings": [
            {
              "index": "1"
            }
          ]
        }
      ]
    },
    "workflow": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "google_sheets": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "slack": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "salesforce": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "hubspot": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    },
    "zoho_bigin": {
      "extracted_variables": [
        {
          "key": "customer_issue",
          "prompt": "Identify the main issue the customer is experiencing."
        }
      ]
    }
  },
  "transfer": {
    "transfer_options": [
      {
        "number": "+15551234567",
        "type": "static",
        "transfer_condition": "Transfer if the customer asks to speak with a human.",
        "transfer_message": "Please hold while I connect you to one of our agents."
      }
    ]
  },
  "end_call": {
    "condition": "End the call once the customer'\''s issue is resolved.",
    "message": "Thank you for contacting us. Have a great day!",
    "message_prompt": "End the call politely in the same language the user is speaking."
  },
  "background_track": {
    "volume": 0.2
  },
  "languages": [
    "English (India)",
    "Hindi"
  ]
}'
Example response
{
  "id": 6365,
  "name": "Updated Support Agent",
  "status": "Completed"
}

Authorization

BearerAuth
headerAuthorizationBearer <token>

Bearer token authentication. Obtain your API key from the OmniDimension dashboard.

Path Parameters

agent_id*integer

The ID of the agent.

Request Body

application/json

Agent configuration.

user_id?ClientUserId

Reseller keys only: act as one of your clients by its user id. Omit it to act on your own account. How acting for a client works.

name?string

Name for the agent.

welcome_message?string

Initial message the agent will say when answering a call.

is_welcome_message_dynamic?boolean

When true, the welcome message is treated as a directive the agent uses to generate a tailored greeting for each call, rather than being spoken word for word. When false, the welcome message is spoken exactly as written.

is_welcome_message_interruption?boolean

Allow the caller to interrupt the welcome message. When false, the agent finishes speaking the welcome before listening.

is_interruption_allowed?boolean

Global toggle for whether the caller can interrupt the agent mid-sentence at any point in the call.

dynamic_variables?

Key/value map used to substitute placeholders in the agent's prompt and welcome message at call time. Reference a variable in your prompt with {{variable_name}}. Useful for personalising the same agent across many calls.

context_breakdown?

List of context breakdowns, each containing title, body, and optional is_enabled.

call_type?string

Call type of the assistant.

Value in"Incoming""Outgoing"
timezone?string

IANA timezone for this agent, for example Asia/Kolkata. Sets the local date and time the agent works with during calls. If not set, the account timezone is used as fallback. Pass an empty string to clear it.

transcriber?

Configuration for the speech-to-text transcriber.

model?

Configuration for the language model.

voice?

Configuration for the text-to-speech voice. provider and voice_id identify the voice together, so send both to change it. provider on its own is not accepted, and a voice_id on its own leaves the voice as it was. The other fields here apply independently.

web_search?

Configuration for web search capabilities.

post_call_actions?

Side effects that fire once the call ends: email, webhook, Omni CRM, Cloud WhatsApp, a workflow, Google Sheets, Slack, Salesforce, HubSpot or Zoho Bigin.

transfer?

Conditional call transfer to a human agent or another number.

end_call?

Hang up automatically when a condition is met.

background_track?

Ambient background noise that plays under the agent's voice.

initial_ringing_sound_enabled?boolean

Plays a ringing tone after the call is picked up, until the agent starts speaking.

voicemail?

Voicemail / answering-machine handling for outbound calls. Set this with the nested object shown here; the agent object returns these values as the flat fields voicemail_enabled and voicemail_message. Voicemail detection is an access-gated feature. If it isn't enabled for your account, request access.

languages?array<string>

Languages the agent should support. Pass each language as a display-name string exactly as it appears in the dashboard's language picker. Unrecognized names are skipped.

Response body

application/json

Response Body

Updated agent.

application/json
id?integer

Agent identifier.

name?string
status?string

Build state of the agent after the update. Always Completed once the operation returns.

Was this page helpful?