Whisper events over PubSub

Using the Twitch PubSub system (TPS), you can listen to Whisper events by subscribing to the Whisper 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 Whisper topic

You can subscribe to a Whisper topic for a channel by sending a simple JSON message. The topic has a specific format: whispers.<user_id>. When subscribing to the Whisper topic for a channel, you must supply an OAuth token linked to the user_id for the topic using the chat_login scope.

Note: <user_id> is the _id field from the Kraken users 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": ["whispers.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 Whispers 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. The data and message fields are JSON strings and will need to be escaped.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
   "type":"MESSAGE",
   "data":{
      "topic":"whispers.44322889",
      "message":{
         "type":"whisper_received",
         "data":{
            "id":41
         },
         "thread_id":"129454141_44322889",
         "body":"hello",
         "sent_ts":1479160009,
         "from_id":39141793,
         "tags":{
            "login":"dallas",
            "display_name":"dallas",
            "color":"#8A2BE2",
            "emotes":[

            ],
            "badges":[
               {
                  "id":"staff",
                  "version":"1"
               }
            ]
         },
         "recipient":{
            "id":129454141,
            "username":"dallasnchains",
            "display_name":"dallasnchains",
            "color":"",
            "badges":[]
         },
         "nonce":"6GVBTfBXNj7d71BULYKjpiKapegDI1"
      },
      "data_object":{
         "id":41,
         "thread_id":"129454141_44322889",
         "body":"hello",
         "sent_ts":1479160009,
         "from_id":44322889,
         "tags":{
            "login":"dallas",
            "display_name":"dallas",
            "color":"#8A2BE2",
            "emotes":[],
            "badges":[
               {
                  "id":"staff",
                  "version":"1"
               }
            ]
         },
         "recipient":{
            "id":129454141,
            "username":"dallasnchains",
            "display_name":"dallasnchains",
            "color":"",
            "badges":[]
         },
         "nonce":"6GVBTfBXNj7d71BULYKjpiKapegDI1"
      }
   }
}