Fanvue API Documentation

Two events report how a fan stands relative to a creator: whether the creator has muted them, and whether they’re online. They carry the same fan_status resource and are discriminated by change_type, but ride separate topics so you can subscribe to one without the other.

Event (`type`)	`change_type`	`state`	Fires when
`creator.fan.status_changed`	`mute`	`muted` \| `unmuted`	The creator mutes or unmutes the fan
`creator.fan.presence_changed`	`presence`	`online` \| `offline`	The fan comes online or goes offline

Neither has a legacy flat equivalent. Both require the read:chat scope, and presence events are sent only for creators who have presence enabled. Each event arrives in the envelope, and the tables below describe data.

Fan status resource

Field	Type	Description
`object`	string	Always `"fan_status"`
`change_type`	string	`mute` or `presence`
`state`	string	`muted` \| `unmuted` (for `mute`), or `online` \| `offline` (for `presence`)
`changed_at`	string \| null	ISO 8601 time the change occurred
`fan`	object	The fan, see Fan object
`creator`	object	`{ uuid }` of the creator
`metadata`	object	Your passthrough metadata map

Fan object

Field	Type	Description
`uuid`	string	The fan’s user UUID
`email`	null	Always `null`. Present for shape parity only; never populated
`handle`	string	The fan’s public handle. Omitted when the identity lookup does not resolve
`display_name`	string	The fan’s display name. Omitted when the identity lookup does not resolve

handle and display_name are omitted from the payload rather than sent as null, so treat an absent key as “not resolved”. The message and payment events use the same convention. Both are public profile fields, and no email is carried on any creator.* event. The identity lookup is best-effort and runs after the delivery decision. A lookup failure omits handle and display_name rather than delaying or dropping the event, so don’t treat their absence as a change to the fan’s profile.

Examples

`creator.fan.status_changed` (mute)

{
  "id": "f1a2b3c4-bbbb-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.fan.status_changed",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "fan_status",
    "change_type": "mute",
    "state": "muted",
    "changed_at": "2026-06-09T08:39:33.139Z",
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

`creator.fan.presence_changed` (online)

{
  "id": "f1a2b3c4-cccc-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.fan.presence_changed",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "fan_status",
    "change_type": "presence",
    "state": "online",
    "changed_at": "2026-06-09T08:39:33.139Z",
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

`creator.fan.presence_changed` (offline)

Identical apart from state. changed_at is when the platform stopped considering the fan online, not the moment they closed the app.

{
  "id": "f1a2b3c4-dddd-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "creator.fan.presence_changed",
  "timestamp": "2026-06-09T09:12:41.000Z",
  "data": {
    "object": "fan_status",
    "change_type": "presence",
    "state": "offline",
    "changed_at": "2026-06-09T09:12:41.000Z",
    "fan": {
      "uuid": "fan-uuid",
      "email": null,
      "handle": "janed",
      "display_name": "Jane D"
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": {}
  }
}

Delivery

Both topics use the same delivery rule. Each event reaches:

apps holding read:chat for the creator, and
the creator’s connector destination, when one is subscribed.

Delivery is filtered per topic, so taking read:chat doesn’t opt you into presence; subscribe to creator.fan.presence_changed explicitly. Presence is much higher volume than mute, with one event per fan per online/offline transition for every creator that fan is a contact of. Mute changes, by contrast, fire for every creator on every mute or unmute action.

When presence fires

online fires when the fan’s first socket connects. Repeated connections while already online don’t re-fire.
offline fires when the fan’s presence record lapses. There is no disconnect signal to key off, so offline is reported when the platform stops considering the fan online, which is later than the moment they actually left.

A fan who has turned off their online status in their own privacy settings produces neither transition, so an absence of presence events is not evidence a fan is offline.

Treat presence as a hint, not a ledger

Presence describes state that is true only for a moment, and webhook delivery retries. A redelivered online can arrive after the offline that superseded it. Build for that rather than assuming ordered, exactly-once delivery:

Compare changed_at against the state you already hold and discard anything older. Don’t apply an event just because it arrived.
Reconcile from GET /creators/{creatorUserUuid}/subscribers/online on reconnect, and periodically if presence drives anything a user sees. That endpoint is the source of truth, and the event tells you when to look.
Expect offline to be missed more often than online. Don’t build a session timer that depends on receiving both halves.

Receiving events

Creator events

Checkout link events

App events

Legacy events (deprecated)

Creator fan status events

Fan status resource

Fan object

Examples

`creator.fan.status_changed` (mute)

`creator.fan.presence_changed` (online)

`creator.fan.presence_changed` (offline)

Delivery

When presence fires

Treat presence as a hint, not a ledger

​Fan status resource

​Fan object

​Examples

​creator.fan.status_changed (mute)

​creator.fan.presence_changed (online)

​creator.fan.presence_changed (offline)

​Delivery

​When presence fires

​Treat presence as a hint, not a ledger

Fan status resource

Fan object

Examples

`creator.fan.status_changed` (mute)

`creator.fan.presence_changed` (online)

`creator.fan.presence_changed` (offline)

Delivery

When presence fires

Treat presence as a hint, not a ledger