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

# How Do I Read and Send OnlyFans Messages Through an API?

> Read and send OnlyFans messages through an API with OFAuth: messages:read and messages:write scopes, list chats, send a message, and get Realtime events.

To read and send OnlyFans messages through an API, use OFAuth's typed Access operations: `GET /v3/access/chats` lists chats, `GET /v3/access/chats/{userId}/messages` reads a chat, and `POST /v3/access/chats/{userId}/messages` sends a message. Reading needs the `messages:read` scope and sending needs `messages:write`. Every call carries a bearer token and an `x-linked-account-id` header for the account you are acting on.

OnlyFans has no public messaging API. OFAuth is an independent platform, not affiliated with OnlyFans. The account owner, a creator or an agency, approves your scopes on the OFAuth consent screen before you can touch their inbox.

## Frequently Asked Questions

**Which scopes do I need to read and send OnlyFans messages?** `messages:read` reads chats, messages, chat media, mass messages, and templates. `messages:write` sends, deletes, pins, and likes messages, mutes or hides chats, and sends mass messages.

**How do I get notified of new OnlyFans messages?** Turn on Realtime events for a webhook destination. New chat messages arrive as `realtime.chat_message.received`. You can also open a Realtime stream (Server-Sent Events) for one linked account.

**What is the rate limit?** 600 requests per minute per authorization, shared across `/v3/access`, `/v3/vault-plus`, and `/v3/linked-accounts`, with short bursts allowed. Above it, calls return `429` `rate_limited`.

**Can one token send messages for several creators?** Yes, if the owner shared several linked accounts in one authorization. Select the intended account with `x-linked-account-id`. Each account must have the permission needed by the operation.

## How do I request messaging scopes?

Add the scopes to the authorization request. Every successful code exchange includes a refresh token.

```ts theme={null}
const scope = "profile:read messages:read messages:write"
```

If you already have an authorization without `messages:write`, run the authorization flow again with the larger scope set. The `authorization_id` stays the same. Until then, sends fail with `403` `missing_scope` or `additional_consent_required`, both with `recovery.action` `request_additional_consent`.

## How do I list chats and read messages?

Use the [version 4 SDK](https://docs.ofauth.com/v3/sdk/typescript.md) for typed message operations with tokens supplied by your auth system. The HTTP helper below shows the request headers and error fields when you call the API directly. Supply its token through your coordinated token provider; do not build a second refresh path.

```ts ofauth-messages.ts theme={null}
const API = "https://api.ofauth.com/v3/access"

export async function access(
  accessToken: string,
  linkedAccountId: string,
  path: string,
  init: RequestInit = {}
) {
  const response = await fetch(`${API}${path}`, {
    ...init,
    headers: {
      authorization: `Bearer ${accessToken}`,
      "x-linked-account-id": linkedAccountId,
      "content-type": "application/json",
      ...init.headers
    }
  })
  if (!response.ok) {
    const body = await response.json()
    const error = new Error(body.error) as Error & { action?: string; requestId?: string; retryAfter?: string | null }
    error.action = body.recovery?.action
    error.requestId = body.requestId
    error.retryAfter = response.headers.get("RateLimit-Reset")
    throw error
  }
  return response.json()
}

export async function listChats(accessToken: string, linkedAccountId: string) {
  return access(accessToken, linkedAccountId, "/chats?limit=20")
}

export async function readChat(accessToken: string, linkedAccountId: string, userId: string) {
  return access(accessToken, linkedAccountId, `/chats/${userId}/messages`)
}
```

`{userId}` identifies the chat. Chat media for one chat is at `GET /v3/access/chats/{userId}/media`, also under `messages:read`. Check the operation reference for each response shape and pagination parameters.

## How do I send a message?

`POST` a JSON body with `text` to the chat's messages route.

```ts theme={null}
import { access } from "./ofauth-messages"

export async function sendMessage(
  accessToken: string,
  linkedAccountId: string,
  userId: string,
  text: string
) {
  return access(accessToken, linkedAccountId, `/chats/${userId}/messages`, {
    method: "POST",
    body: JSON.stringify({ text })
  })
}
```

Do not retry a send blindly. If OnlyFans rejects the request, the error is `provider_request_rejected` with `recovery.action` `do_not_repeat` or `check_request`. Follow retry actions and timing only after checking whether the message was created.

Mass messages use a separate operation, `POST /v3/access/chats/mass-messages`, under `messages:write`.

## How do I receive new messages in real time?

Polling the chat list wastes your rate limit. Use Realtime events instead:

1. In the dashboard, add a webhook destination for the environment and turn on **Send Realtime events**.
2. Verify each delivery with the Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`).
3. Route on `type === "realtime.chat_message.received"` and use `linkedAccountId` to find the account.

```ts theme={null}
async function onRealtimeEvent(event: any) {
  if (event.type !== "realtime.chat_message.received") return
  // event.data.eventBody holds the translated OnlyFans payload.
  await saveIncomingMessage(event.linkedAccountId, event.order, event.data)
}
```

Realtime events require the linked account to be `connected`. Deduplicate on `eventId` and order by `order`. For one account in a live UI, create a stream URL on your server with `POST /v3/realtime` and open it in the page with `new EventSource(url)` ([Realtime from the browser](https://docs.ofauth.com/v3/guides/realtime-browser.md)).

## How do I stay under the rate limit?

Responses carry `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. When you get `429` `rate_limited`, back off until `RateLimit-Reset` and retry. In Test, a separate daily quota applies and returns `429` `quota_exhausted` with `Retry-After`.

## Learn More

* [Calling Access](https://docs.ofauth.com/v3/api-reference.md)
* [Webhooks](https://docs.ofauth.com/v3/api-reference/webhooks.md)
* [Errors](https://docs.ofauth.com/v3/api-reference/errors.md)
* [Realtime OnlyFans Events](https://docs.ofauth.com/v3/api-reference/realtime/onlyfans-events.md)
* [How Do I Receive OnlyFans Webhooks?](https://docs.ofauth.com/v3/agents/playbooks/onlyfans-webhooks.md)
* [How Do I Call the OnlyFans API from Python?](https://docs.ofauth.com/v3/agents/playbooks/python-onlyfans-api.md)
* [Is There an Official OnlyFans API?](https://docs.ofauth.com/v3/agents/playbooks/is-there-an-official-onlyfans-api.md)


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