Start a Call for a Conversation Route

POST /v1/voice-agents/call

Initiate a call with a voice agent. This endpoint is kept to testing outbound calls via Twilio only.

cURL

curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents/call \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "toNumber": "<string>",
  "voiceAgentId": "<string>",
  "params": {},
  "agentDetails": {},
  "webhookUrl": "https://example.com/webhook",
  "webhookAuth": {
    "authKey": "Token",
    "authSecret": "Secret"
  }
}
'

200

{
  "success": false,
  "message": "success",
  "data": {
    "id": "<string>",
    "title": "<string>",
    "model": "<string>",
    "type": "<string>",
    "processingType": "<string>",
    "webhookUrl": "<string>",
    "totalCost": 123,
    "usageTime": "<string>",
    "fromLng": "<string>",
    "toLng": "<string>",
    "mediaUrl": "<string>",
    "jobResponse": {},
    "fromScript": "<string>",
    "toScript": "<string>",
    "status": "<string>",
    "relevantJobId": "<string>",
    "agentDetails": {
      "id": "<string>",
      "agentName": "<string>",
      "greetingMessage": "<string>",
      "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"
    },
    "apiKeyId": "<string>",
    "billingId": "<string>",
    "systemModelKey": "<string>",
    "voiceAgentId": "<string>",
    "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

Option 1

Option 2

toNumber · string · required

The number that you want to call

fromNumber · enum<string> · required

Available options: [phone], [phone]

voiceAgentId · string | null · required

params · object · required

Params set in the voice agent's greeting message or preamble. Send when using voiceAgentId only.

agentDetails · object

Send agentDetails instead of voiceAgentId and params.

Show child attributes

webhookUrl · string<uri> | null

Example:

"https://example.com/webhook"

webhookAuth · object

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

Show child attributes

Response

200

application/json

Successful call initiation

success · boolean · default: false

message · string · default: success

data · object

Show child attributes