Contents

Authenticating and EventSub

Reviews for organizations and chatbot verification continue to be temporarily paused while we revise our processes. Reviews for Extensions and game ownership have resumed. Thank you for your patience and understanding.

Registering your bot

To get an access token, you must first register your bot. For information about registering your bot, see Registering Your App.

Authenticating

After registering your bot and getting a client ID, you can generate an access token. You can use either a User Access Token or an App Access Token, depending on what type of chatbot you are making. For information about Access Tokens and managing Twitch OAuth tokens, see Authentication.

After determining what type of access token to use, and what scopes are required, you can get a token in a number of ways, including:

If you just need a token for testing chat functionality, you can use the Twitch CLI to generate a User Access Token:
twitch token --user-token --scopes "user:read:chat user:write:chat"

What type of Access Token to use

Each type of chatbot has a different Access Token and scope requirement.

Cloud Chatbots

Since Cloud Chatbots use a user account owned by an application user, but need permission from the chat room’s broadcaster to read and write chat messages, you’ll need an App Access Token, and two User Access Tokens, one from your bot and one from the user who owns the chat room.

The App Access token can be generated with no scope. This token’s primary use is to set up the EventSub subscriptions, such as Channel Chat Message.

The first User Access Token you’ll need is one for the bot that will be reading chat, sending chat messages as the bot, and performing moderator commands. This is only needed to be performed once and kept alive through refreshing the access token. This authentication requires 3 scopes minimum:

The second User Access Token will be from the broadcaster who owns the chat room. This will be used for API calls that can only be performed as the broadcaster, such as Get Creator Goals. This authentication requires 1 scope minumum:

Alternatively, the second User Access Token is not required if the bot’s user account is a moderator in the broadcaster’s channel. However, this is a less common approach as it requires manual action from the broadcaster.

Installed Chatbots

Installed Chatbots access the broadcaster’s user account to act as a bot, so only a single User Access Token from the broadcaster will be needed. This authentication only requires 1 scope minimum:

Chat Clients

Chat Clients, similar to Installed Chatbots, access the broadcaster’s user account to act as a bot. Unlike Installed Chatbots, sending chat messages is a part of chat clients, so this authentication requires 2 scopes minimum:

Setting up EventSub Subscriptions

To read chat messages and other chat events, you’ll need to set up an EventSub subscription.

WebSockets vs Webhooks

Before making your subscription, you’ll have to decide what EventSub transport you’d like to use. The options Twitch currently provides is WebSockets and Webhooks.

The WebSocket transport sends EventSub events to you over WebSockets, a protocol designed for persistent client-server communication within web browsers. Receiving EventSub events via WebSockets is the best option when a chatbot is hosted on the end-user’s system, such as in the case of Chat Clients and Installed Chatbots.
You can only subscribe to events over WebSockets transport using a User Access Token.

The Webhook transport sends EventSub events to your public HTTP server via a webhook. Receiving EventSub events via Webhooks is the best option when a chatbot is hosted off of the end-user’s system, such as in the case of Cloud Chatbots. You can only subscribe to events over Webhook transport using an App Access Token.

For more information on handling WebSocket events, see Getting Events Using WebSockets.
For more information on handling Webhook events, see Getting Events Using Webhook Callbacks.

Making the subscription

Creating the subscription is done by calling the Create EventSub Subscription API.

Each subscription type has a different condition object that needs to be filled in. For chat subscription types, you’ll need to set the chat’s broadcaster in broadcaster_user_id and your bot’s User ID in user_id.
For further information on each subscription type, see EventSub Subscription Types.

An example of subscribing to channel.chat.message, where the broadcaster is User ID 12826 (Twitch) and the bot authorized is User ID 141981764 (TwitchDev):

curl -X POST 'https://api.twitch.tv/helix/eventsub/subscriptions' \
-H 'Authorization: Bearer 2gbdx6oar67tqtcmt49t3wpcgycthx' \
-H 'Client-Id: wbmytr93xzw8zbg0p1izqyzzc5mbiz' \
-H 'Content-Type: application/json' \
-d '{
  "type": "channel.chat.message",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "12826",
    "user_id": "141981764"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://your-webhook-handling-server.com",
    "secret":"s3cre7"
  }
}'

For more information on managing EventSub subscriptions, see Managing EventSub Subscriptions.

Scaling WebSockets with conduits

When your bot starts handling a large amount of users, scaling up requires taking into consideration load balancing. When using WebSockets specifically it can be difficult to handle scaling, so to ease this Twitch provides a wrapper transport type to assist with load balancing called Conduits.

Conduits is designed to allow you to tell Twitch what WebSocket connection or Webhook endpoint you want specific EventSub subscriptions to go to, each of these endpoints being referred to as a “shard”. For chat messages, this means an EventSub subscription for listening to a specific chat room’s chat messages will only send those messages to the specified shard.

Conduits can only be managed using App Access Tokens, but the transports of the subscriptions assigned to each conduit shard can be created using a User Access Token or an App Access Token.

For more information on managing and scaling with conduits, see Handling Conduit Events.

Docs Status Support Showcase Blog