creator.chat.* events report conversation state rather than message state. There is one event, and together with creator.message.read it lets you mirror the creator’s unread badge; see The inbox badge has two halves.
The event requires the
read:chat scope, the same as the message events, and has no legacy flat equivalent. It arrives in the envelope, and the tables below describe data.
Chat unread marker resource
The conversation is addressed by
fan.uuid. As on the message events, there is no separate chat id.
unread_messages_count is usually 0
Marking a conversation unread doesn’t create unread messages, so the count is whatever it already was. In the common case, a creator flagging a chat they’ve already read so they remember to come back to it, that is 0. A 0 here does not contradict the event. It is why the badge rule in The inbox badge has two halves is an OR rather than a count check.
The count is resolved best-effort when the event is built. If that lookup fails the event is still delivered, with 0, rather than being dropped. Treat 0 as “no unread messages, or not resolved” and fall back to GET /chats if you need the exact number.
Fan object
Same shape as the Fan object on the message events, minus
avatar_url. The identity lookup is best-effort and runs after the delivery decision, so an absent handle or display_name is a lookup that didn’t resolve, not a change to the fan’s profile.
creator stays a bare { uuid }. The creator is the account you already hold a token for, so this event does not restate their identity.
Example
A creator flagging a conversation they have already read:The inbox badge has two halves
The Fanvue sidebar shows a conversation as unread when either of two things is true, and you need both events to mirror it:
Render a conversation as unread when the marker is set or
unread_messages_count is above zero. Clearing a manual marker on a conversation with no unread messages emits creator.message.read with read_messages_count: 0, which is the marker being cleared rather than a no-op.
Subscribe to both. Taking only
creator.chat.marked_unread gives you a badge you can never turn off.Ordering the two halves
The two halves are not ordered against each other. Each event is published independently, so a mark and a read that happen close together can arrive in either order. Compare the times on the payloads and apply whichever is later, rather than applying whichever landed last:timestamp moves on a retry, so don’t order on it.
Delivery
Each event reaches:- apps holding
read:chatfor the creator, and - the creator’s connector destination, when one is subscribed.
What does not fire it
- Marking a conversation that is already unread. The event reports the transition into unread, not the action, so a repeat mark with no read in between emits nothing. Marking, reading and marking again emits twice, because the read cleared the marker in between.
- A fan marking a creator’s chat unread. The event is creator-owned and reports the creator’s own inbox, so a mark by a non-creator produces nothing. That holds even though
read:chatis a scope a fan’s app can hold. - A conversation going unread because a new message arrived. That is
creator.message.received, which already carriesunread_messages_count. This event is the deliberate manual mark only. - Archiving or muting a conversation. Muting is
creator.fan.status_changed; archiving emits nothing. - Internal automated and support conversations, which are never exposed to integrations.
Deduplicating a mark
The eventid is a hash of the two parties and marked_at, so it carries an occurrence component and the id alone is a valid idempotency key. A creator who marks a conversation unread, opens it, and marks it unread again gets two events with two ids, with no new message needed in between. See Deduplicating events.