Fanvue API Documentation

These events mirror a creator’s direct-message activity in real time. They are the successor to the legacy message.received, message.sent, and message.read events, plus new deleted and reaction events.

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 → fan message is sent (UI, agency, automation, or AI)
`creator.message.read`	fan_message_read	The creator marks a fan’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. Delivered in the Standard-Webhooks envelope; the fields below describe the data object.

creator.message.received and creator.message.sent both carry the message content, text, media_uuids, price and more. creator.message.deleted is metadata-only: for that one, use the chat API to fetch content. The two content-bearing events do not carry an identical set, see Content fields for exactly which event carries what.The conversation is addressed by the fan (fan.uuid); there is no separate chat id.

Two payload behaviours that 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

Used by creator.message.received, creator.message.sent, and creator.message.deleted.

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 field here is optional in the sense described above: when the value does not apply, the key is absent from the payload, not null, 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 (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 automation
`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. What it does not carry is is_muted, tip, or is_automated.creator.message.deleted carries none of this table. Fetch its content from the chat API.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 deliberately do not emit it, so do not treat this event as a complete record of disappearing messages.

Read-receipt resource

Used by creator.message.read. This is a per-conversation read receipt, not a message entity, 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
`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

This fires only when the read actually cleared unread state. Opening an already-read conversation emits nothing, so creator.message.read is not a signal that the creator opened the chat.

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,
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "display_name": "Jane D",
      "handle": "janed"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

Reaction resource

Used by creator.message.reaction. Either party can react, so this resource 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, actor alone cannot do it.Only added reactions emit. Removing a reaction produces no event; 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": {}
  }
}

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Creator Messages

Message resource

Core fields

Content fields

Fan object

Example: `creator.message.received`

Example: `creator.message.sent`

Example: `creator.message.deleted`

Read-receipt resource

Example: `creator.message.read`

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

​Read-receipt resource

​Example: creator.message.read

​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`

Read-receipt resource

Example: `creator.message.read`

Reaction resource

Example: `creator.message.reaction`