MCP is live.Set upAsk the community
OmniDimension
Dashboard
DocumentationAPI referenceSDKsMCP
Agents

Create agent

Create a new agent with the provided configuration. The full config supports transcriber, model, voice, web search, transfer, end-call conditions, post-call actions (email, webhook, Omni CRM, Cloud WhatsApp, or a workflow), ambient background track, initial ringing sound, and multilingual support.

POST/agents/create
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.

Initial message the agent will say when answering a call.

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

Title*
Title of the breakdown.
Body*
Body of the breakdown, the detailed prompt content.
Is enabled
Whether this section is included in the prompt.
curl -X POST 'https://omnidim.io/api/v1/agents/create' \
  -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": "Customer Support Agent",
  "status": "Completed"
}

Authorization

BearerAuth
headerAuthorizationBearer <token>

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

Header Parameters

Idempotency-Key?string

Your own unique key for this agent, for example a fresh UUID. Send the same key when you retry. If the first request already created the agent, you get that agent back instead of a second one, so a request that timed out is safe to repeat. The same key with a different request body is refused. Keys are kept for 24 hours.

Lengthlength <= 255

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

Created agent. When the same Idempotency-Key is sent again with the same request body, this is the agent the first request created.

application/json
id?integer

Agent identifier. Use this in subsequent calls to /agents/{agent_id}.

name?string

Echoes the name you submitted.

status?string

Build state of the agent. Always Completed for newly created agents.

Was this page helpful?

List agents

Retrieve all agents for the authenticated user with pagination support.

Get agent

Get details of a specific agent by ID. The response also includes a `can_publish` boolean showing whether [version history](/docs/api-reference/agents/listAgentVersions) is turned on for the agent's organization.