Skip to main content
POST
/
api
/
v1
/
iframes
/
{id}
/
conversations
/
{sessionId}
/
takeover
Take Over Session
curl --request POST \
  --url https://api.example.com/api/v1/iframes/{id}/conversations/{sessionId}/takeover
{
  "session_id": "<string>",
  "takeover_status": "<string>",
  "taken_over_by": "<string>",
  "taken_over_at": "<string>"
}
Marks the session as human-driven so the widget stops generating AI replies. Idempotent — repeated calls just refresh the takeover timestamp. Hand control back with Release.

​
Authentication

Requires a Bearer token (API key) or a dashboard session.

​
Path Parameters

​
id
string
required
The widget config UUID.
​
sessionId
string
required
The session UUID.

​
Response

​
session_id
string
​
takeover_status
string
"human" after a successful takeover.
​
taken_over_by
string
The operator user ID.
​
taken_over_at
string
ISO timestamp of the takeover.

​
Example

curl
curl -X POST https://www.hitheo.ai/api/v1/iframes/CONFIG_ID/conversations/SESSION_ID/takeover \
  -H "Authorization: Bearer $THEO_API_KEY"