Skip to main content
PATCH
/
v1
/
voice-agents
/
{voiceAgentId}
Update an existing voice agent
curl --request PATCH \
  --url https://api.tryhamsa.com/v1/voice-agents/{voiceAgentId} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentName": "<string>",
  "greetingMessage": "<string>",
  "greetingMessageType": "<string>",
  "preamble": "<string>",
  "lang": "ar",
  "pokeMessages": [
    "<string>"
  ],
  "realTime": true,
  "silenceThreshold": 123,
  "interrupt": true,
  "outcome": "<string>",
  "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"
  },
  "voiceId": "<string>",
  "description": "<string>",
  "isTemplate": true,
  "icon": "<string>",
  "tools": {
    "genderDetection": false,
    "smartCallEnd": false
  },
  "params": {},
  "alignment": {
    "greetingMessage": "ltr",
    "preamble": "ltr"
  },
  "knowledgeBaseItemsIds": [
    "<string>"
  ],
  "webToolsIds": [
    "<string>"
  ],
  "voiceDictionaryIds": [
    "<string>"
  ],
  "userInactivityTimeout": 17.5,
  "maxCallDuration": 315,
  "responseDelay": 800,
  "backgroundNoise": true,
  "waitForUserToSpeakFirst": 1,
  "thinkingVoice": true,
  "speakerIdentification": true,
  "llmConfig": {
    "provider": "OpenAI",
    "modelName": "GPT-4.1",
    "baseUrl": "https://api.custom-llm.com/v1",
    "apiKey": "sk-...",
    "temperature": 0.2
  },
  "webToolsOverrides": {},
  "agenticRag": true,
  "languageDialectSwitcher": true,
  "noiseCancellation": "<string>",
  "cancelNoisePer": "<string>",
  "minInterruptionDuration": 0.85,
  "vadActivationThreshold": 0.55,
  "enableAutoGainControl": true,
  "sendDenoisedToStt": true
}
'
{
  "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 '

Path Parameters

​
voiceAgentId
string
required

Body

application/json
​
agentName
string
​
greetingMessage
string | null

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

​
greetingMessageType
string | null
​
preamble
string

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

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

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

​
realTime
boolean
​
silenceThreshold
integer
​
interrupt
boolean
​
outcome
string | null

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

​
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"]
}
​
webhookUrl
string<uri> | null
Example:

"https://example.com/webhook"

​
webhookAuth
object

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

​
voiceId
string

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

​
description
string
​
isTemplate
boolean
​
icon
string
​
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
​
knowledgeBaseItemsIds
string[]
​
webToolsIds
string[]
​
voiceDictionaryIds
string[]
​
userInactivityTimeout
number
Required range: 5 <= x <= 30
​
maxCallDuration
number
Required range: 30 <= x <= 600
​
responseDelay
number
Required range: 100 <= x <= 1500
​
backgroundNoise
boolean
​
waitForUserToSpeakFirst
integer
Required range: 0 <= x <= 2
​
thinkingVoice
boolean
​
speakerIdentification
boolean
​
llmConfig
object

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

​
webToolsOverrides
object
​
agenticRag
boolean
​
languageDialectSwitcher
boolean
​
noiseCancellation
string
​
cancelNoisePer
string | null
​
minInterruptionDuration
number
Required range: 0.2 <= x <= 1.5
​
vadActivationThreshold
number
Required range: 0.2 <= x <= 0.9
​
enableAutoGainControl
boolean
​
sendDenoisedToStt
boolean

Response

Successful response

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