twitchps
v1.6.0
Published
Library to easily interact with Twitch PubSub System
Downloads
24
Maintainers
Readme
TwitchPS
Neat little Node library which lets you easily interact with the Twitch.tv PubSub service.
Supported Topics
| Feature | Topic and Example | Required Scope | You are notified when … |
|---|---|---|---|
| Bits | channel-bits-events-v1.<channel ID>
channel-bits-events-v2.<channel ID>
Example: channel-bits-events-v1.44322889
| bits:read
| Anyone cheers on a specified channel. |
| Bits Badge Notification | channel-bits-badge-unlocks.<channel_id>
Example: channel-bits-badge-unlocks.44322889
| bits:read
| Message sent when a user earns a new Bits badge in a particular channel, and chooses to share the notification with chat. |
| Channel Points | channel-points-channel-v1.<channel_id>
Example: channel-points-channel-v1.44322889
| channel:read:redemptions
| A custom reward is redeemed in a channel. |
| Community Channel Points | community-points-channel-v1.<channel_id>
Example: community-points-channel-v1.44322889
| No scope needed | Access to more events than standard channel points. It outputs to the reward-redeemed
event. Check events table below |
| Channel Subscriptions | channel-subscribe-events-v1.<channel ID>
Example: channel-subscribe-events-v1.44322889
| channel_subscriptions
| Anyone subscribes (first month, gift sub) or resubscribes (subsequent months) to a channel. |
| Whispers | whispers.<user ID>
Example: whispers.44322889
| whispers:read
| Anyone whispers the specified user. |
| Stream Status | video-playback.<channel name>
Example: video-playback.summit1g
| No scope needed | Status on stream going up, down, and viewer count. Not officially supported by Twitch|
| Moderator Action | chat_moderator_actions.<channel ID>
Example: chat_moderator_actions.44322889
| channel:moderate
| A moderator performs an action in the channel. |
Installation
Node
Install via NPM
npm i twitchps --save
Usage
Include the Component
Options
| Name | Type | Optional | Default | Description | |---|---|---|---|---| | init_topics | JSON object | False | *NONE | JSON Object array of initial topics with tokens. See below. | | reconnect | boolean | True | True | Reconnect when disconnected from Pubsub servers.| | debug | boolean | True | False | Turns debug console output on and off. |
const TwitchPS = require('twitchps');
// Initial topics are required
let init_topics = [{topic: 'video-playback.bajheera'}, {topic: 'whispers.44322889', token: 'nkuaf7ur3trg7ju37md1y3u5p52s3q'}];
// Optional reconnect, debug options (Defaults: reconnect: true, debug: false)
var ps = new TwitchPS({init_topics: init_topics, reconnect: false, debug: true});
ps.on('stream-up', (data) => {
console.log(data.time , data.channel_name);
// Use data here
});
Token changed for security reasons. You can generate a token here.
In order to find the userID/channelID follow the instructions here.
For more detailed usage see example application.
Connection Events
| Event Name | You are notified when … | |:--------------:|:--------------------------------------------:| | 'connected' | A successful connection has been established | | 'disconnected' | The connection has been terminated | | 'reconnect' | An attempt will be made to reconnect |
Events emitted after subscribing/adding topics
| Event Name | List of fields |
|:-----------------------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| 'error' | origin - {string} error - {string} (optional if topic is involved) topic - {string} |
| 'bits' | badge_entitlement - {object} (v2 only) bits_used - {integer} channel_id - {string} channel_name - {string} chat_message - {string} context - {string} is_anonymous - {boolean} (v2 only) message_id - {string} message_type - {string} time - {string} total_bits_used - {integer} user_id - {string} user_name - {string} version - {string} |
| 'bits-badge' | user_id - {string} - ID of user who earned the new Bits badge user_name - {string} - Login of user who earned the new Bits badge channel_id - {string} - ID of channel where user earned the new Bits badge channel_name - {string} - Login of channel where user earned the new Bits badge badge_tier - {int} - Value of Bits badge tier that was earned (1000, 10000, etc.) chat_message - {string} - [Optional] Custom message included with share time - {string} - Time when the bits were used. RFC 3339 format |
| 'reward-redeemed'(from community-points-channel-v1
) | timestamp - {string} - Time the pubsub message was sent redemption - {object} - Data about the redemption, includes unique id and user that redeemed it channel_id - {string} - ID of the channel in which the reward was redeemed. redeemed_at - {string} - Timestamp in which a reward was redeemed reward - {object} - Data about the reward that was redeemed user_input - {string} - [Optional] A string that the user entered if the reward requires input status - {string} - reward redemption status, will be FULFULLED if a user skips the reward queue, UNFULFILLED otherwise |
| 'channel-points'(from channel-points-channel-v1
) | timestamp - {string} - Time the pubsub message was sent redemption - {object} - Data about the redemption, includes unique id and user that redeemed it channel_id - {string} - ID of the channel in which the reward was redeemed. redeemed_at - {string} - Timestamp in which a reward was redeemed reward - {object} - Data about the reward that was redeemed user_input - {string} - [Optional] A string that the user entered if the reward requires input status - {string} - reward redemption status, will be FULFULLED if a user skips the reward queue, UNFULFILLED otherwise |
| 'community-points-all' | type - {string} timestamp - {string} event - {object} |
| 'community-reward-created''community-reward-updated''community-reward-deleted''community-goal-created''community-goal-updated''community-goal-deleted' | timestamp - {string} event - {object} |
| 'subscribe' | user_name - {string} display_name - {string} channel_name - {string} user_id - {string} channel_id- {string} time- {string} sub_plan- {string} sub_plan_name - {string} months - {integer} cumulative_months - {integer} context - {string} sub_message - {object} sub_message.message - {string} sub_message.emotes - {array} recipient_id - {integer} recipient_user_name - {string} recipient_display_name - {string} |
| 'whisper_sent' & 'whisper_received' | id - {integer} body - {string} thread_id - {string} sender - {JSON} sender.id - {integer} sender.username - {string} sender.display_name - {string} sender.color - {string} sender.badges - {Array} sender.emotes - {Array} recipient - {JSON} recipient.id - {integer} recipient.username - {string} recipient.display_name - {string} recipient.color - {string} recipient.badges - {Array} sent_ts - {integer} nonce - {string} |
| 'stream-up' | time - {integer} channel_name- {string} play_delay - {string} |
| 'stream-down' | time - {integer} channel_name- {string} |
| 'viewcount' | time - {integer} channel_name- {string} viewers - {integer} |
| 'automod_rejected' | user - {string} user_id - {string} message_id - {string}message - {string} reason - {string} |
| 'approved_automod_message' | createdBy - {string} created_by_user_id - {string} message_id - {string}target_user_login - {string} target_user_id - {string} |
| 'denied_automod_message' | createdBy - {string} created_by_user_id - {string} message_id - {string}target_user_login - {string} target_user_id - {string} |
| 'add_permitted_term' | createdBy - {string} created_by_user_id - {string} approved_term - {string} |
| 'delete_permitted_term' | createdBy - {string} created_by_user_id - {string} deleted_term - {string} |
| 'add_blocked_term' | createdBy - {string} created_by_user_id - {string} approved_term - {string} |
| 'add_permitted_term' | createdBy - {string} created_by_user_id - {string} blocked_term - {string} |
Listen to new topics
ps.addTopic([{topic: "video-playback.starladder_cs_en"}]);
ps.addTopic([{topic: 'whispers.38290946', token: 'nkuaf7ur3trg7ju37md1y3u5p52s3q'}]);
Token changed for security reasons.
Un-listen (remove) to existing topics
ps.removeTopic([{topic: "video-playback.starladder_cs_en"}]);
Token not required.
Community
- Follow @thecuriouseng on Twitter
- Have a question that is not a bug report? - Tweet me @thecuriouseng
- Found a bug ? Submit an issue.