curl --request POST \
--url https://api.tryhamsa.com/v2/voice-agents/{voiceAgentId}/draft/propose \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"note": "New opening line for Saudi callers."
}
'{
"success": true,
"message": "success",
"data": {
"id": "9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47",
"author": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"status": "open",
"baseVersionNumber": 4,
"versionsBehind": 0,
"changedPaths": [
"conversation.preamble",
"llm.temperature"
],
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56",
"proposedAt": "2026-10-28T09:15:00.000Z",
"proposalNote": "New opening line for Saudi callers.",
"lastSentBack": {
"by": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"note": "Please keep the greeting under 10 seconds.",
"at": "2026-10-28T09:15:00.000Z"
},
"combinedFrom": [
{
"draftId": "9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56",
"author": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
}
}
],
"expiresAt": "2026-11-04T09:15:00.000Z",
"publishedAs": 5,
"closedBy": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"closedAt": "2026-10-28T09:15:00.000Z",
"closedNote": "Covered by the new FAQ flow.",
"lastVia": {
"kind": "api_key",
"keyRef": "sk_live_4f2a",
"keyName": "CRM sync"
},
"proposedVia": {
"kind": "api_key",
"keyRef": "sk_live_4f2a",
"keyName": "CRM sync"
},
"updatedAt": "2026-10-28T09:15:00.000Z",
"valueKeys": [
"ORDER_ID"
]
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}Agent Versions & Drafts
Propose Agent Draft
Sends your draft for review. Reviewers (members with agents:review_drafts, except you) get a notification and an email (at most one email per draft per hour) and publish it in the dashboard, or send it back. While proposed, the draft does not expire and you can still save to it. Withdraw it with Withdraw Agent Draft.
POST
/
v2
/
voice-agents
/
{voiceAgentId}
/
draft
/
propose
curl --request POST \
--url https://api.tryhamsa.com/v2/voice-agents/{voiceAgentId}/draft/propose \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"note": "New opening line for Saudi callers."
}
'{
"success": true,
"message": "success",
"data": {
"id": "9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47",
"author": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"status": "open",
"baseVersionNumber": 4,
"versionsBehind": 0,
"changedPaths": [
"conversation.preamble",
"llm.temperature"
],
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56",
"proposedAt": "2026-10-28T09:15:00.000Z",
"proposalNote": "New opening line for Saudi callers.",
"lastSentBack": {
"by": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"note": "Please keep the greeting under 10 seconds.",
"at": "2026-10-28T09:15:00.000Z"
},
"combinedFrom": [
{
"draftId": "9a4c1e6b-2f3d-4b8a-8e7c-5d1f0a2b3c47",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56",
"author": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
}
}
],
"expiresAt": "2026-11-04T09:15:00.000Z",
"publishedAs": 5,
"closedBy": {
"id": "b7d9e979-4a16-437b-8571-4ed92a94faa8",
"name": "Sara Ahmad",
"email": "[email protected]"
},
"closedAt": "2026-10-28T09:15:00.000Z",
"closedNote": "Covered by the new FAQ flow.",
"lastVia": {
"kind": "api_key",
"keyRef": "sk_live_4f2a",
"keyName": "CRM sync"
},
"proposedVia": {
"kind": "api_key",
"keyRef": "sk_live_4f2a",
"keyName": "CRM sync"
},
"updatedAt": "2026-10-28T09:15:00.000Z",
"valueKeys": [
"ORDER_ID"
]
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}{
"code": 8409,
"message": "Your draft changed in another tab or through your API key. Reload it and try again.",
"messageKey": "DraftStaleRevision",
"params": {
"reason": "STALE_REVISION",
"revision": "e2f7a9c3-6b1d-4e5f-a8c2-7d3b9f0e1a56"
}
}Authorizations
Headers
Optional, up to 255 characters. Retry with the same key after a network error and you get the first answer back instead of the change being made twice (kept 10 minutes). Same key with a different body: 422 IdempotencyKeyReused. While the first request still runs: 409 IdempotencyKeyInProgress.
Maximum string length:
255Example:
"0b6f3c1e-retry-1"
Path Parameters
Body
application/json
Was this page helpful?