Conversations

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.
`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.

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

Conversation

{
  "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 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.

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):

{ "total": 1912, "ai": 1733, "team": 141, "handoff": 3, "aiOff": 35, "unread": 14 }

Read and send messages: every call on this page, with examples.
Hand-offs: what the AI hands off and how to resolve it.
Hugo, the AI chatter: how the AI decides what to say and sell.

Get started

Guides

Reference topics

Status: who answers this chat

Taking over and releasing

Turning the AI off for one chat

Unread

The Conversation object

Messages

Finding conversations

​Status: who answers this chat

​Taking over and releasing

​Turning the AI off for one chat

​Unread

​The Conversation object

​Messages

​Finding conversations

​Related

Status: who answers this chat

Taking over and releasing

Turning the AI off for one chat

Unread

The Conversation object

Messages

Finding conversations

Related