Activity data

An activity is a stream event such as a subscription, gift, donation, follow, raid, redeem or virtual-currency contribution. Custom widgets receive activities from the activity hooks, Activity Alert scripts receive them as ctx.activity, and Command scripts receive them as ctx.activity when an activity trigger runs.

Match groups instead of provider types

type identifies one provider-specific event, such as sub, kick_sub or newSponsorEvent. Use it only when the code needs behavior for that exact event.

For behavior shared across providers, use activity_group or contribution_group instead. Synchra assigns these groups to activity types, including types added by new provider integrations. Code using a group therefore continues to match new providers without adding their individual activity types.

if (activity.activity_group === "subscription") {
  showSubscriberWelcome(activity.viewer_display_name)
}

This is more durable than checking every known type:

// Avoid this for provider-independent behavior.
if (["sub", "kick_sub", "newSponsorEvent"].includes(activity.type)) {
  showSubscriberWelcome(activity.viewer_display_name)
}

Activity groups

activity_group describes what happened.

Value	Meaning
`subscription`	A subscription, membership or renewal.
`subscription_gift`	One or more gifted subscriptions.
`donation`	A monetary contribution.
`virtual_currency`	Bits, gifts or other platform currency.
`follow`	A new follower or channel subscriber.
`raid`	An incoming raid.
`redeem`	A reward redemption.

Use this group for most filtering, presentation and behavior.

Contribution groups

contribution_group identifies activity types that use compatible contribution values or source settings. For example, Twitch subscriptions and resubs both use twitch_subs, while money-based donation sources use currency_amount.

Value	Compatible activity values
`currency_amount`	Monetary contributions and memberships.
`virtual_currency`	Platform currency and gift values.
`twitch_subs`	Twitch subscriptions, resubs and gifted subs.
`youtube_memberships`	YouTube memberships and membership gifts.
`tiktok_superfans`	TikTok Super Fan events.
`rumble_subs`	Rumble subscriptions and gifts.
`kick_subs`	Kick subscriptions, resubs and gifts.
`follows`	Follow events across providers.
`redeems`	Reward redemptions across providers.

Use this group when activities should share value calculations or contribution settings. Use activity_group when only the kind of event matters.

Both fields can be null when an activity has no applicable group.

Filtering activity hooks

Custom widgets can request activities by group. Filters are combined with OR matching.

const activity = synchra.useLatestActivity({
  activityGroups: ["subscription", "subscription_gift", "donation"],
})

Use contribution groups when the widget works with compatible contribution values:

const activities = synchra.useActivities({
  limit: 20,
  contributionGroups: ["currency_amount", "virtual_currency"],
})

Activity Alert and Command scripts

Activity Alert scripts can branch on a group without checking which provider created the alert:

synchra.defineAlertScript({
  onShow(ctx) {
    if (ctx.activity.activity_group !== "donation") return
    ctx.elements.alert?.classList.add("is-donation")
  },
})

Command scripts use the same fields:

export async function run(ctx: ScriptContext) {
  if (ctx.activity?.activity_group !== "subscription_gift") return

  await ctx.sendMessage({
    message: `Thank you, ${ctx.activity.viewer_display_name}!`,
  })
}

Activity fields

Classification

Field	Meaning
`provider`	Source provider, such as `twitch`, `youtube` or `kick`.
`type`	Raw provider-specific activity type.
`type_display_name`	Human-readable activity type.
`sub_type`	Raw tier, reward or provider subtype when available.
`sub_type_display_name`	Human-readable subtype.
`activity_group`	Provider-independent description of what happened.
`contribution_group`	Group of activity types with compatible contribution behavior.

Viewer and event

Field	Meaning
`id`	Synchra activity ID.
`channel_id`	Synchra channel ID.
`provider_message_id`	Event ID supplied by the provider.
`provider_channel_id`	Channel ID supplied by the provider.
`provider_viewer_id`	Viewer ID supplied by the provider.
`viewer_name`	Viewer username or login.
`viewer_display_name`	Viewer display name.
`viewer_profile_picture_url`	Viewer profile image when available.
`viewer_created_at`	Viewer account creation time when available.
`created_at`	Activity time as an ISO timestamp.
`gifted_viewers`	Gift recipients when the provider supplies them.
`read`	Whether the activity was marked as read in Synchra.

Value and content

Field	Meaning
`count`	Raw integer value supplied for the activity.
`count_decimal_place`	Decimal scaling applied to `count`.
`count_currency`	Currency code for monetary values, otherwise `null`.
`count_name`	Human-readable unit, such as `months`, `bits` or `viewers`.
`system_message`	Provider-generated event text.
`message_parts`	Structured viewer message text, mentions, links and emotes.

Calculate the numeric value as count / 10 ** count_decimal_place. A count of 1234 with count_decimal_place set to 2 represents 12.34.

Custom widgets can render message_parts with synchra.assembleParts(activity.message_parts). Command scripts also receive the derived amount, message and recipient_display_name fields. Activity Alert scripts can use the formatted values in ctx.vars.

Presentation

Field	Meaning
`color`	Default activity color or gradient.
`font_color`	Suggested text color, when one is available.