curl --request POST \
--url https://api.tryhamsa.com/v1/voice-agents/call-token \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
"callerKey": "user-48213"
}
'{
"success": true,
"message": "success",
"data": {
"callToken": "ct_q3V8kz2Lx0n5Wb7Yc1Rf4Hj6Tm9Pa2Ds8Ge5Ku0Io3Nw",
"expiresAt": "2026-10-31T12:00:30.000Z",
"resolved": {
"versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"versionNumber": 4,
"draftRevisionId": "6e5d4c3b-2a1f-4e0d-9c8b-7a6f5e4d3c2b",
"environmentId": "8c4e2a6b-3d9f-4a1c-9e27-0f1b2c3d4e5f",
"splitApplies": false
}
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}Create Call Token
Creates a call token: a single-use pass to start one web call on an agent, valid for 30 seconds (the call itself can last longer). Use it to start calls from a web page without putting a secret key in it: your server creates the token with a secret key (sk_) and hands it to the page, and the Hamsa web SDK starts the call with it (Authorization: CallToken <token>). With a public key (pk_), the web SDK creates the token itself.
A call token is also the only way to run a call on a specific version or environment: versionRef and environmentId sent directly when starting a call are refused with 403 CallTokenRequired. With neither, the call runs what prod serves; during an A/B test, the side is picked now (send callerKey to keep one person on the same side).
Who can create one: a secret key (sk_, from your server: a request with an Origin header is refused), a public key (pk_: always for its own environment, so it can’t send versionRef or environmentId), or a signed-in dashboard member. Legacy API keys can’t. Needs the agents:call permission; a key limited to some agents works only for those.
curl --request POST \
--url https://api.tryhamsa.com/v1/voice-agents/call-token \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"voiceAgentId": "d949f13f-40d2-4e48-ac86-b66633070603",
"callerKey": "user-48213"
}
'{
"success": true,
"message": "success",
"data": {
"callToken": "ct_q3V8kz2Lx0n5Wb7Yc1Rf4Hj6Tm9Pa2Ds8Ge5Ku0Io3Nw",
"expiresAt": "2026-10-31T12:00:30.000Z",
"resolved": {
"versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"versionNumber": 4,
"draftRevisionId": "6e5d4c3b-2a1f-4e0d-9c8b-7a6f5e4d3c2b",
"environmentId": "8c4e2a6b-3d9f-4a1c-9e27-0f1b2c3d4e5f",
"splitApplies": false
}
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}{
"code": 8404,
"message": "Policy not found!",
"messageKey": "PolicyNotFound",
"params": {
"reason": "NO_DRAFT"
}
}Authorizations
Body
Optional. The version to run: a version ID, draft (your own draft), or draft:<draftId> (a proposed draft; needs the agents:review_drafts permission). Omit it to run what the environment, or prod, serves. Not with a public key.
1 - 100"a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
Was this page helpful?