Handle hand-offs

A hand-off is the AI chatter deciding that a person should take a conversation: a fan in distress, a refund demand, a request to meet, something it must not handle. When it hands off, the conversation’s status becomes handoff, the AI stops replying in that chat, and a hand-off record explains why. The fan waits until your team acts, so hand-offs are the most time-sensitive items in the inbox. Scopes: inbox:read to list and read; inbox:write to resolve; messages:send to reply.

Why the AI hands off

Every hand-off has a reason and a human-readable label:

`reason`	Examples of `label`	Urgency
`welfare`	Suicidal or self-harm language; In danger right now; Ill or in medical trouble	Highest. Answer within minutes.
`prohibited_request`	Anyone under 18; Force or non-consent; Animals or anything illegal	Highest. Do not continue the topic.
`real_world`	Asks to meet; Claims to know where she lives; Fishing for her location	High
`payment_dispute`	Asks for a refund; Chargeback or fraud threat; Paid and got nothing	High: money and account standing
`whale_risk`	A regular is upset; Unusually large money	High: a top spender
`custom_request`	A custom she does not make; Wants her voice	Normal
`confusion`	Refers to something you have no context for	Normal
`failed_delivery`	A paid message could not be delivered (raised automatically)	Normal

Which situations hand off is configured per creator with handoffKinds in the AI persona. Self-harm language and anything involving someone under 18 always hand off.

List open hand-offs

GET /v1/handoffs returns the open hand-offs across every creator the key can see, oldest first (the fan who has waited longest comes first). Add creatorId for one creator; a creator the key cannot see is 404 CREATOR_NOT_FOUND. Page with limit (1 to 100, default 25) and cursor.

curl "https://api.onlyx.ai/v1/handoffs?creatorId=cre_5f2d9a1c7b3e4f60a2d1" \
  -H "Authorization: Bearer $ONLYX_API_KEY"

import os, requests

API = "https://api.onlyx.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONLYX_API_KEY']}"}

handoffs = requests.get(f"{API}/handoffs", headers=HEADERS, timeout=30).json()["data"]
for h in handoffs:
    print(h["createdAt"], h["reason"], h["label"], "-", h["fanName"], h["conversationId"])

const API = "https://api.onlyx.ai/v1";
const headers = { Authorization: `Bearer ${process.env.ONLYX_API_KEY}` };

const { data: handoffs } = await (await fetch(`${API}/handoffs`, { headers })).json();
for (const h of handoffs) console.log(h.createdAt, h.reason, h.label, "-", h.fanName, h.conversationId);

Response 200

{
  "data": [
    {
      "id": "esc_6d8f0a2c4e6b8d0f2a4c",
      "conversationId": "cnv_9f2c41d7a8b35e06c1f4",
      "creatorId": "cre_5f2d9a1c7b3e4f60a2d1",
      "fanName": "Jake",
      "reason": "payment_dispute",
      "label": "Asks for a refund",
      "note": "Says the video he bought yesterday will not play and wants his money back.",
      "status": "open",
      "createdAt": "2026-09-26T12:40:18.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Field	Meaning
`conversationId`	The chat to open
`fanName`	The fan’s display name, for your notification
`reason`, `label`	Why, as a stable code and as a readable label
`note`	A short explanation written when the hand-off was raised, describing what the fan said or did, or `null`
`createdAt`	When the hand-off was raised (`null` if unknown)
`status`	`open` or `resolved`

You can also find these chats with GET /v1/conversations?status=handoff, and GET /v1/conversations/{conversationId} includes the open hand-off in its handoff field.

Work a hand-off

Read the conversation

Fetch the conversation and its latest messages (GET /v1/conversations/{conversationId}/messages). Read the note, then the fan’s own words.

Take over, if you need time

The AI is already silent in a handoff chat. If you want to keep it silent after you resolve, take the chat over first (POST /v1/conversations/{conversationId}/takeover), or simply reply: a reply from your team moves the chat to team for 12 hours.

Reply to the fan

Send your answer with POST /v1/conversations/{conversationId}/messages (with an Idempotency-Key). See Read and send messages. For welfare hand-offs, answer as a caring person, not as a salesperson.

Resolve the hand-off

POST /v1/conversations/{conversationId}/handoff/resolve closes it and returns the resolved hand-off (its note is your resolution note when you send one). Add an optional note (up to 300 characters) saying what you did; the body itself is optional. A conversation with no open hand-off answers 404 NOT_FOUND, so resolving twice is harmless. While sending through the API is switched off, resolving is refused with 503 SENDING_DISABLED, because it can hand the chat back to the AI.

If the chat is still in handoff when you resolve it (nobody replied or took it over), it goes back to the AI immediately, and the AI may answer the fan’s waiting message within seconds. If your team already replied, the chat stays with your team until its hold ends, and resolving only closes the record.

curl -X POST https://api.onlyx.ai/v1/conversations/cnv_9f2c41d7a8b35e06c1f4/handoff/resolve \
  -H "Authorization: Bearer $ONLYX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0d2f4a6c-8e1b-4d3f-a5c7-9e1b3d5f7a9c" \
  -d '{"note": "Re-sent the video as a free message; fan confirmed it plays."}'

import uuid

h = requests.post(
    f"{API}/conversations/cnv_9f2c41d7a8b35e06c1f4/handoff/resolve",
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json={"note": "Re-sent the video as a free message; fan confirmed it plays."},
    timeout=30,
).json()
print(h["status"])  # resolved

const h = await (await fetch(`${API}/conversations/cnv_9f2c41d7a8b35e06c1f4/handoff/resolve`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID() },
  body: JSON.stringify({ note: "Re-sent the video as a free message; fan confirmed it plays." }),
})).json();
console.log(h.status); // resolved

Response 200

{
  "id": "esc_6d8f0a2c4e6b8d0f2a4c",
  "conversationId": "cnv_9f2c41d7a8b35e06c1f4",
  "creatorId": "cre_5f2d9a1c7b3e4f60a2d1",
  "fanName": "Jake",
  "reason": "payment_dispute",
  "label": "Asks for a refund",
  "note": "Re-sent the video as a free message; fan confirmed it plays.",
  "status": "resolved",
  "createdAt": "2026-09-26T12:40:18.000Z"
}

Example: alert your team about new hand-offs

Poll every minute and post new hand-offs to your team chat. The most urgent reasons go first.

Python

import os, time, requests

API = "https://api.onlyx.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['ONLYX_API_KEY']}"}  # scopes: inbox:read
URGENT = {"welfare", "prohibited_request", "real_world", "payment_dispute", "whale_risk"}
seen = set()

def notify(text):
    # Replace with your Slack, Telegram or email call.
    print(text)

while True:
    r = requests.get(f"{API}/handoffs", headers=HEADERS, timeout=30)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "30")))
        continue
    r.raise_for_status()
    fresh = [h for h in r.json()["data"] if h["id"] not in seen]
    for h in sorted(fresh, key=lambda h: h["reason"] not in URGENT):
        flag = "URGENT " if h["reason"] in URGENT else ""
        notify(f"{flag}{h['label']}: {h['fanName']} ({h['creatorId']}) - {h['note']} "
               f"https://app.onlyx.ai (conversation {h['conversationId']})")
        seen.add(h["id"])
    time.sleep(60)

From your AI assistant

With the MCP server connected, ask: “Are there any open hand-offs? Summarize each and suggest a reply.” The assistant uses list_handoffs and list_messages, drafts replies, and only sends or resolves (send_message, resolve_handoff) after you confirm, because both can reach the fan.

Hugo, the AI chatter: every hand-off reason.
AI persona: choose which situations hand off.
Conversations: what happens to a chat after a hand-off.

Get started

Guides

Reference topics

Why the AI hands off

List open hand-offs

Work a hand-off

Example: alert your team about new hand-offs

From your AI assistant

​Why the AI hands off

​List open hand-offs

​Work a hand-off

​Example: alert your team about new hand-offs

​From your AI assistant

​Related

Why the AI hands off

List open hand-offs

Work a hand-off

Example: alert your team about new hand-offs

From your AI assistant

Related