Create an Outbound Call

Call Voice Agent using Twilio custom phone number.

curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents/phone-number/call \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "toNumber": "<string>",
  "phoneNumber": "+1234567890",
  "voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
  "params": {},
  "agentDetails": {
    "agentName": ""
  }
}
'

{
  "success": false,
  "message": "success",
  "data": {
    "voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
    "jobId": "d949f13f-40d2-4e48-ac86-b66633070603"
  }
}

POST

voice-agents

phone-number

call

Call Voice Agent using Twilio custom phone number.

curl --request POST \
  --url https://api.tryhamsa.com/v1/voice-agents/phone-number/call \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "toNumber": "<string>",
  "phoneNumber": "+1234567890",
  "voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
  "params": {},
  "agentDetails": {
    "agentName": ""
  }
}
'

{
  "success": false,
  "message": "success",
  "data": {
    "voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
    "jobId": "d949f13f-40d2-4e48-ac86-b66633070603"
  }
}

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

phoneNumber

string

required

Example:

"+1234567890"

voiceAgentId

string | null

required

Example:

"d949f13f-40d2-4e48-ac86-b66633070603"

params

object

required

Overriding 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

agentDetails.agentName

string

required

agentDetails.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!

agentDetails.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!

agentDetails.lang

enum<string>

default:ar

Available options:

ar,

en

agentDetails.pokeMessages

string[]

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

agentDetails.realTime

boolean

default:false

agentDetails.silenceThreshold

integer

default:800

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

Required range: x >= 1

agentDetails.interrupt

boolean

default:false

agentDetails.outcome

string

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

agentDetails.webhookUrl

string<uri> | null

Example:

"https://example.com/webhook"

agentDetails.webhookAuth

object

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

Show child attributes

agentDetails.webhookAuth.authKey

string | null

Example:

"Token"

agentDetails.webhookAuth.authSecret

string | null

Example:

"Secret"

agentDetails.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"]
}

agentDetails.voiceId

enum<string>

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

Available options:

ab55c68b-091b-43b4-a55a-0be82093cd23,

79f81a3b-10f7-4eea-b0aa-5bd0b887d8cd,

f87b58a6-dd88-4f77-86e4-10099e8412c8,

35189a1c-afbd-4ab7-9aa2-1af88c70ac63,

88d45604-12e9-4f7a-93bf-e16cf04c9214,

2ef6405e-7313-4b5e-b738-b0536ed0a36a,

9bead147-7ae5-47aa-80d3-f54668568a69,

e2803890-f4dd-46f7-bfc6-1d3dc761c8ae,

ac5ca565-175c-48d8-98dc-2fccc906cf4b,

fb4d10c0-295d-43a9-9d8e-8775144b4b23,

3c249172-a61a-4a72-9375-1591b73d7ef6,

21f9d3fc-ae8b-41a2-9165-a3186433ae3c,

8e9f526c-eb30-417d-9e7a-65f704917fcc,

8a97dfe8-fe9d-40c5-8f94-7bf9b142e254

agentDetails.tools

object

Show child attributes

agentDetails.tools.genderDetection

boolean

default:false

agentDetails.tools.smartCallEnd

boolean

default:false

agentDetails.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.

Response

Successful response

success

boolean

default:false

message

string

default:success

data

object

Show child attributes

data.voiceAgentId

string

The voice agent Id attached to the phone number

Example:

"d949f13f-40d2-4e48-ac86-b66633070603"

data.jobId

string

The call job Id

Example:

"d949f13f-40d2-4e48-ac86-b66633070603"

List User Phone Numbers Route Create Voice Agent Route

⌘I

API Documentation

SDK Documentation

Voice Enablement

Transcription Routes

Text to Speech Routes

Real Time Routes

Phone Numbers Routes

Voice Agents Routes

Voice Agents Conversations Routes

AI Content Routes

Job Routes

Project Routes

API Statistics Routes

Create an Outbound Call

Authorizations

Body

Response