Features

Region-Aware Gift Matching

Match TikTok gifts reliably across all regions using numeric gift IDs fetched directly from TikTok’s webcast API. No more broken rules when gift names differ between languages.

Overview

TikTok gift names vary by region and language. A gift called “Rose” in English may have a completely different name in Japanese, Korean, or Portuguese. Prior to v1.2.58, VMSC matched gifts by name only, which meant rules would break for streamers whose TikTok region used non-English gift names.

Region-Aware Gift Matching solves this by adding a numericId field to the gift catalogue. This numeric ID is TikTok’s universal identifier for each gift and does not change between regions or languages.

How It Works

Gift Catalogue & numericId

VMSC maintains an internal gift catalogue that maps gift metadata (name, icon, diamond value) to each gift. In v1.2.58, every gift entry now includes a numericId field — TikTok’s universal integer identifier for that gift.

Auto-Fetch on Startup

When VMSC starts, it automatically fetches the latest gift data from TikTok’s webcast API. This ensures the catalogue stays up to date with new gifts, renamed gifts, and retired gifts. The fetch happens in the background and does not block startup.

The auto-fetch uses TikTok’s public webcast gift list endpoint. No additional authentication beyond your normal TikTok connection is required.

The lookup() Function

When a gift event arrives from TikTok, VMSC calls its internal lookup(giftId, giftName) function to resolve the gift:

  1. Numeric ID first — The function tries to match the incoming giftId against the catalogue’s numericId field. If a match is found, the gift is resolved immediately. This path is region-proof because numeric IDs are universal.
  2. Name fallback — If no numeric match is found (e.g., the catalogue has not been updated yet), the function falls back to matching by giftName. This preserves backward compatibility with older catalogue data. 
// Simplified lookup logic
function lookup(giftId, giftName) {
  // 1. Try numeric ID (region-proof)
  const byId = catalogue.find(g => g.numericId === giftId);
  if (byId) return byId;

  // 2. Fallback to name match
  const byName = catalogue.find(
    g => g.name.toLowerCase() === giftName.toLowerCase()
  );
  return byName || null;
}

Why This Matters

Before region-aware matching, streamers in non-English regions had to manually enter localized gift names into their rules. If TikTok changed a gift name in a region update, rules would silently stop matching.

With numeric ID matching, your rules work across all TikTok regions regardless of the gift name language. A rule configured for “Rose” will match the same gift whether the incoming event calls it “Rose”, “Rosa”, or its Japanese equivalent.

ScenarioBefore v1.2.58After v1.2.58
English streamer, English viewer Works (name matches) Works (numeric ID matches)
English streamer, Japanese viewer May fail (different gift name) Works (numeric ID matches)
TikTok renames a gift Rules break until manually updated Works (numeric ID unchanged)
New gift not in catalogue No match Auto-fetched on next startup

Configuration

Region-aware gift matching is enabled by default in v1.2.58 and requires no configuration. The gift catalogue is updated automatically on every VMSC startup.

If you need to manually refresh the catalogue (e.g., TikTok just released new gifts and you do not want to restart VMSC), you can click the Refresh Gift Catalogue button in Settings > TikTok.

If VMSC cannot reach TikTok’s webcast API at startup (e.g., no internet connection), it falls back to the last cached version of the catalogue. Gift matching will still work using cached numeric IDs.