> ## Documentation Index > Fetch the complete documentation index at: https://help.onlyx.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > You are reading OnlyX Help: the OnlyX Help Center and the OnlyX developer documentation. OnlyX is an AI chatting and CRM platform for OnlyFans agencies. Its AI chatter is called Hugo in the app. > Pages at the site root (for example /inbox/..., /hugo/..., /billing/...) are Help Center articles for agency owners, admins, chatters and creators who use the app at app.onlyx.ai. Words in bold are the exact button, menu and label names the app shows; keep them exactly as written. When these pages do not answer a question, the person can email support at support@onlyx.ai. > Pages under /developers are the developer documentation. REST API base URL: https://api.onlyx.ai/v1 (authenticate with `Authorization: Bearer `; keys start with onx_sk_ and are created in app.onlyx.ai under Settings > API & MCP). MCP server: https://mcp.onlyx.ai/mcp (OAuth, or a Bearer API key). In the API the AI chatter is `ai` on the wire. Money is integer US cents in fields ending in Cents; timestamps are UTC ISO-8601. > Rules for assistants acting on a user's behalf: discover ids with list calls and never invent them; before any call that reaches a real fan or the live OnlyFans account (sending a message, releasing a chat to the AI, turning AI on for a chat, resolving a hand-off, turning review mode off, changing the welcome message, creating a tracking link) show the user the exact content and get explicit confirmation; send every POST with an Idempotency-Key and reuse it on retry; never resend a message whose delivery status is unconfirmed; never ask a creator for her OnlyFans password or codes - she signs in herself through a connect link and the OnlyX Login app. # Conversations > One chat between a creator and a fan. Its status says who answers it: the AI, your team, a hand-off, or nobody automatic. A **conversation** is the chat between one creator and one fan, the same thread you see in the OnlyFans inbox. Its id starts with `cnv_`. Each conversation holds **messages** (`msg_...`) in both directions. ## Status: who answers this chat Every conversation has exactly one `status`: | Status | Who answers the fan | How a chat gets here | | - | - | - | | `ai` | Hugo, the AI chatter, in the creator's voice | New chats start here when the creator's AI is on. Chats return here after a release, after a hand-off is resolved, or when a take-over expires. | | `team` | Your people (or your integration). The AI stays out. | Someone sent a message in an `ai` or `handoff` chat, or took the chat over. New chats start here when the creator's AI is off. | | `handoff` | Nobody yet. The AI asked for a human and stopped replying in this chat. | The AI handed the chat off: a safety concern, a payment dispute, a request it should not handle. See [Hand-offs](/developers/guides/handoffs). | | `ai_off` | Your people. The AI never replies in this chat until someone turns it back on. | Someone turned the AI off for this chat. There is no timer. | ```mermaid theme={"system"} stateDiagram-v2 ai --> team: your team sends or takes over team --> ai: release, or the take-over expires ai --> handoff: the AI hands off handoff --> ai: hand-off resolved handoff --> team: your team sends or takes over ai --> ai_off: AI turned off for this chat team --> ai_off: AI turned off for this chat ai_off --> ai: AI turned on for this chat ``` ### Taking over and releasing * **Sending a message** in an `ai` or `handoff` chat moves it to `team` for **12 hours**, so the AI does not talk over you. Any follow-ups the AI had scheduled in that chat are cancelled. * **Take over** (`POST /v1/conversations/{conversationId}/takeover`) does the same without sending, and the AI withdraws any reply it had waiting in the chat. Pass `holdMinutes` between 15 and 1440 (default 720, which is 12 hours). Taking over a chat your team already holds restarts the hold. `takenOverUntil` shows when the hold ends. * When the hold ends, the chat goes back to `ai` by itself (if the creator's AI is on). * **Release** (`POST /v1/conversations/{conversationId}/release`) hands the chat back to the AI now. If the fan's last message is still unanswered, **the AI may reply to it immediately**. If the creator's AI is off, the chat stays with your team. ### Turning the AI off for one chat `PUT /v1/conversations/{conversationId}/ai` with `{"enabled": false}` moves the chat to `ai_off`. Use it for a fan your team wants to handle personally for good, such as a VIP or a sensitive situation. `{"enabled": true}` puts the chat back to `ai`, and the AI may answer the fan's waiting message right away. Release, turning the AI on for a chat, and resolving a hand-off can each make the AI send a message to the fan within seconds. Treat them like a send: confirm first. ## Unread `unreadCount` counts fan messages nobody has read in OnlyX yet. It changes when: * a fan writes (it goes up); * you call `POST /v1/conversations/{conversationId}/read` (it goes to 0); * you call `POST /v1/conversations/{conversationId}/unread` to flag the chat for later (it becomes 1). Sending a message through the API does not change it: mark the chat read yourself when your team has dealt with it. Read state lives in OnlyX only. Marking a chat read does **not** send a read receipt to the fan on OnlyFans. ## The Conversation object ```json Conversation theme={"system"} { "id": "cnv_9f2c41d7a8b35e06c1f4", "creatorId": "cre_5f2d9a1c7b3e4f60a2d1", "fan": { "id": "fan_3b7e9d2a1c5f48e06b92", "displayName": "Jake", "username": "jake_91", "avatarUrl": "https://..." }, "status": "team", "unreadCount": 0, "lastMessage": { "text": "haha ok deal", "direction": "in", "at": "2026-09-26T14:10:40.000Z" }, "lastMessageAt": "2026-09-26T14:10:40.000Z", "takenOverUntil": "2026-09-27T02:02:31.000Z", "totalSpentCents": 48500 } ``` | Field | Meaning | | - | - | | `fan` | Who the creator is talking to. `displayName` is the custom name your team gave them, else their OnlyFans name; `username` and `avatarUrl` are their OnlyFans username and avatar when known. | | `status` | `ai`, `team`, `handoff` or `ai_off`, as above. | | `lastMessage` | The newest message: its text (shortened for a preview), `direction` (`in` from the fan, `out` to the fan) and time (`at`). `null` for an empty chat. | | `unreadCount` | Fan messages not yet marked read in OnlyX. | | `takenOverUntil` | While `status` is `team`: when the take-over or team send stops holding the chat. Otherwise `null`. | | `totalSpentCents` | Everything this fan has spent with this creator. | `GET /v1/conversations/{conversationId}` returns the same fields plus: * `fan`: the full [Fan](/developers/guides/fans) object (notes, subscription, spend, lists, `salesOptOut`); * `handoff`: the open hand-off, if the chat is in `handoff` (otherwise `null`); * `aiCanReply`: whether the AI would answer this chat right now. It is `true` only when the creator's AI is on and set up, the chat is `ai`, and the creator is connected. A conversation the key cannot see (another workspace's, or a creator outside the key's restriction) is `404 CONVERSATION_NOT_FOUND`, exactly like an id that does not exist. ## Messages Messages come oldest to newest. Each has a `direction` (`in` or `out`) and a `sender`: | `sender` | Who wrote it | | - | - | | `fan` | The fan | | `ai` | The AI chatter | | `team` | Your team, from the dashboard or through the API | A message can carry media (`media[]`, each marked `preview: true` if the fan sees it free), a price (`paid`, with `purchased` once the fan unlocks it), and a tip (`tipCents`). Outgoing messages carry `delivery`, which tracks whether OnlyFans accepted them. The delivery states and sending rules are in [Read and send messages](/developers/guides/read-and-send-messages). ## Finding conversations `GET /v1/conversations` filters by `creatorId`, `status`, `unread`, and a text search `q` (fan names), sorts by `recent` (default), `spend`, `unread` or `name`, and pages with `limit` (1 to 50, default 25) and `cursor`. `GET /v1/conversations/counts` returns the numbers for each status at once, handy for a dashboard (it has its own limit of 30 calls per 60 seconds per key): ```json theme={"system"} { "total": 1912, "ai": 1733, "team": 141, "handoff": 3, "aiOff": 35, "unread": 14 } ``` ## Related * [Read and send messages](/developers/guides/read-and-send-messages): every call on this page, with examples. * [Hand-offs](/developers/guides/handoffs): what the AI hands off and how to resolve it. * [Hugo, the AI chatter](/developers/concepts/hugo-ai): how the AI decides what to say and sell.