---
title: "Create a new dial"
method: POST
path: "/dials"
---

# Create a new dial

`POST /dials`

## Request

- Base URL: `https://api.vogent.ai/api`
- URL: `https://api.vogent.ai/api/dials`
- Auth: HTTP bearer

Creates a one-off dial session, either for phone dials or browser dials.

## Request body

- CreateDialInput
  - `webhookUrl` string, nullable: Optional. The URL for the webhook for this dial session.
  - `browserCall` boolean, nullable: Set to true if this is a browser call.
  - `toNumber` string, nullable: Required if this is a phone dial, in E.164 format.
  - `fromNumberId` string, nullable: The ID for the phone number to use to start the call. Required if this is a phone dial.
  - `fromNumberPoolId` string, nullable: The ID of a phone number pool to use when starting the call.
  - `aiVoiceId` string, nullable: The ID for the voice on the call. If not specified, the default voice for the agent will be used.
  - `voiceOptionValues` ModelOptionValue[]: An optional configuration for the voice being used.
    - `optionId` string, required: The ID of option.
    - `value` string, required
  - `voiceVolumeLevel` integer: The volume level for the voice on the call, from -300 (quiet) to 300 (loud).
  - `callAgentId` string, required: Required. The ID of the agent.
  - `versionedModelId` string: The prompt/model version to use for this call, if not specified, the default on the agent is used.
  - `ivrVersionedPromptId` string: The prompt/model version to use for the IVR portion of this call, if ivr nav is enabled on the agent.
  - `overrideTranscriberFinalDurationMs` integer: How long in ms after an utterance is complete to ignore the final/non-final status of the transcript and run inference.
  - `timeoutMinutes` integer: The number of minutes before the call will be timed out. If not specified, there will be no limit on the calls, it's recommended to provide something here.
  - `callAgentExtractorId` string: The ID of the extractor to use for this call, if not specified, the default on the agent is used.
  - `callAgentInput` object, nullable: Any macros in the call agent prompt.
  - `agentOverrides` AgentOverrides: Optional overrides for agent configuration when creating a dial. These override the agent's default settings for this specific dial.
    - `defaultVoiceId` string: The ID of the voice to use.
    - `defaultVersionedPrompt` CreateVersionedPromptInput
      - `aiModelId` string, required: The ID of the model to use.
      - `agentType` 'STANDARD' | 'CUSTOM_FLOW', required
      - `prompt` string, nullable
      - `flowDefinition` FlowDefinitionInput
        - `nodes` ApiFlowNodeInput[]
          - `id` string, required
          - `name` string, required: One of the allowed flow node types. View the available types at https://docs.vogent.ai/flow.
          - `type` string, required
          - `transitionRules` FlowTransitionRuleInput[], required
            - `conditionType` 'always' | 'equal' | 'in' | 'greater' | 'less' | 'language', required: The condition used to evaluate the transition rule. If language, the value will be used as a natural language condition to describe when to execute a transition.
            - `arrayConditionType` 'any' | 'all', nullable: The type of array condition to apply. 'any' means at least one element must match, 'all' means all elements must match.
            - `field` string, nullable
            - `value` string, nullable
            - `values` string[], nullable
            - `transitionNodeId` string, required
          - `nodeData` object, required: The node-specific configuration. View the configurations by node type at https://docs.vogent.ai/flow.
        - `globalContext` string, nullable
        - `aiOpen` boolean: Deprecated, use openingLineType instead.
        - `openingLineType` 'INBOUND_ONLY' | 'INBOUND_OUTBOUND' | 'NONE'
      - `name` string, required
      - `modelOptionValues` ModelOptionValue[]
        - `optionId` string, required: The ID of option.
        - `value` string, required
    - `inboundWebhookResponse` boolean
    - `inboundWebhookUrl` string
    - `maxDurationSeconds` integer: The maximum duration of the call in seconds.
    - `timeoutMessage` string, nullable: An optional message to play via TTS before hanging up when the call reaches its max duration timeout.
    - `timeoutBehaviorConfiguration` TimeoutBehaviorConfiguration, nullable
      - `behavior` 'HANGUP' | 'TRANSFER', required: The behavior when a call reaches its max duration timeout. HANGUP disconnects the call, TRANSFER forwards to a specified number.
      - `transferNumber` string, nullable: The phone number to transfer to when behavior is TRANSFER.
    - `openingLine` object: Details about the Agent's opening line. If unspecified, or null no opening line will be created.
      - `lineType` 'INBOUND_ONLY' | 'INBOUND_OUTBOUND' | 'NONE', required
      - `content` string, required: The content of the opening line.
    - `voiceVolumeLevel` integer: A value, generally between -300 and 300, indicating the volume level to use for the voice. The default is -100.
    - `backgroundNoiseType` 'noise' | 'office' | 'silence': The background audio that's used by the agent.
    - `linkedFunctionDefinitionIds` string[]: The function definitions that should be available to this agent (deprecated, use linkedFunctionDefinitionInputs instead)
    - `linkedFunctionDefinitionInputs` LinkedFunctionDefinition[]: The function definitions that should be available to this agent with optional lifecycle message overrides
      - `functionDefinitionId` string, required: The ID of the function definition to link.
      - `lifecycleMessagesOverride` FunctionLifecycleMessages
        - `started` string[], required: Messages to display when the function starts executing. One will be chosen at random.
        - `waiting` string[]: Messages to play while the function is still running and the model returned StillWaiting. One will be chosen at random. If empty, a built-in default set of English phrases is used.
        - `awaitSpeech` boolean: Hold the function until the agent has finished speaking — any text said alongside the call, then the started message — instead of running it while the agent is still talking. Defaults to false.
    - `metadata` object
    - `transcriberParams` TranscriberParams
      - `type` string, required: By default, the only supported option is deepgram. Please contact support if you'd like access to more options.
      - `keywords` string[]: Keywords to be used for transcription.
    - `idleMessageConfig` IdleMessageConfig
      - `enabled` boolean, required: Whether idle messages are enabled for this agent.
      - `messages` string[]: The list of idle messages that the agent can say when the user is silent.
      - `idleDurationMilliseconds` integer: The duration in milliseconds that the user must be silent before an idle message is triggered.
      - `maxIdleMessages` integer: The maximum number of idle messages that can be said during a call.
    - `utteranceDetectorConfig` UtteranceDetectorConfig
      - `sensitivity` 'ULTRA_FAST' | 'FAST' | 'MEDIUM' | 'SLOW', required
      - `interruptionPlayTimeMs` integer, nullable: The minimum amount of time in milliseconds that the agent will continue speaking after being interrupted. Defaults to 0.
    - `endpointDetectorConfig` EndpointDetectorConfig
      - `type` 'SIMPLE' | 'SEMANTIC', required
      - `mode` 'CONSERVATIVE' | 'DEFAULT' | 'AGGRESSIVE'
    - `ivrConfiguration` IVRConfigurationOverride
      - `detectionType` 'NONE' | 'STANDARD', required: The type of IVR detection to use for the agent.
      - `versionedPromptId` string, nullable: The versioned prompt ID to use for IVR detection.
      - `versionedPrompt` CreateVersionedPromptInput
        - `aiModelId` string, required: The ID of the model to use.
        - `agentType` 'STANDARD' | 'CUSTOM_FLOW', required
        - `prompt` string, nullable
        - `flowDefinition` FlowDefinitionInput
          - `nodes` ApiFlowNodeInput[]
            - `id` string, required
            - `name` string, required: One of the allowed flow node types. View the available types at https://docs.vogent.ai/flow.
            - `type` string, required
            - `transitionRules` FlowTransitionRuleInput[], required
              - …
            - `nodeData` object, required: The node-specific configuration. View the configurations by node type at https://docs.vogent.ai/flow.
          - `globalContext` string, nullable
          - `aiOpen` boolean: Deprecated, use openingLineType instead.
          - `openingLineType` 'INBOUND_ONLY' | 'INBOUND_OUTBOUND' | 'NONE'
        - `name` string, required
        - `modelOptionValues` ModelOptionValue[]
          - `optionId` string, required: The ID of option.
          - `value` string, required
      - `aiVoiceId` string, nullable: The AI voice ID to use for IVR detection.
      - `taggingText` string, nullable: The tagging text for IVR detection.
    - `language` string: The language to use for the agent.
    - `secondaryLanguages` string[]: Additional languages the agent can switch to during a call.
    - `enableChangeLanguage` boolean: Whether the agent can use the change_language tool to switch languages during a call.
    - `fillEmptyStringVariables` boolean: If true, variables that are not specified will be filled with empty strings instead of being left as template placeholders.
    - `silenceHangupConfiguration` SilenceHangupConfiguration, nullable
      - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call.
      - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up.
    - `ivrSilenceHangupConfiguration` SilenceHangupConfiguration, nullable
      - `type` 'DISABLED' | 'FIRST_MESSAGE_ONLY' | 'WHOLE_CALL', required: The type of silence hangup behavior. DISABLED means no silence hangup, FIRST_MESSAGE_ONLY means only hangup if no first message is received, WHOLE_CALL means hangup after silence at any point in the call.
      - `silenceDurationSeconds` integer: The duration of silence in seconds before hanging up.
    - `voicemailConfig` VoicemailConfig, nullable
      - `detection` 'DISABLE' | 'HANGUP' | 'LEAVE_VOICEMAIL', required: How the agent reacts to an answering machine. DISABLE disables voicemail detection, HANGUP ends the call on detection, LEAVE_VOICEMAIL waits for the beep and speaks the configured message before hanging up.
      - `message` string, nullable: The text to speak via TTS when leaving a voicemail. Required when detection is LEAVE_VOICEMAIL.
  - `keywords` string[], nullable: A list of keywords to be used in the call.
  - `advancedBrowserInteraction` boolean: If browserCall is false, and you want to have a more complex flow, allowing the web SDK to have transcribed barge-in lines, you should set this to true. Contact the vogent team to enable this feature.
  - `idempotencyKey` string, nullable: Optional. A unique key that keeps a retried request from placing a second call. If a dial in this workspace was already created with this key, the request fails with a 409 naming that dial instead of dialing again.

## Response `200`

Successful operation

- CreateDialOutput
  - `dialToken` string, required: You can pass this dial token to Elto's web UI, or use this token to authorize any requests for this dial. It's safe to pass this token to a client -- it only allows users to run requests against the dial associated with this session.
  - `sessionId` string, required
  - `dialId` string, required

## Other responses

- `400`: Invalid input
- `409`: The idempotency key on this request is already in use
- `422`: Validation exception

---

[API](https://skmtc.dev/vogent/apis/vogent-openapi-3-0.md) - [All operations](https://skmtc.dev/vogent/apis/vogent-openapi-3-0/llms.txt) - [OpenAPI document](https://skmtc.dev/vogent/apis/vogent-openapi-3-0/revisions/a5966cc364ef?raw)