Bits events over PubSub

Using the Twitch PubSub system (TPS), you can listen to Bits events occurring in a channel by subscribing to the Bits event topic. When connecting, you’ll need to provide authentication via an OAuth token from the channel where you’re listening. For general information about TPS (including rate limits and best practices), check out the Twitch PubSub System documentation.

Subscribing to a Bits topic

You can subscribe to a Bits topic for a channel by sending a simple JSON message. The topic has a specific format: channel-bitsevents.<channel_id>. When subscribing to the Bits topic for a channel, you must supply an OAuth token linked to the channel_id for the topic. Any scope will suffice for subscribing.

Note: <channel_id> is the _id field from the Kraken channels response.

In full, you would send a request that looks like the following:

1
2
3
4
5
6
7
8
{
  "type": "LISTEN",
  "nonce": "...",
  "data": {
    "topics": ["channel-bitsevents.44322889"],
    "auth_token": "..."
  }
}

After your initial request, you’ll receive a response message with the error if applicable.

1
2
3
4
5
{
  "type": "RESPONSE",
  "nonce": "...",
  "error": "..." 
}

The nonce field will match the request nonce. The error field will be an empty string if there is no error. If there is an error, it can be one of ERR_BADMESSAGE, ERR_BADAUTH, ERR_SERVER, ERR_BADTOPIC.

Receiving a Bits event message

When a message for your subscription is published, you will receive a message containing the applicable data. The message will look like the following:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
   "type": "MESSAGE",
   "data": {
      "topic": "channel-bitsevents.44322889",
      "message": {
         "user_name": "dallas",
         "channel_name": "twitch",
         "user_id": "44322889",
         "channel_id": "12826",
         "time": "2015-12-19T16:39:57-08:00",
         "chat_message": "Omg that baneling bust was Kreygasm cheer10 cheer10 cheer100",
         "bits_used": 120,
         "total_bits_used": 620,
         "context": "cheer"
         }
   }
}

Response Parameters

Name Type Description
user_name string Login name of the person who used Bits.
channel_name string Channel name where Bits were used.
user_id string User ID of the person who used Bits.
channel_id string Channel ID where Bits were used.
time string Time when the Bits were used. RFC 3339 format.
chat_message string Chat message sent with the cheer.
bits_used integer Number of Bits used.
total_bits_used integer All-time total number of Bits used on this channel by the user.
context string Event type associated with this Bits usage (e.g. cheer).