> ## 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 & Chats

> Send messages, manage conversations, and mass message at scale

## What You Can Build

* **AI Chatbots**: Automated fan interactions and response management
* **CRM Systems**: Message history, conversation tracking, fan engagement tools
* **Mass Messaging**: Send promotions, updates, or PPV content to multiple fans
* **Chat Analytics**: Message volume, response times, engagement metrics

***

## Quick Example

Send a message to a fan:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/messages", {
    method: "POST",
    headers: {
      apikey: "YOUR_API_KEY",
      "x-connection-id": "conn_abc123",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      text: "Hey! Thanks for subscribing 💕"
    })
  })

  const message = await response.json()
  console.log("Message sent:", message.id)
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.ofauth.com/v2/access/chats/123456/messages",
      headers={
          "apikey": "YOUR_API_KEY",
          "x-connection-id": "conn_abc123",
          "Content-Type": "application/json"
      },
      json={
          "text": "Hey! Thanks for subscribing 💕"
      }
  )
  print("Message sent:", response.json()["id"])
  ```
</CodeGroup>

***

## Common Operations

### List Chats

Get a list of all conversations:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/chats?" + new URLSearchParams({
  limit: "10",
  offset: "0",
  order: "recent"  // "recent" | "old"
}), {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const chats = await response.json()
// Returns array of chat objects with last message, fan info, etc.
```

### Filter Chats

```javascript theme={null}
// Priority chats only
const priority = await fetch(
  "https://api.ofauth.com/v2/access/chats?filter=priority",
  { headers }
)

// Unread chats
const unread = await fetch(
  "https://api.ofauth.com/v2/access/chats?filter=unread",
  { headers }
)

// Fans who tipped
const tippers = await fetch(
  "https://api.ofauth.com/v2/access/chats?filter=who_tipped",
  { headers }
)
```

### Get Chat Messages

Fetch messages from a specific conversation:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/messages?" + new URLSearchParams({
  limit: "20",
  offset: "0"
}), {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const messages = await response.json()
```

### Get Chat Media

Retrieve media shared in a specific conversation:

```javascript theme={null}
// Get all media from a chat
const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/media", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

// Or filter by type: photos, videos, or audios
const photos = await fetch("https://api.ofauth.com/v2/access/chats/123456/media?type=photos", {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const media = await response.json()
```

| Parameter    | Type   | Description                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `type`       | string | Filter by media type: `photos`, `videos`, or `audios`. Omit for all media. |
| `limit`      | number | Results per page                                                           |
| `skip_users` | string | Skip user data in response                                                 |

### Send Message with Media

Include images or videos in your message:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/messages", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Check this out! 🔥",
    mediaItems: [789, 790] // Media IDs from vault
  })
})
```

### Send PPV Message

Send pay-per-view content:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/messages", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Exclusive content just for you 💋",
    mediaItems: [789],
    price: 9.99,  // $3-$200
    previewMediaCount: 1  // First 1 item in mediaItems (left to right) is preview
  })
})
```

### Delete a Message

Delete a sent message:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/chats/123456/messages/MESSAGE_ID", {
  method: "DELETE",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

***

## Mass Messaging

Send to multiple fans at once using the mass messaging endpoints:

### Create Mass Message

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/mass-messages", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "New content dropping tomorrow! 🎉",
    userIds: [123, 456, 789],
    // Or target by lists:
    // userLists: [1, 2, 3],
    // excludeUserLists: [4, 5]  // Exclude specific lists
  })
})
```

### Schedule Mass Message

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/mass-messages", {
  method: "POST",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Scheduled announcement! 📅",
    userLists: [1],
    scheduledDate: "2024-12-25T12:00:00Z"
  })
})
```

### List Sent Mass Messages

View sent mass message stats:

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/analytics/mass-messages/sent?" + new URLSearchParams({
  limit: "20",
  startDate: "2024-01-01",
  endDate: "2024-12-31"
}), {
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})

const massMessages = await response.json()
```

### Update Mass Message

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/mass-messages/MASS_MESSAGE_ID", {
  method: "PUT",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Updated message content!",
    userIds: [123, 456]
  })
})
```

### Delete Mass Message

```javascript theme={null}
const response = await fetch("https://api.ofauth.com/v2/access/mass-messages/MASS_MESSAGE_ID", {
  method: "DELETE",
  headers: {
    apikey: "YOUR_API_KEY",
    "x-connection-id": "conn_abc123"
  }
})
```

***

## API Endpoints

| Endpoint                                         | Method | Description              |
| ------------------------------------------------ | ------ | ------------------------ |
| `/v2/access/chats`                               | GET    | List all chats           |
| `/v2/access/chats/{userId}/messages`             | GET    | Get messages in a chat   |
| `/v2/access/chats/{userId}/messages`             | POST   | Send a message           |
| `/v2/access/chats/{userId}/messages/{messageId}` | DELETE | Unsend a message         |
| `/v2/access/chats/{userId}/media`                | GET    | Get media from a chat    |
| `/v2/access/analytics/mass-messages/sent`        | GET    | List sent mass messages  |
| `/v2/access/mass-messages`                       | POST   | Create mass message      |
| `/v2/access/mass-messages/{massMessageId}`       | GET    | Get mass message details |
| `/v2/access/mass-messages/{massMessageId}`       | PUT    | Update mass message      |
| `/v2/access/mass-messages/{massMessageId}`       | DELETE | Delete mass message      |

<Card title="Full API Reference" icon="book" href="/api-reference/access/overview">
  See complete endpoint documentation
</Card>

***

## Query Parameters

### List Chats Query

| Parameter    | Type   | Default  | Description                                |
| ------------ | ------ | -------- | ------------------------------------------ |
| `limit`      | number | 10       | Results per page (1-20)                    |
| `offset`     | number | 0        | Pagination offset                          |
| `order`      | string | "recent" | Sort order: `recent`, `old`                |
| `filter`     | string | -        | Filter: `priority`, `who_tipped`, `unread` |
| `query`      | string | -        | Search query                               |
| `userListId` | number | -        | Filter by user list ID                     |

### Chat Messages Query

| Parameter | Type   | Default | Description             |
| --------- | ------ | ------- | ----------------------- |
| `limit`   | number | 10      | Results per page (1-20) |
| `offset`  | number | 0       | Pagination offset       |
| `query`   | string | -       | Search within messages  |

***

## Message Options

| Field               | Type                | Description                                                                    |
| ------------------- | ------------------- | ------------------------------------------------------------------------------ |
| `text`              | string              | Message content ([supports markdown](/guides/how-to/text-formatting))          |
| `mediaItems`        | (number\|string)\[] | Media references (see [`mediaItems` reference](/guides/media-items))           |
| `price`             | number              | PPV price ($3-$200)                                                            |
| `isLockedText`      | boolean             | Lock text behind paywall                                                       |
| `previewMediaCount` | number              | How many `mediaItems` are previews. Uses the first N items from left to right. |
| `isMarkdown`        | boolean             | Parse text as markdown (default: true)                                         |
| `userTags`          | number\[]           | Tag users in message                                                           |
| `releaseForms`      | object              | Release form attachments                                                       |

<Tip>
  Use markdown formatting like `**bold**`, `*italic*`, and `# headers` in your messages. See [Text Formatting Guide](/guides/how-to/text-formatting) for all options.
</Tip>

<Info>
  For all accepted `mediaItems` values and validation rules, see the [`mediaItems` reference](/guides/media-items).
</Info>

### Queue-specific Options

| Field                 | Type      | Description                        |
| --------------------- | --------- | ---------------------------------- |
| `userIds`             | number\[] | Target specific user IDs           |
| `userLists`           | number\[] | Target user list IDs               |
| `excludeUserLists`    | number\[] | Exclude user list IDs              |
| `scheduledDate`       | string    | ISO date for scheduled sending     |
| `subscribedAfterDate` | string    | Target users subscribed after date |

***

## Tips & Best Practices

<Tip>
  **Rate Limiting**: OnlyFans has strict rate limits on messaging. Space out mass messages and implement exponential backoff for retries.
</Tip>

<Warning>
  **Content Guidelines**: Messages sent through OFAuth are subject to OnlyFans' terms of service. Automated spam or harassment can result in account suspension.
</Warning>

<Info>
  **Media First**: When sending messages with media, upload the media to the vault first using `/uploads/init` to get media IDs, then reference those IDs in `mediaItems`.
</Info>

***

## Common Workflows

### Welcome New Subscriber

Automatically greet new fans when they subscribe:

```javascript theme={null}
// 1. Get recently subscribed fans
const response = await fetch(
  "https://api.ofauth.com/v2/access/subscribers?type=latest&latestType=new&limit=10",
  { headers }
)
const newFans = await response.json()

// 2. Send welcome message to each
for (const fan of newFans.list) {
  await fetch(`https://api.ofauth.com/v2/access/chats/${fan.id}/messages`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      text: `Hey ${fan.name}! Thanks so much for subscribing! Let me know if there's anything you'd like to see.`
    })
  })
  
  // Space out messages to avoid rate limits
  await new Promise(r => setTimeout(r, 2000))
}
```

### Send PPV to High-Value Fans

Target your best customers with exclusive content:

```javascript theme={null}
// 1. Upload exclusive content first
const uploadInit = await fetch("https://api.ofauth.com/v2/access/uploads/init", {
  method: "POST",
  headers,
  body: JSON.stringify({
    filename: "exclusive.mp4",
    mimeType: "video/mp4",
    size: fileSize
  })
})
const { mediaUploadId, uploadUrl } = await uploadInit.json()

// 2. Upload the file
await fetch(uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: { "Content-Type": "video/mp4" }
})

// 3. Complete the upload
await fetch("https://api.ofauth.com/v2/access/uploads/complete", {
  method: "POST",
  headers,
  body: JSON.stringify({ mediaUploadId })
})

// 4. Send as PPV to a specific user list
await fetch("https://api.ofauth.com/v2/access/mass-messages", {
  method: "POST",
  headers,
  body: JSON.stringify({
    text: "Exclusive content just for my VIPs!",
    mediaItems: [mediaUploadId],
    price: 15.00,
    previewMediaCount: 1,
    userLists: [VIP_LIST_ID]
  })
})
```

### Respond to Unread Messages

Build a simple auto-responder or notification system:

```javascript theme={null}
// Get unread chats
const response = await fetch(
  "https://api.ofauth.com/v2/access/chats?filter=unread&limit=20",
  { headers }
)
const unreadChats = await response.json()

for (const chat of unreadChats.list) {
  // Get the latest message
  const messagesResp = await fetch(
    `https://api.ofauth.com/v2/access/chats/${chat.withUser.id}/messages?limit=1`,
    { headers }
  )
  const messages = await messagesResp.json()
  const lastMessage = messages.list[0]
  
  // Process the message (e.g., send to your AI, notify staff, etc.)
  console.log(`New message from ${chat.withUser.name}: ${lastMessage.text}`)
}
```

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Media & Vault" icon="photo-film" href="/guides/media">
    Upload media before sending in messages
  </Card>

  <Card title="Fans & Subscribers" icon="users" href="/guides/fans">
    Get fan lists for targeted messaging
  </Card>
</CardGroup>