Fanvue API Documentation

Two events report how a fan stands relative to a creator. 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 are delivered in the Standard-Webhooks envelope; the fields below describe the data object.

Delivery

Both topics use the same delivery model. 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 does not opt you into presence, subscribe to creator.fan.presence_changed explicitly. Presence is much higher volume than mute: one event per fan per online/offline transition, for every creator that fan is a contact of.

Presence is rolling out per creator, so a creator who has not been enabled produces no presence events yet. Mute changes fire on every mute/unmute action with no such gate.

When presence fires

online, the fan’s first socket connects. Repeated connections while already online do not re-fire.
offline, 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 “show online status” in their own privacy settings produces neither transition. 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. Do not apply an event just because it arrived.
Reconcile from GET /creators//subscribers/online on reconnect, and periodically if presence drives anything a user sees. That endpoint is the source of truth; the event tells you when to look.
Expect offline to be missed more often than online. Do not build a session timer that depends on receiving both halves.

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 same convention the message and payment events use. Both are public profile fields; 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 do not treat their absence as a change to the fan’s profile.

Example: `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": {}
  }
}

Example: `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": {}
  }
}

Example: `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": {}
  }
}

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Creator Fan Status

Delivery

When presence fires

Treat presence as a hint, not a ledger

Fan status resource

Fan object

Example: `creator.fan.status_changed` (mute)

Example: `creator.fan.presence_changed` (online)

Example: `creator.fan.presence_changed` (offline)

​Delivery

​When presence fires

​Treat presence as a hint, not a ledger

​Fan status resource

​Fan object

​Example: creator.fan.status_changed (mute)

​Example: creator.fan.presence_changed (online)

​Example: creator.fan.presence_changed (offline)

Delivery

When presence fires

Treat presence as a hint, not a ledger

Fan status resource

Fan object

Example: `creator.fan.status_changed` (mute)

Example: `creator.fan.presence_changed` (online)

Example: `creator.fan.presence_changed` (offline)