> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Messaging and chats

> Choose an inbox, reply to a fan, or send a campaign

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

| Your goal | Start here | Access |
| - | - | - |
| Build an inbox | Read conversations below | `messages:read` |
| Send to a known fan now | [Send a message](https://docs.ofauth.com/v3/guides/how-to/send-message.md) | `messages:write` |
| Read context and reply | Follow the workflow below | `messages:read` and `messages:write` |
| Target several fans or lists, or schedule delivery | [Send a mass message](https://docs.ofauth.com/v3/guides/how-to/mass-message.md) | Check the guide’s required permissions |

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](https://docs.ofauth.com/v3/guides/link.md) with `messages:read` and `messages:write`. These permissions let your app read and send messages. Select a [linked account](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md). Install the [TypeScript SDK](https://docs.ofauth.com/v3/sdk/typescript.md) version 4. Create a client on your server:

```typescript theme={null}
import { OFAuthClient } from "@ofauth/onlyfans-sdk"

const client = new OFAuthClient({
	accessToken: process.env.ACCESS_TOKEN!,
	linkedAccountId: process.env.LINKED_ACCOUNT_ID!
})
```

## Read conversations

Read the unread inbox and show the conversations to the person using your app:

```typescript theme={null}
const chats = await client.access.chats.listUnread({ limit: 20, order: "recent" })
console.log(chats.items.map(chat => ({ userId: chat.user.id })))
```

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.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/message-participants.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=937a2d02e52a7f84ec0def86398baaae)

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](https://docs.ofauth.com/v3/api-reference.md) 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:

```typescript theme={null}
const userId = 123456
const history = await client.access.chats.messages.list({ userId, limit: 10 })
console.log(history.items.map(({ id, text }) => ({ id, text })))
```

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](https://docs.ofauth.com/v3/guides/display-media.md). You can also read shared conversation media in pages. See the [API reference](https://docs.ofauth.com/v3/api-reference.md).

## Send messages

Use the selected message's `id` as the string `replyToMessageId`. This example uses `987654` as the selected incoming message ID:

```typescript theme={null}
const reply = await client.access.chats.messages.send({
	userId,
	body: {
		text: "Thanks! I'll include that in the next set.",
		replyToMessageId: "987654"
	}
})
console.log({ userId, messageId: reply.id, text: reply.text })
```

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](https://docs.ofauth.com/v3/api-reference/errors.md) 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](https://docs.ofauth.com/v3/guides/how-to/send-message.md). Use [Text formatting](https://docs.ofauth.com/v3/guides/how-to/text-formatting.md) for supported syntax and [Media references](https://docs.ofauth.com/v3/guides/media-items.md) 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](https://docs.ofauth.com/v3/api-reference.md) covers how to like, pin, mark as read, mute, or hide messages and conversations.

## Send to multiple fans

Follow [Send a mass message](https://docs.ofauth.com/v3/guides/how-to/mass-message.md) to target fans or [user lists](https://docs.ofauth.com/v3/guides/fans.md), 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](https://docs.ofauth.com/v3/guides/realtime-onlyfans-events.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.