v1

latestOpenAPI 3.0.1MIT2026-07-26104203277.0 KB

Create a new voice agent

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

post/v1/voice-agents

Request body

agentNamestring required

greetingMessagestring

Greeting Message can be customized by adding params like: {{name}}, to make the message more personal!

greetingMessageType'STATIC' | 'PROMPT' nullable

preamblestring

Preamble can be customized by adding params like: {{agentName}}, to make the prompt more specific and context aware!

lang'ar' | 'en'

pokeMessagesstring[]

The messages to say to the user when he doesn't respond!

realTimeboolean

silenceThresholdinteger

The silence threshold in milliseconds. Minimum value is 1 millisecond.

interruptboolean

typestring

outcomestring nullable

A prompt to take the conversation and transform it to anything you like, like creating an article out of the conversation!

webhookUrlstring uri nullable

outcomeResponseShapeobject

Recursive OpenAPI-style shape with 'type', 'properties', 'required', 'items', ...etc. Please refer to the OpenAPI Outcome Response Instructions above for more information.

voiceIdstring nullable

For trying voices and choosing one by yourself, or even cloning a voice, please visit Hamsa Agents platform voices tab here.

paramsobject

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.

webToolsIdsstring[]

voiceDictionaryIdsstring[]

knowledgeBaseItemsIdsstring[]

webToolsOverridesobject

userInactivityTimeoutnumber

maxCallDurationnumber

responseDelaynumber

backgroundNoiseboolean

waitForUserToSpeakFirstinteger

thinkingVoiceboolean

speakerIdentificationboolean

noiseCancellationstring

cancelNoisePerstring

agenticRagboolean

languageDialectSwitcherboolean

minInterruptionDurationnumber

vadActivationThresholdnumber

enableAutoGainControlboolean

sendDenoisedToSttboolean

Example request

{
  "webhookUrl": "https://example.com/webhook",
  "webhookAuth": {
    "authKey": "Token",
    "authSecret": "Secret"
  },
  "outcomeResponseShape": {
    "type": "object",
    "properties": {
      "test": {
        "type": "number",
        "description": "Hello world from Hamsa AI!"
      }
    },
    "required": [
      "test"
    ]
  },
  "llmConfig": {
    "provider": "OpenAI",
    "modelName": "GPT-4.1",
    "baseUrl": "https://api.custom-llm.com/v1",
    "apiKey": "sk-...",
    "temperature": 0.2
  }
}

Response

Successful response

successboolean

messagestring

Example response

{
  "data": {
    "outcomeResponseShape": {
      "type": "object",
      "properties": {
        "test": {
          "type": "number",
          "description": "Hello world from Hamsa AI!"
        }
      },
      "required": [
        "test"
      ]
    },
    "webhookUrl": "https://example.com/webhook",
    "webhookAuth": {
      "authKey": "Token",
      "authSecret": "Secret"
    },
    "llmConfig": {
      "provider": "OpenAI",
      "modelName": "GPT-4.1",
      "baseUrl": "https://api.custom-llm.com/v1",
      "apiKey": "sk-...",
      "temperature": 0.2
    }
  }
}