Skip to main content
POST
/
v1
/
voice-agents
Create a new voice agent
curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentName": "<string>",
  "greetingMessage": "Hello, how can I help you today?",
  "greetingMessageType": null,
  "preamble": "You are a helpful assistant that will answer users questions.",
  "lang": "ar",
  "pokeMessages": [],
  "realTime": false,
  "silenceThreshold": 800,
  "interrupt": true,
  "type": "Single Prompt",
  "outcome": null,
  "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"
    ]
  },
  "voiceId": null,
  "tools": {
    "genderDetection": false,
    "smartCallEnd": false
  },
  "params": {},
  "alignment": {
    "greetingMessage": "ltr",
    "preamble": "ltr"
  },
  "webToolsIds": [
    "<string>"
  ],
  "voiceDictionaryIds": [
    "<string>"
  ],
  "knowledgeBaseItemsIds": [
    "<string>"
  ],
  "webToolsOverrides": {},
  "userInactivityTimeout": 15,
  "maxCallDuration": 300,
  "responseDelay": 400,
  "backgroundNoise": false,
  "waitForUserToSpeakFirst": 0,
  "thinkingVoice": false,
  "speakerIdentification": false,
  "llmConfig": {
    "provider": "OpenAI",
    "modelName": "GPT-4.1",
    "baseUrl": "https://api.custom-llm.com/v1",
    "apiKey": "sk-...",
    "temperature": 0.2
  },
  "noiseCancellation": "telephony-optimized",
  "cancelNoisePer": "conversation",
  "agenticRag": false,
  "languageDialectSwitcher": false,
  "minInterruptionDuration": 0.5,
  "vadActivationThreshold": 0.5,
  "enableAutoGainControl": false,
  "sendDenoisedToStt": false
}
'
{
  "success": false,
  "message": "success",
  "data": {
    "id": "<string>",
    "agentName": "<string>",
    "greetingMessage": "<string>",
    "greetingMessageType": "STATIC",
    "description": "<string>",
    "preamble": "<string>",
    "lang": "<string>",
    "pokeMessages": [
      "<string>"
    ],
    "realTime": true,
    "silenceThreshold": 123,
    "interrupt": true,
    "type": "<string>",
    "outcome": "<string>",
    "outcomeResponseShape": {
      "type": "object",
      "properties": {
        "test": {
          "type": "number",
          "description": "Hello world from Hamsa AI!"
        }
      },
      "required": [
        "test"
      ]
    },
    "projectId": "<string>",
    "apiKeyId": "<string>",
    "voiceId": "<string>",
    "voiceRecordId": "<string>",
    "voiceRecord": {},
    "collectionId": "<string>",
    "isTemplate": true,
    "icon": "<string>",
    "webhookUrl": "https://example.com/webhook",
    "webhookAuth": {
      "authKey": "Token",
      "authSecret": "Secret"
    },
    "params": {},
    "alignment": {
      "greetingMessage": "<string>",
      "preamble": "<string>"
    },
    "tools": {
      "genderDetection": true,
      "smartCallEnd": true
    },
    "webToolsIds": [
      "<string>"
    ],
    "voiceDictionaryIds": [
      "<string>"
    ],
    "knowledgeBaseItemsIds": [
      "<string>"
    ],
    "webToolsOverrides": {},
    "userInactivityTimeout": 123,
    "maxCallDuration": 123,
    "responseDelay": 123,
    "backgroundNoise": true,
    "waitForUserToSpeakFirst": 123,
    "thinkingVoice": true,
    "speakerIdentification": true,
    "llmConfig": {
      "provider": "OpenAI",
      "modelName": "GPT-4.1",
      "baseUrl": "https://api.custom-llm.com/v1",
      "apiKey": "sk-...",
      "temperature": 0.2
    },
    "noiseCancellation": "<string>",
    "cancelNoisePer": "<string>",
    "agenticRag": true,
    "languageDialectSwitcher": true,
    "minInterruptionDuration": 123,
    "vadActivationThreshold": 123,
    "enableAutoGainControl": true,
    "sendDenoisedToStt": true,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

Pass the API key in the Authorization header, You need to put Token keyword before the API key. e.g. 'Authorization: Token '

Body

application/json
​
agentName
string
required
​
greetingMessage
string
default:Hello, how can I help you today?

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

​
greetingMessageType
enum<string> | null
Available options:
STATIC,
PROMPT
​
preamble
string
default:You are a helpful assistant that will answer users questions.

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

​
lang
enum<string>
default:ar
Available options:
ar,
en
​
pokeMessages
string[]

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

​
realTime
boolean
default:false
​
silenceThreshold
integer
default:800

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

Required range: x >= 1
​
interrupt
boolean
default:true
​
type
string
default:Single Prompt
​
outcome
string | null

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

​
webhookUrl
string<uri> | null
Example:

"https://example.com/webhook"

​
webhookAuth
object

Authorization header to be sent in this format: Authorization: [authKey] [authSecret]

​
outcomeResponseShape
Outcome Response Schema · object

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

Example:
{
  "type": "object",
  "properties": {
    "test": {
      "type": "number",
      "description": "Hello world from Hamsa AI!"
    }
  },
  "required": ["test"]
}
​
voiceId
string | null

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

​
tools
object
​
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
​
webToolsIds
string[]
​
voiceDictionaryIds
string[]
​
knowledgeBaseItemsIds
string[]
​
webToolsOverrides
object
​
userInactivityTimeout
number
default:15
Required range: 5 <= x <= 30
​
maxCallDuration
number
default:300
Required range: 30 <= x <= 600
​
responseDelay
number
default:400
Required range: 100 <= x <= 1500
​
backgroundNoise
boolean
default:false
​
waitForUserToSpeakFirst
integer
default:0
Required range: 0 <= x <= 2
​
thinkingVoice
boolean
default:false
​
speakerIdentification
boolean
default:false
​
llmConfig
object

Configuration for the LLM (Large Language Model) used by the voice agent

​
noiseCancellation
string
default:telephony-optimized
​
cancelNoisePer
string
default:conversation
​
agenticRag
boolean
default:false
​
languageDialectSwitcher
boolean
default:false
​
minInterruptionDuration
number
default:0.5
Required range: 0.2 <= x <= 1.5
​
vadActivationThreshold
number
default:0.5
Required range: 0.2 <= x <= 0.9
​
enableAutoGainControl
boolean
default:false
​
sendDenoisedToStt
boolean
default:false

Response

Successful response

​
success
boolean
default:false
​
message
string
default:success
​
data
object