Fanvue API Documentation

creator.message.* events mirror a creator’s messaging activity as it happens. They replace the legacy message.received and message.read events and add sent, mass_sent, read_by_fan, deleted and reaction. There is no legacy message.sent event, so creator.message.sent is the only event for a creator’s outbound message. To mirror whole chats into your own store, Keep a local copy of chats in sync combines these events with the chat API.

Event (`type`)	`data.object`	Fires when
`creator.message.received`	message	The creator receives an inbound message from a fan
`creator.message.sent`	message	An outbound creator-to-fan message is sent (web app, API, agency or automated reply)
`creator.message.mass_sent`	mass_message	A mass message is sent. One event per send, not per recipient
`creator.message.read`	fan_message_read	The creator marks a fan’s messages as read
`creator.message.read_by_fan`	creator_message_read	A fan marks the creator’s messages as read
`creator.message.deleted`	message	A message is unsent/deleted
`creator.message.reaction`	reaction	A reaction is added to a message

All message events require the read:chat scope. Each event arrives in the envelope, and the tables below describe data. The conversation is addressed by the fan (fan.uuid); there is no separate chat id. creator.message.received and creator.message.sent both carry the message content (text, media_uuids, price and more), and so does creator.message.mass_sent on its own mass message resource. The two content-bearing events don’t carry an identical set; Content fields shows which event carries what. creator.message.deleted is metadata-only, so use the chat API to fetch content for that one.

Two payload behaviours commonly break integrations:

Keys are snake_case. media_uuids, message_type, is_muted, unread_messages_count, is_automated, not mediaUuids, messageType, isMuted. The deprecated flat message.received used camelCase; the creator.* envelope does not.
Optional fields are omitted, not nulled. An absent value has no key at all; it is never sent as null or as an empty array. A message with no media has no media_uuids key, so treat an absent key as empty rather than reading payload.data.media_uuids.length.

Message resource

creator.message.received, creator.message.sent and creator.message.deleted share this resource. A mass message has its own; see Mass message resource.

Core fields

Always present on all three events.

Field	Type	Description
`object`	string	Always `"message"`
`uuid`	string	The message’s unique identifier
`sender`	string	`creator` or `fan`. Always `creator` on `creator.message.sent`
`created_at`	string \| null	ISO 8601 time the message was created. Always `null` on `creator.message.deleted`
`deleted_at`	string \| null	ISO 8601 unsend time. Set on `creator.message.deleted`, `null` on `received` and `sent`
`creator`	object	`{ uuid }` of the creator who owns the conversation
`fan`	object	The conversation counterpart, see Fan object
`metadata`	object	Your passthrough metadata map

Content fields

creator.message.received and creator.message.sent carry the message itself. Every content field is optional, and when the value doesn’t apply, the key is absent from the payload, not null and not [].

Field	Type	Present on	Description
`text`	string	`received`, `sent`	The message body. Absent when the message has no text (e.g. media-only)
`message_type`	string	`received`, `sent`	Platform message type, e.g. `SINGLE_RECIPIENT`, `BROADCAST`, `TIP`, `LOCKED_MESSAGE_UNLOCKED`, `VOICE_CALL`, or an `AUTOMATED_` / `CHAT_TEXT_` value
`is_muted`	boolean	`received`	Whether the creator has muted this fan
`media_uuids`	string[]	`received`, `sent`	Ordered media UUIDs on the message, including its preview. Absent when the message has no media
`gif`	object	`received`, `sent`	`{ id, format, title, url, width, height }` for a GIF message. `url` is `null` when the hotlink is withheld. Absent on ordinary messages
`price`	integer	`received`, `sent`	Unlock price in minor units (USD cents) for a pay-to-view message. Absent when the message is not a paid unlock
`tip`	object	`received`	`{ price, status, transaction_order_id }` for a `TIP` message. Absent otherwise
`is_automated`	boolean	`received`	`true` when the message was sent by an automated reply
`unread_messages_count`	integer	`received`, `sent`	The creator’s unread count for this conversation. On `received` it includes the inbound message; on `sent` the creator’s own message does not add to it

creator.message.sent is not metadata-only. It carries text, media_uuids, price, gif, message_type and unread_messages_count. It does not carry is_muted, tip or is_automated. Content on sent is hydrated best-effort after the event is triggered. A lookup failure omits the fields rather than delaying or dropping the delivery, so an absent text on sent means “no text or not resolved”. Fall back to the chat API if you need certainty.

Fan object

Field	Type	Present on	Description
`uuid`	string	all	The counterpart’s user UUID. This also addresses the conversation
`email`	null	all	Always `null` on message events. Present for shape parity only; do not rely on it
`display_name`	string	`received`, `sent`, `deleted`	The counterpart’s display name. Absent when the identity lookup does not resolve it
`handle`	string	`received`, `sent`, `deleted`	The counterpart’s public handle. Absent when the identity lookup does not resolve it
`avatar_url`	string \| null	`received`	Avatar URL. `null` when they have no avatar; absent when `display_name` did not resolve

avatar_url is the only identity field limited to creator.message.received. creator.message.sent and creator.message.deleted carry handle and display_name but no avatar.

Example: `creator.message.received`

A pay-to-view message with text and two media attachments:

{
  "id": "f1a2b3c4-4444-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.message.received",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "message",
    "uuid": "2f7c5e8a-6d36-4e3a-98d9-9f1b3b0a1a10",
    "sender": "fan",
    "created_at": "2026-06-09T08:39:33.139Z",
    "deleted_at": null,
    "text": "Hey! Loved your latest post 😍",
    "message_type": "SINGLE_RECIPIENT",
    "is_muted": false,
    "media_uuids": [
      "b8c47a91-3f2d-4a55-b7e8-1c9d2e4f5a6b",
      "c1d58b02-4e3e-4b66-c8f9-2d0e3f5a6b7c"
    ],
    "price": 300,
    "is_automated": false,
    "unread_messages_count": 3,
    "creator": { "uuid": "creator-uuid" },
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed",
      "avatar_url": "https://cdn.fanvue.com/avatars/example.jpg"
    },
    "metadata": {}
  }
}

A plain text-only message from the same fan omits media_uuids and price entirely; the keys are not present at all.

Example: `creator.message.sent`

The same envelope and object as received. sender is always creator, and is_muted, tip and is_automated are never present.

{
  "id": "f1a2b3c4-7777-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.message.sent",
  "timestamp": "2026-06-09T08:41:02.114Z",
  "data": {
    "object": "message",
    "uuid": "9b1c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "sender": "creator",
    "created_at": "2026-06-09T08:41:02.114Z",
    "deleted_at": null,
    "message_type": "SINGLE_RECIPIENT",
    "text": "Thanks for subscribing! 💕",
    "media_uuids": ["b8c47a91-3f2d-4a55-b7e8-1c9d2e4f5a6b"],
    "unread_messages_count": 0,
    "creator": { "uuid": "creator-uuid" },
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "metadata": {}
  }
}

Example: `creator.message.deleted`

The core fields only. sender names which party unsent their own message, deleted_at is the unsend time, and created_at is always null.

{
  "id": "f1a2b3c4-7778-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.message.deleted",
  "timestamp": "2026-06-09T09:15:44.000Z",
  "data": {
    "object": "message",
    "uuid": "9b1c3d4e-5f60-4a7b-8c9d-0e1f2a3b4c5d",
    "sender": "creator",
    "created_at": null,
    "deleted_at": "2026-06-09T09:15:44.000Z",
    "creator": { "uuid": "creator-uuid" },
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "metadata": {}
  }
}

creator.message.deleted fires only for a single-message unsend, from the creator web app, the public API or agency automation. Mass-message unsends, moderation takedowns and failed scheduled sends don’t emit it, so don’t treat this event as a complete record of disappearing messages.

Mass message resource

creator.message.mass_sent uses this resource. It fires when a creator sends a mass message, either a BROADCAST or a scheduled GHOST_PROMOTION. The event describes the send, not each copy of it. A mass message is one message row fanned out over many conversations, so exactly one event is delivered per send, whatever the audience size. A mass message never emits creator.message.sent. The two topics don’t overlap, so subscribe to both to see every creator-to-fan send. Doing so produces no duplicates.

Fields

Field	Type	Description
`object`	string	Always `"mass_message"`
`uuid`	string	The mass message’s own UUID. A mass message is a single message row, so this is the send’s whole identity; there is no separate campaign id
`sender`	string	Always `"creator"`. Present for parity with the message resource
`created_at`	string \| null	ISO 8601 time the send was dispatched
`recipient_count`	integer	How many fans the send was addressed to, see Recipient count
`creator`	object	`{ uuid }` of the creator who sent it
`metadata`	object	Your passthrough metadata map

Content fields follow the same omitted-not-nulled rule as the message resource: when the value doesn’t apply, the key is absent.

Field	Type	Description
`message_type`	string	`BROADCAST` or `GHOST_PROMOTION`, so a scheduled ghost promotion stays distinguishable inside the topic. Absent only when neither the delivery job nor the mass message’s record reports one
`text`	string	The authored body, see Personalisation tokens. Absent when the send has no text
`media_uuids`	string[]	Ordered media UUIDs on the send, including its preview. Absent when the send has no media
`gif`	object	`{ id, format, title, url, width, height }` for a GIF send. `url` is `null` when the hotlink is withheld. Absent otherwise
`price`	integer	Unlock price in minor units for a pay-to-view send. Absent when the send is not a paid unlock

There is no fan object. A mass message has no single recipient, so the resource names only the creator. The event also carries no unread_messages_count, is_muted, tip or is_automated.

Personalisation tokens

text is the body as the creator wrote it, with its personalisation tokens ({{handle}} and the others) left intact. The event is the send rather than one fan’s copy, so there is no recipient to render it against. Substitute per fan yourself if you need the text a given fan saw.

Recipient count

recipient_count is the size of the whole audience the send was addressed to, read from the mass message’s own record. A large send is dispatched in throttled batches, and this number covers all of them. One case reports less. If the audience hasn’t yet been stamped on the record when the event is built, the count falls back to the batch that published it. That is exact for a send small enough to fit one batch, and under-reports for anything larger rather than guessing.

Which fans received it

The event does not carry the recipient list, and the recipient list is not exposed on the API. recipient_count is a size, not a set.

Sends that are never announced

A retracted send. If the mass message is unsent while delivery is still running, no event is delivered at all.
A mass unsend. Taking a mass message back emits nothing, on this topic or any other. In particular creator.message.deleted does not fire for it, so don’t treat these two events as a matched pair.

Deduplicating a mass message

The event id is a hash of the creator UUID and the mass message UUID, so it is stable per send and a valid idempotency key with no extra work. A delivery job that is re-driven for the same mass message publishes the same id again. See Deduplicating events.

Example: `creator.message.mass_sent`

A pay-to-view broadcast with one media attachment and a personalisation token in the body:

{
  "id": "3d9f0b6c1e8a47529adf0c1b2e3f4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5",
  "type": "creator.message.mass_sent",
  "timestamp": "2026-06-09T10:12:05.881Z",
  "data": {
    "object": "mass_message",
    "uuid": "7c1e9d24-8a3f-4b52-9d61-0f2a3b4c5d6e",
    "sender": "creator",
    "created_at": "2026-06-09T10:12:05.402Z",
    "message_type": "BROADCAST",
    "text": "Hey {{handle}}, new set just dropped 💕",
    "media_uuids": ["b8c47a91-3f2d-4a55-b7e8-1c9d2e4f5a6b"],
    "price": 900,
    "recipient_count": 30142,
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

Read-receipt resource

creator.message.read uses this resource. It is a per-conversation read receipt, not a message entity, so it reports counts rather than a message UUID.

Field	Type	Description
`object`	string	Always `"fan_message_read"`
`read_messages_count`	integer	How many of the fan’s messages were just marked read
`unread_messages_count`	integer	The creator’s remaining unread count for this conversation
`read_at`	string	ISO 8601 time the read was handled, see Ordering against a manual unread mark
`fan`	object	The conversation counterpart, same shape as the Fan object minus `avatar_url`: `uuid`, `email` (always `null`), and `handle` / `display_name` when they resolve
`creator`	object	`{ uuid }` of the creator who read the messages
`metadata`	object	Your passthrough metadata map

The event fires only when the read cleared unread state. Opening an already-read conversation emits nothing, so creator.message.read is not a signal that the creator opened the chat. Clearing a manual unread mark counts as clearing unread state, so this also fires with read_messages_count: 0 when the creator reads a conversation they had marked unread by hand. A 0 there is the marker being cleared, not a no-op. The event covers the creator as reader direction only. For the fan reading the creator’s messages, see Read-by-fan receipt resource.

Ordering against a manual unread mark

creator.message.read is the clear half of the creator’s inbox badge. The set half is creator.chat.marked_unread, which fires when the creator deliberately marks a conversation unread. The two are published independently and are not ordered against each other. Compare this event’s read_at with that event’s marked_at and apply whichever is later, rather than applying whichever arrived last. Both are stamped when the action was handled and stay put across delivery retries, which the envelope timestamp does not.

Deduplicating a read receipt

The event id is a hash of the two parties and read_at, so each read occurrence has its own id. A creator who reads, marks unread and reads again with no new message in between gets two events with two ids. The id alone is a valid idempotency key. See Deduplicating events.

Example: `creator.message.read`

{
  "id": "f1a2b3c4-5555-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.message.read",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "fan_message_read",
    "read_messages_count": 3,
    "unread_messages_count": 0,
    "read_at": "2026-06-09T08:39:32.884Z",
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

Read-by-fan receipt resource

creator.message.read_by_fan uses this resource. It fires when a fan marks the creator’s messages as read, which is what lets you render a “read by recipient” tick on the creator’s side.

creator.message.read and creator.message.read_by_fan are opposite directions, and neither replaces the other. creator.message.read fires when the creator reads the fan’s messages; read_by_fan fires when the fan reads the creator’s.The topic name says who read. The object in the payload says whose messages were read (fan_message_read / creator_message_read). The two names run on different axes, so don’t read either object as the reader.

Field	Type	Description
`object`	string	Always `"creator_message_read"`
`read_messages_count`	integer	How many of the creator’s messages the fan just marked read
`read_at`	string	ISO 8601 time the read was handled, see Read time vs envelope timestamp
`fan`	object	`{ uuid }` of the fan who read. Bare UUID only
`creator`	object	`{ uuid }` of the creator whose messages were read
`metadata`	object	Your passthrough metadata map

Both parties are bare UUIDs on this event, unlike every other message event. There is no email, handle, display_name or avatar_url, and no Fan object; you already hold the fan’s identity from the message events for the same conversation. There is no unread count either, because on this direction that is the fan’s own inbox state. Like creator.message.read, this fires only when the read cleared unread state and at least one message was read. A fan opening an already-read conversation emits nothing, so this is not a signal that the fan opened the chat. The event belongs to the creator whose messages were read, and is delivered to that creator’s consumers. A creator reading a fan’s messages produces creator.message.read instead, and a read whose counterpart is not a creator produces nothing.

Read time vs envelope timestamp

Use read_at, not the envelope timestamp. The envelope timestamp is stamped when the event is published, so it moves on a retry or a replay. read_at is stamped when the read was handled and is the only stable read time on the payload.

Deduplicating a read-by-fan receipt

The id on this topic includes the UUID of the newest message in the conversation, so it carries an occurrence component and is a valid idempotency key on its own. See Deduplicating events.

Example: `creator.message.read_by_fan`

{
  "id": "b71c4e5a2f8d3906c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
  "type": "creator.message.read_by_fan",
  "timestamp": "2026-06-09T08:44:11.204Z",
  "data": {
    "object": "creator_message_read",
    "read_messages_count": 3,
    "read_at": "2026-06-09T08:44:10.502Z",
    "fan": { "uuid": "fan-uuid" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

Reaction resource

creator.message.reaction uses this resource. Either party can react, so it names three roles rather than two.

Field	Type	Description
`object`	string	Always `"reaction"`
`sender`	string	Who reacted: `creator` or `fan`
`message_uuid`	string	The message that was reacted to
`emoji`	string	The reaction emoji
`actor`	object	The reactor, same shape as the Fan object minus `avatar_url`
`creator`	object	`{ uuid }` of the creator who owns the conversation
`fan`	object	The conversation’s fan, always the counterpart and never the reactor. Same shape as `actor`
`created_at`	string \| null	ISO 8601 time the reaction was added
`metadata`	object	Reserved; always `{}` on this event

On a creator-initiated reaction, actor and creator carry the same UUID. Use sender to tell the direction and fan to identify the conversation, because actor alone can’t do it. Only added reactions emit. Removing a reaction produces no event, and a swapped emoji arrives as a new creator.message.reaction.

Example: `creator.message.reaction`

{
  "id": "f1a2b3c4-6666-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.message.reaction",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "reaction",
    "sender": "fan",
    "message_uuid": "2f7c5e8a-6d36-4e3a-98d9-9f1b3b0a1a10",
    "emoji": "❤️",
    "actor": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "creator": { "uuid": "creator-uuid" },
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "created_at": "2026-06-09T08:39:33.139Z",
    "metadata": {}
  }
}

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Creator message events

Message resource

Core fields

Content fields

Fan object

Example: `creator.message.received`

Example: `creator.message.sent`

Example: `creator.message.deleted`

Mass message resource

Fields

Personalisation tokens

Recipient count

Which fans received it

Sends that are never announced

Deduplicating a mass message

Example: `creator.message.mass_sent`

Read-receipt resource

Ordering against a manual unread mark

Deduplicating a read receipt

Example: `creator.message.read`

Read-by-fan receipt resource

Read time vs envelope timestamp

Deduplicating a read-by-fan receipt

Example: `creator.message.read_by_fan`

Reaction resource

Example: `creator.message.reaction`

​Message resource

​Core fields

​Content fields

​Fan object

​Example: creator.message.received

​Example: creator.message.sent

​Example: creator.message.deleted

​Mass message resource

​Fields

​Personalisation tokens

​Recipient count

​Which fans received it

​Sends that are never announced

​Deduplicating a mass message

​Example: creator.message.mass_sent

​Read-receipt resource

​Ordering against a manual unread mark

​Deduplicating a read receipt

​Example: creator.message.read

​Read-by-fan receipt resource

​Read time vs envelope timestamp

​Deduplicating a read-by-fan receipt

​Example: creator.message.read_by_fan

​Reaction resource

​Example: creator.message.reaction

Message resource

Core fields

Content fields

Fan object

Example: `creator.message.received`

Example: `creator.message.sent`

Example: `creator.message.deleted`

Mass message resource

Fields

Personalisation tokens

Recipient count

Which fans received it

Sends that are never announced

Deduplicating a mass message

Example: `creator.message.mass_sent`

Read-receipt resource

Ordering against a manual unread mark

Deduplicating a read receipt

Example: `creator.message.read`

Read-by-fan receipt resource

Read time vs envelope timestamp

Deduplicating a read-by-fan receipt

Example: `creator.message.read_by_fan`

Reaction resource

Example: `creator.message.reaction`