Message Model

Message Types

The nine values of the type field, which fields each populates, and the YouTube renderer behind it.

type tells you what kind of event a message is. There are nine values.

`type`	Meaning	Notable fields
`chat`	An ordinary chat message	`author`, `parts`, badge flags
`chat-edited`	A message replaced in place	same as `chat`
`superchat`	A paid Super Chat	`amount`, `color`
`sticker`	A paid Super Sticker	`amount`, `color`, body is the sticker's label
`membership`	A new or milestone membership	`author`, body is the announcement text
`gift`	Gifted memberships	`author` is the header text
`engagement`	A system notice from YouTube	`iconType`
`ticker`	A ticker item scrolling above the chat	`amount`, `color`
`deleted`	A message was removed	body is the tombstone text

Anything the parser does not recognise is dropped rather than emitted with an unknown type, so this list is exhaustive.

chat

The common case. Carries the author's badges, so isMember, isModerator, isOwner and memberBadge appear here when they apply, along with authorPhoto.

{
  "type": "chat",
  "id": "ChwKGkNJ...",
  "timestamp": "1:23 PM",
  "author": "Some Viewer",
  "message": "hello everyone",
  "amount": "",
  "color": "",
  "parts": [{ "kind": "text", "text": "hello everyone" }],
  "isMember": true,
  "memberBadge": { "tooltip": "Member (6 months)", "thumbnails": [] }
}

chat-edited

Identical in shape to chat. The distinct type exists so a UI can replace an existing message by id instead of appending a duplicate.

superchat

A paid message. amount is the formatted purchase string exactly as YouTube renders it — currency symbol included, locale-dependent, not parseable as a number. color is the card's background as #rrggbb, derived from the tier.

{
  "type": "superchat",
  "author": "Generous Viewer",
  "message": "great stream!",
  "amount": "$5.00",
  "color": "#ffca28",
  "parts": [{ "kind": "text", "text": "great stream!" }]
}

sticker

A paid Super Sticker. There is no author-written text, so the body is taken from the sticker's accessibility label — the description of the image. amount and color behave as they do for superchat.

membership

A new membership or a milestone. The body combines YouTube's primary and subtext lines; when both exist the subtext is appended in parentheses, e.g. "Welcome to the channel! (Member for 6 months)".

gift

A gifted-membership purchase announcement. author holds the announcement header rather than a plain display name, and the body joins the primary text and subtext with a dash.

engagement

A system message from YouTube rather than a person — the "chat is in slow mode" style notice. These carry an iconType such as YOUTUBE_ROUND. When YouTube supplies an icon but no text, the iconType is used as the body so the event is never blank.

ticker

An item from the scrolling ticker above the chat. Two different renderers produce this type:

paid ticker items, which carry amount and color,
sponsor ticker items, whose body is the literal string "sponsor".

Ticker items have no timestamp. They largely duplicate superchat and membership events that already arrived, so most UIs filter them out.

deleted

A moderation event. Two renderers produce it: a single message being removed, and every message from one author being removed at once. For the per-author variant, author holds the channel id.

deleted events carry no id, so they cannot be correlated back to the message they removed. The body is YouTube's tombstone text, defaulting to "a message" when YouTube supplies none.

Filtering by type

const HIDDEN = new Set(['ticker', 'engagement'])

client.on('message', (message) => {
  if (HIDDEN.has(message.type)) return
  render(message)
})

Because type is a plain string rather than a literal union, a switch over it will not be exhaustiveness-checked by TypeScript — always include a default branch.