Skip to main content
Use an inbox to find conversations, a message to reply to one fan, and a mass message to send to a group or schedule delivery.

Choose how to send

A mass message enters a queue before delivery. Save the returned id and use it to check progress.

Before you start

Ask the user to authorize your app with messages:read and messages:write. These permissions let your app read and send messages. Select a linked account. Install the TypeScript SDK version 4. Create a client on your server:

Read conversations

Read the unread inbox and show the conversations to the person using your app:
Each chat’s user.id is the fan’s OnlyFans user ID. The linked account ID in the header selects your creator account. Keep these IDs separate. The linked account ID selects the creator. The fan's OnlyFans user ID selects the conversation recipient. For an inbox with more pages, pass page.nextCursor as cursor while page.hasMore is true. Keep the inbox and filters unchanged. Use /chats for all conversations, /chats/priority for priority conversations, or /chats/with-tips for conversations with tips. To show names and avatars without looking each fan up, add include_users=true: each chat’s user and lastMessage.sender then come with their profile. Without it they are { id } references. See the API reference for search and user-list filters.

Read messages and media

After the person using your app selects a fan, read that conversation. Here, 123456 stands for that selected ID:
The response is { items, page }. Each message includes id, text, sender, and media. Follow page.nextCursor for older messages while page.hasMore is true. Show the messages so the person can choose one and write a reply. For attachments, follow Display media. You can also read shared conversation media in pages. See the API reference.

Send messages

Use the selected message’s id as the string replyToMessageId. This example uses 987654 as the selected incoming message ID:
The response contains the created message. Save reply.id with the recipient and your reply record before allowing another send. You have finished when that record contains the message ID. This example sends only the reply the person chose. If the request times out or you do not know whether it succeeded, stop. Check recent messages and follow V3 error recovery before trying again. OnlyFans may have sent the reply even if you did not receive the response. An automatic retry can send it twice. For paid attachments, preview ordering, locked text, and release forms for people in the media, follow Send a message. Use Text formatting for supported syntax and Media references for attachment formats.

Manage messages and conversations

Use returned IDs when deleting messages or changing a conversation. Check the response before updating your app. The API reference covers how to like, pin, mark as read, mute, or hide messages and conversations.

Send to multiple fans

Follow Send a mass message to target fans or user lists, schedule delivery, inspect buyers, or cancel a campaign. Save the queue ID and use it to check progress. Do not send the message again to check its status.

Build messaging workflows

For incoming activity, use Realtime events to update the inbox. Use each event ID only once when adding replies to your app’s task list. If you add automated welcomes, save the returned message ID per fan so a repeated event does not create another welcome.