Concepts

Human Takeover

Sometimes the right answer is a real person. Human takeover lets one of your operators step into a live AI conversation: the bot pauses its AI, the operator sends messages the end-user sees as one continuous assistant voice, and when they're done they hand the thread back to the AI — no context lost.

The concept

A takeover is a session over one end-user's conversation. While it's active, Humane suppresses the AI for that user and delivers the operator's messagesinstead. The end-user doesn't see a hand-off seam — to them it's the same assistant, now being driven by a human. The lifecycle is deliberately small:

• start — an operator claims the conversation (first operator wins).
• drafts — optional: ask the AI co-pilot for reply suggestions.
• send — inject an operator-authored turn into the live thread.
• release — hand the conversation back to the AI.

The SDK flow

The Python SDK exposes the whole lifecycle under client.takeover: start → drafts → send → release.

from humane_ai import HumaneClient

with HumaneClient(api_key="hx_...") as client:
    # 1. An operator steps in. Returns the active TakeoverSession.
    session = client.takeover.start(
        user_id="u_8f2",
        operator_id="op_1",
        operator_name="Dana",
        operator_avatar_url=None,   # optional
        idle_minutes=30,            # optional auto-release window
    )

    # 2. Ask the AI co-pilot for reply options (best-effort; may return []).
    options = client.takeover.drafts("u_8f2", count=3, guidance="keep it warm")

    # 3. Send an operator-authored turn — the end-user sees this as the assistant.
    client.takeover.send("u_8f2", body=options[0] if options else "Hey, it's Dana — I'm here.")

    # Is a session still active? (None when no operator is steering.)
    active = client.takeover.get("u_8f2")   # TakeoverSession | None

    # 4. Hand back to the AI.
    client.takeover.release("u_8f2", handback_message="Handing you back to the assistant 💚")

The /process contract during takeover

Here's the part that matters for your bot. When a takeover is active and a new user message arrives, your /process call does not generate an AI reply. Instead the response carries three takeover-specific keys, and your bot must render the operator's messages instead of generating anything:

{
  "response": null,
  "suppress_ai": true,
  "takeover": {
    "session_id": "1f2e…",
    "state": "active",
    "operator_id": "op_1",
    "operator_name": "Dana",
    "started_at": "2026-06-02T14:22:10Z",
    "idle_release_at": "2026-06-02T14:52:10Z"
  },
  "pending_operator_messages": [
    { "message_id": "9a…", "body": "Hey, it's Dana — I'm here.", "created_at": "2026-06-02T14:22:30Z" }
  ],
  "user": {
    "id": "u_8f2",
    "mood": 0.31, "energy": 0.42, "trust": 0.55,
    "sentiment": 0.38, "familiarity": 0.60,
    "interaction_count": 7
  }
}

The contract, precisely:

• suppress_ai: true — the signal to your bot: do not generate an AI reply for this turn.
• response is null — no AI ran, so there is nothing to show from the model.
• takeover — who is steering and since when. Render an "a human is replying" affordance if you like.
• pending_operator_messages — the operator turns to deliver to the end-user, in order. Render these instead of an AI reply.

# Inside your bot's message handler:
r = client.process(user_id="u_8f2", message=incoming_text)
raw = r.raw   # the full JSON dict

if raw.get("suppress_ai"):
    for m in raw.get("pending_operator_messages", []):
        deliver_to_user(m["body"])      # render the operator's words as the assistant
else:
    deliver_to_user(r.response)         # normal AI reply

REST endpoints (non-Python)

Not on Python? The lifecycle is four endpoints under /api/sdk, all authenticated with X-API-Key. The {user_id} path segment is your external end-user id — the same one you pass to observe / process.

curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2 \
  -H "Content-Type: application/json" -H "X-API-Key: hx_..." \
  -d '{ "operator_id": "op_1", "operator_name": "Dana" }'

{
  "id": "1f2e…",
  "end_user_id": "8c…",
  "operator_id": "op_1",
  "operator_name": "Dana",
  "state": "active",
  "started_at": "2026-06-02T14:22:10Z",
  "idle_release_at": "2026-06-02T14:52:10Z",
  "released_at": null
}

curl -H "X-API-Key: hx_..." https://humaneai.vaarak.com/api/sdk/takeover/u_8f2

curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2/messages \
  -H "Content-Type: application/json" -H "X-API-Key: hx_..." \
  -d '{ "body": "Hey, it'\''s Dana — I'\''m here." }'

{ "message_id": "9a…", "created_at": "2026-06-02T14:22:30Z" }

curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2/release \
  -H "Content-Type: application/json" -H "X-API-Key: hx_..." \
  -d '{ "handback_message": "Handing you back to the assistant." }'

curl -X POST https://humaneai.vaarak.com/api/sdk/takeover/u_8f2/drafts \
  -H "Content-Type: application/json" -H "X-API-Key: hx_..." \
  -d '{ "count": 3, "guidance": "reassure them about pricing" }'

{ "drafts": ["I totally get the concern…", "Happy to walk you through it…", "No pressure at all…"] }

Webhook events

Every lifecycle step fires a webhook so your other systems (and the dashboard live-feed) learn of it. Each payload carries your external user_id so you can correlate without an id mapping.

Full payload shapes are in the Webhook Events reference.