---
title: "Create a new voice agent"
method: POST
path: "/v1/voice-agents"
deprecated: true
---

# Create a new voice agent

`POST /v1/voice-agents`

> **Deprecated.**

Create a new voice agent to start using our powerful and robust voice assistant feature. This route requires an API key for authentication.

## Request body

- 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

## Response `200`

Successful response

- VoiceAgentResponse
  - `success` boolean
  - `message` string
  - `data` VoiceAgentResponseData
    - `id` string
    - `agentName` string
    - `greetingMessage` string
    - `greetingMessageType` 'STATIC' | 'PROMPT', nullable
    - `description` string
    - `preamble` string
    - `lang` string
    - `pokeMessages` string[]
    - `realTime` boolean
    - `silenceThreshold` integer
    - `interrupt` boolean
    - `type` string
    - `outcome` string, nullable
    - `outcomeResponseShape` object, nullable
    - `projectId` string
    - `apiKeyId` string
    - `voiceId` string, nullable
    - `voiceRecordId` string, nullable
    - `voiceRecord` object, nullable — The voice record object which is connected to this agent.
    - `collectionId` string, nullable
    - `isTemplate` boolean
    - `icon` string, nullable
    - `webhookUrl` string, uri, nullable
    - `webhookAuth` ExternalWebhookAuthScheme — Authorization header to be sent in this format: `Authorization: [authKey] [authSecret]`
      - `authKey` string, nullable
      - `authSecret` string, nullable
    - `params` object — The parameters that are created for this agent.
    - `alignment` object
      - `greetingMessage` string
      - `preamble` string
    - `tools` object
      - `genderDetection` boolean
      - `smartCallEnd` boolean
    - `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, nullable
    - `agenticRag` boolean
    - `languageDialectSwitcher` boolean
    - `minInterruptionDuration` number
    - `vadActivationThreshold` number
    - `enableAutoGainControl` boolean
    - `sendDenoisedToStt` boolean
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

## Other responses

- `400` — Bad Request
- `401` — Bad Request
- `403` — Bad Request
- `500` — Internal Server 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/versions/ecbeb5d8dc13/schema)