Fanvue API Documentation

By the end of this page you’ll be able to list a creator’s chats, read the messages in one, tell a tip from a pay-to-view message from an automation, and send a priced message with a free preview. You need an access token with read:chat, plus write:chat to send. If you’re keeping a local copy of chats, don’t re-poll each one; receive messages with webhooks and pull deltas in bulk, as Keep a local copy of chats in sync shows.

List chats

GET /chats returns one item per conversation, paginated with page and size (default 15, maximum 50). The filter query parameter narrows the list, and unread returns only chats with unread messages. Scope: read:chat.

curl "https://api.fanvue.com/chats?filter=unread&page=1&size=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

Two fields on each chat item describe unread state, and they are not interchangeable:

Field	Meaning
`isRead`	`false` when unread messages exist, or when the chat was marked unread with `PATCH /chats/{userUuid}`. Use it for unread badges.
`unreadMessagesCount`	Number of messages the authenticated user has not read. Stays `0` for a chat that was marked unread manually.

Each item also carries user (the counterpart, with uuid, handle and displayName) and lastMessage. The lastMessage.senderRole value tells you who wrote it:

`senderRole`	Sender
`CREATOR`	The creator, sending directly
`AGENCY`	A team member sending on the creator’s behalf
`FAN`	The counterpart fan
`SYSTEM`	An automated or platform message

The message object

GET /chats/{userUuid}/messages returns the messages between the authenticated user and userUuid, newest first. Scope: read:chat.

curl "https://api.fanvue.com/chats/f47ac10b-58cc-4372-a567-0e02b2c3d479/messages?size=15&markAsRead=false" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

Each message in the data array carries these fields:

Field	What it tells you
`uuid`	Stable ID for the message.
`text`	The message body, or `null` for a media-only message.
`sentAt`	When it was sent.
`sender` / `recipient`	Each has a `uuid` and a `handle`.
`hasMedia` / `mediaType` / `mediaUuids`	Attachment flag, attachment type and the ordered attachment UUIDs.
`mediaPreviewUuid`	The media item shown free as a preview of a pay-to-view message, or `null`.
`gif`	A third-party GIF block (`id`, `format`, `title`, `url`, `width`, `height`), or `null`. A GIF message has no media and no price.
`type`	The message kind. Values are listed in Tell message types apart.
`pricing`	Present for pay-to-view messages. `pricing.USD.price` is in USD cents. `null` for ordinary messages.
`purchasedAt`	When the fan purchased this message, or `null`.
`tipSource`	For `TIP` messages: `chat`, `post` or `media_link`. `null` otherwise.
`isRead`	Whether the recipient has read the message.
`sentByUserId`	The team member who sent it on the creator’s behalf, or `null` when the creator sent it directly.
`appUuid`	The app that sent the message through the API, or `null` for messages sent from Fanvue.

A full priced message looks like this:

{
  "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "text": "New set from the shoot, 12 photos",
  "sentAt": "2026-03-04T18:21:09.000Z",
  "sender": { "uuid": "3bbe6394-2830-4646-a8ba-4a0a05426947", "handle": "ava-creates" },
  "recipient": { "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "handle": "sam-fan" },
  "hasMedia": true,
  "mediaType": "image",
  "mediaUuids": ["0b4a3c1e-2f6d-4b8a-9c1d-5e7f8a9b0c1d", "1c5b4d2f-3a7e-4c9b-8d2e-6f8a9b0c1d2e"],
  "mediaPreviewUuid": "0b4a3c1e-2f6d-4b8a-9c1d-5e7f8a9b0c1d",
  "gif": null,
  "type": "SINGLE_RECIPIENT",
  "pricing": { "USD": { "price": 1500 } },
  "purchasedAt": null,
  "tipSource": null,
  "isRead": true,
  "sentByUserId": "9d8c7b6a-5e4f-4d3c-b2a1-0f9e8d7c6b5a",
  "appUuid": null
}

Tell message types apart

The type field separates ordinary messages, tips, calls, mass messages and automated messages:

Group	`type` values
Ordinary	`SINGLE_RECIPIENT`, `CHAT_TEXT_REPLY`, `CHAT_TEXT_GENERATION`, `CHAT_TEXT_REWRITE`
Tip	`TIP`
Voice call	`VOICE_CALL`
Mass message	`BROADCAST`, `GHOST_PROMOTION`
Automated	`AUTOMATED_FIRST_MESSAGE_REPLY`, `AUTOMATED_NEW_SUBSCRIBER`, `AUTOMATED_NEW_FOLLOWER`, `AUTOMATED_NEW_PURCHASE`, `AUTOMATED_RE_SUBSCRIBED`, `AUTOMATED_RENEWED`, `AUTOMATED_CANCELED`, `AUTOMATED_CHAT_MESSAGE_REPLY`

In practice:

A tip is type === "TIP".
A pay-to-view (PPV) message has a non-null pricing, whatever its type.
An automated message carries an AUTOMATED_ prefix. Filter on the prefix to separate automations from the human conversation.
A mass message reached this fan as part of a broadcast. The per-chat endpoint interleaves them with direct messages; POST /chats/messages/batch leaves them out.

Check PPV payment state

purchasedAt is the timestamp the fan paid, or null:

purchasedAt set: the fan has unlocked the message.
purchasedAt null on a message with pricing: the message is awaiting purchase.

pricing.USD.price is in USD cents, so divide by 100 for display. Read both fields from the message. The same names appear on chat media items, where they describe the media’s source message. The item serving as the free preview reports pricing, purchasedAt and amountPaid as null even on a priced message the fan has bought. See Pricing fields on chat media.

Check read state

isRead on each message gives you read state straight from the message list. For a surface that updates when a fan reads the creator’s message, subscribe to creator.message.read_by_fan rather than polling. creator.message.read fires the other way round, when the creator reads a fan’s messages. See Creator message events.

Identify the sender

sentByUserId is the UUID of the team member who sent the message on the creator’s behalf, or null when the creator sent it directly. Use it to attribute a message, and any purchase it drove, to a specific chatter. On the chat list, lastMessage.senderRole gives the same distinction without a UUID lookup.

User names

Two name fields appear on the authenticated user (GET /users/me) and on every sender and recipient:

handle is the unique @ handle.
displayName is the changeable public name.

Use uuid as the stable identifier. Show displayName and fall back to handle.

Send a message

POST /chats/{userUuid}/message sends into an existing chat. Scope: write:chat. The body accepts:

Field	Rule
`text`	1 to 5000 characters. Optional when `mediaUuids`, `gif` or `templateUuid` is present.
`mediaUuids`	Media UUIDs to attach, in display order. Audio media is delivered as a voice note.
`price`	USD cents, minimum `300`. Requires `mediaUuids` or `templateUuid`.
`mediaPreviewUuid`	One attached media item to show free. Requires `price` and `mediaUuids`.
`templateUuid`	A saved template, which carries its own text, media and price.
`gif`	A third-party GIF block. Cannot be combined with `mediaUuids`, `mediaPreviewUuid`, `price` or `templateUuid`.

The response is 201 with { "messageUuid": "..." }.

curl -X POST "https://api.fanvue.com/chats/f47ac10b-58cc-4372-a567-0e02b2c3d479/message" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "New set from the shoot, 12 photos",
    "mediaUuids": ["0b4a3c1e-2f6d-4b8a-9c1d-5e7f8a9b0c1d", "1c5b4d2f-3a7e-4c9b-8d2e-6f8a9b0c1d2e"],
    "mediaPreviewUuid": "0b4a3c1e-2f6d-4b8a-9c1d-5e7f8a9b0c1d",
    "price": 1500
  }'

A 400 with a contactability error means the fan can’t be messaged, for example because they aren’t subscribed. Handle it per chat so one fan doesn’t stop a batch.

Send media only after GET /media/{uuid} reports status: "ready". Media still processing attaches to the message but the recipient cannot open it. If you sent too early, wait for ready and send again. See Upload media in parts.

Start here

Authentication

API concepts

Guides

Read and send messages

List chats

The message object

Tell message types apart

Check PPV payment state

Check read state

Identify the sender

User names

Send a message

​List chats

​The message object

​Tell message types apart

​Check PPV payment state

​Check read state

​Identify the sender

​User names

​Send a message

List chats

The message object

Tell message types apart

Check PPV payment state

Check read state

Identify the sender

User names

Send a message