---
title: "Call Voice Agent using Twilio custom phone number."
method: POST
path: "/v1/voice-agents/phone-number/call"
---

# Call Voice Agent using Twilio custom phone number.

`POST /v1/voice-agents/phone-number/call`

## Request body

- union
  - object
    - `toNumber` string, required — The number that you want to call
    - `phoneNumber` string, required
    - `agentDetails` VoiceAgentRequest
      - `agentName` string, required
      - `greetingMessage` string — Greeting Message can be customized by adding params like: {{name}}, to make the message more personal!
      - `greetingMessageType` 'STATIC' | 'PROMPT', nullable
      - `preamble` string — Preamble can be customized by adding params like: {{agentName}}, to make the prompt more specific and context aware!
      - `lang` 'ar' | 'en'
      - `pokeMessages` string[] — The messages to say to the user when he doesn't respond!
      - `realTime` boolean
      - `silenceThreshold` integer — The silence threshold in milliseconds. Minimum value is 1 millisecond.
      - `interrupt` boolean
      - `type` string
      - `outcome` string, nullable — A prompt to take the conversation and transform it to anything you like, like creating an article out of the conversation!
      - `webhookUrl` string, uri, nullable
      - `webhookAuth` ExternalWebhookAuthScheme — Authorization header to be sent in this format: `Authorization: [authKey] [authSecret]`
        - `authKey` string, nullable
        - `authSecret` string, nullable
      - `outcomeResponseShape` object — Recursive OpenAPI-style shape with 'type', 'properties', 'required', 'items', ...etc. Please refer to the `OpenAPI Outcome Response Instructions` above for more information.
      - `voiceId` string, nullable — For trying voices and choosing one by yourself, or even cloning a voice, please visit Hamsa Agents platform voices tab [here](https://agents.tryhamsa.com/app/voices).
      - `tools` object
        - `genderDetection` boolean
        - `smartCallEnd` boolean
      - `params` object — Set the params you define in the greeting message or preamble fields here, the key is the same as the param and the value is the param value. Press 'Add new property' below to set the param name then press enter, after that add the value.
      - `alignment` object
        - `greetingMessage` string
        - `preamble` string
      - `webToolsIds` string[]
      - `voiceDictionaryIds` string[]
      - `knowledgeBaseItemsIds` string[]
      - `webToolsOverrides` object
      - `userInactivityTimeout` number
      - `maxCallDuration` number
      - `responseDelay` number
      - `backgroundNoise` boolean
      - `waitForUserToSpeakFirst` integer
      - `thinkingVoice` boolean
      - `speakerIdentification` boolean
      - `llmConfig` VoiceAgentLlmConfig — Configuration for the LLM (Large Language Model) used by the voice agent
        - `provider` 'OpenAI' | 'Gemini' | 'deepmyst' | 'Custom' | 'Groq' — The LLM provider to use
        - `modelName` string — The model name to use. Valid models depend on the provider: OpenAI (GPT-5, GPT-5-Mini, GPT-5-Nano, GPT-4.1, GPT-4.1-Mini, GPT-4.1-Nano, GPT-4o, GPT-4o-mini), Gemini (Gemini 2.5-Pro, Gemini 2.5-Flash, gemini-3-flash-preview), deepmyst (gpt-4.1-optimize, gpt-4.1-mini-optimize), Groq (openai/gpt-oss-120b, openai/gpt-oss-20b)
        - `baseUrl` string — Custom base URL for the LLM API. Required when provider is 'Custom'
        - `apiKey` string — API key for authentication with the LLM provider. Required when provider is 'Custom'
        - `temperature` number — Controls randomness in the model's responses. Lower values make output more deterministic, higher values make it more creative. Note: GPT-5, GPT-5-Mini, and GPT-5-Nano models require temperature to be exactly 1.
      - `noiseCancellation` string
      - `cancelNoisePer` string
      - `agenticRag` boolean
      - `languageDialectSwitcher` boolean
      - `minInterruptionDuration` number
      - `vadActivationThreshold` number
      - `enableAutoGainControl` boolean
      - `sendDenoisedToStt` boolean
    - `voiceAgentId` string, nullable, required
    - `params` object, required — Overriding params set in the voice agent's greeting message or preamble. Send when using voiceAgentId only.
  - object
    - `toNumber` string, required — The number that you want to call
    - `phoneNumber` string, required
    - `agentDetails` VoiceAgentRequest, required
      - `agentName` string, required
      - `greetingMessage` string — Greeting Message can be customized by adding params like: {{name}}, to make the message more personal!
      - `greetingMessageType` 'STATIC' | 'PROMPT', nullable
      - `preamble` string — Preamble can be customized by adding params like: {{agentName}}, to make the prompt more specific and context aware!
      - `lang` 'ar' | 'en'
      - `pokeMessages` string[] — The messages to say to the user when he doesn't respond!
      - `realTime` boolean
      - `silenceThreshold` integer — The silence threshold in milliseconds. Minimum value is 1 millisecond.
      - `interrupt` boolean
      - `type` string
      - `outcome` string, nullable — A prompt to take the conversation and transform it to anything you like, like creating an article out of the conversation!
      - `webhookUrl` string, uri, nullable
      - `webhookAuth` ExternalWebhookAuthScheme — Authorization header to be sent in this format: `Authorization: [authKey] [authSecret]`
        - `authKey` string, nullable
        - `authSecret` string, nullable
      - `outcomeResponseShape` object — Recursive OpenAPI-style shape with 'type', 'properties', 'required', 'items', ...etc. Please refer to the `OpenAPI Outcome Response Instructions` above for more information.
      - `voiceId` string, nullable — For trying voices and choosing one by yourself, or even cloning a voice, please visit Hamsa Agents platform voices tab [here](https://agents.tryhamsa.com/app/voices).
      - `tools` object
        - `genderDetection` boolean
        - `smartCallEnd` boolean
      - `params` object — Set the params you define in the greeting message or preamble fields here, the key is the same as the param and the value is the param value. Press 'Add new property' below to set the param name then press enter, after that add the value.
      - `alignment` object
        - `greetingMessage` string
        - `preamble` string
      - `webToolsIds` string[]
      - `voiceDictionaryIds` string[]
      - `knowledgeBaseItemsIds` string[]
      - `webToolsOverrides` object
      - `userInactivityTimeout` number
      - `maxCallDuration` number
      - `responseDelay` number
      - `backgroundNoise` boolean
      - `waitForUserToSpeakFirst` integer
      - `thinkingVoice` boolean
      - `speakerIdentification` boolean
      - `llmConfig` VoiceAgentLlmConfig — Configuration for the LLM (Large Language Model) used by the voice agent
        - `provider` 'OpenAI' | 'Gemini' | 'deepmyst' | 'Custom' | 'Groq' — The LLM provider to use
        - `modelName` string — The model name to use. Valid models depend on the provider: OpenAI (GPT-5, GPT-5-Mini, GPT-5-Nano, GPT-4.1, GPT-4.1-Mini, GPT-4.1-Nano, GPT-4o, GPT-4o-mini), Gemini (Gemini 2.5-Pro, Gemini 2.5-Flash, gemini-3-flash-preview), deepmyst (gpt-4.1-optimize, gpt-4.1-mini-optimize), Groq (openai/gpt-oss-120b, openai/gpt-oss-20b)
        - `baseUrl` string — Custom base URL for the LLM API. Required when provider is 'Custom'
        - `apiKey` string — API key for authentication with the LLM provider. Required when provider is 'Custom'
        - `temperature` number — Controls randomness in the model's responses. Lower values make output more deterministic, higher values make it more creative. Note: GPT-5, GPT-5-Mini, and GPT-5-Nano models require temperature to be exactly 1.
      - `noiseCancellation` string
      - `cancelNoisePer` string
      - `agenticRag` boolean
      - `languageDialectSwitcher` boolean
      - `minInterruptionDuration` number
      - `vadActivationThreshold` number
      - `enableAutoGainControl` boolean
      - `sendDenoisedToStt` boolean
    - `voiceAgentId` string, nullable
    - `params` object — Overriding params set in the voice agent's greeting message or preamble. Send when using voiceAgentId only.

## Response `200`

Successful response

- CallPhoneNumberResponse
  - `success` boolean
  - `message` string
  - `data` object
    - `voiceAgentId` string — The voice agent Id attached to the phone number
    - `jobId` string — The call job Id

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `500` — Server Side Error

---

[API](https://skmtc.net/tryhamsa/apis/hamsa-api.md) · [All operations](https://skmtc.net/tryhamsa/apis/hamsa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryhamsa/hamsa-api/revisions/ecbeb5d8dc13/schema)