EventSub delivers real time information for activities that occur on Twitch such as subscriptions, Cheering, Hype Trains, and polls. As extensive as EventSub has become since its initial release, there has been one foundational aspect of Twitch that has not made an appearance until now. Get your favorite emotes ready because sending and receiving Twitch Chat is coming to EventSub and the Twitch API.
During TwitchCon 2023, four new subscription types were announced and later released as the first step to bring Twitch Chat to EventSub. These are channel.chat.clear, channel.chat.clear_user_messages, channel.chat.message_delete, and channel.chat.notification. At the same time, we mentioned eventually adding a fifth subscription type for receiving all chat messages in a given channel. After letting it cook a little longer, the channel.chat.message subscription type is now available as version 1.
To subscribe to read chat in a channel, you’ll need authorization from the user your application wants to read chat as (we’ll call this the chatting user). This user must be able to join the specified channel’s chat and will appear in the chatters list as long as your subscription is active. If you’re setting up a subscription over WebSockets, you’ll need the
user:read:chat scope from the chatting user. If your app needs to scale out to many channels, you’ll need to subscribe via Conduits or Webhooks, and you must also have the
user:bot scope from the chatting user and either (1) the
channel:bot scope from the broadcaster or (2) the chatting user must have moderation status from the broadcaster. These additional scopes for app access tokens provides broadcasters with more control over who can programmatically interact with their chat.
Although defined in the documentation, here is a recap of these scopes:
channel:bot- Allows the application’s bot users access to a channel. Granted by the broadcaster of the channel you want to read chat in and necessary if you are setting up your subscription with an app access token.
user:bot- Allows the application’s to appear as this user in chat. Granted by the user your application will read chat as and necessary if you are setting up your subscription with an app access token. In the future, we may visually distinguish users that appear in chat via this method from other Twitch users.
user:read:chat- Allows the application to view live stream chat messages.
Now that developers can receive chat messages via EventSub, they should also be able to send chat messages via the Twitch API. Therefore, the Send Chat Message Twitch API endpoint is now available in open beta. This endpoint will allow you to send a message to a broadcaster’s chat room. As with IRC, your application will be able to send chat messages at a rate limit based on the chatting user.
Similarly to the scopes mentioned above for reading chat, this API endpoint requires the
user:write:chat scope at a minimum for app and user access tokens. If an app access token is used, then the endpoint also requires the
user:bot scope from the chatting user and either the
channel:bot scope from the broadcaster or moderator status in the broadcaster’s channel.
Building chatbots over an IRC connection has been beneficial for creators since it was introduced; it created the foundation for interactivity in the live streaming community. But there are some inherent issues building applications with the IRC protocol that we wanted to solve with our latest third-party interfaces. For example, it can take an extremely long time to connect to a lot of channels over IRC, which only becomes worse as your application gains popularity. Reconnecting quickly to a lot of channels via IRC can be challenging and expensive. We think this complexity is a barrier to having more chatbot options for broadcasters. If we made it easy to scale your chatbot as it becomes more popular, we could foster a larger chatbot environment that ultimately gives creators more options and features to enhance their communities.
EventSub with Webhooks and WebSockets does not address the reconnect speed issue with IRC. So we created a new transport type called Conduits to help with this issue and give developers easier ways to scale and load balance your application.
We introduced Conduits via RFC 0017 in August 2023 with more details provided during TwitchCon. Conduits are essentially a wrapper transport type that abstracts your EventSub subscriptions from a specific underlying transport (i.e. Webhook or WebSocket) and load balance notifications across shards. A shard is either a Webhook or a WebSocket connection while a Conduit is a collection of shards. Conduits are intended for backend applications and requires an app access token.
This design allows us to solve three particular challenges for developers using EventSub: it allows us to have subscriptions persist across disconnects, shard notifications for applications with many subscriptions, and provide applications a way to receive high-throughput notifications at scale.
To get started or learn more about how to use Conduits, refer to the Handling Conduit Events guide. As you will see from the guide, the key steps to begin implementing this new transport type are:
- Create a Conduit and specify the shard count
- Connect a type of transport to each shard
- Create subscriptions, with an app access token, that reference the conduit ID as the transport
Notifications are sent to shards and an attempt is made to send notifications for a particular channel ID to the same shard for consistency.
EventSub will disable shards if the underlying websocket disconnects, or if the webhook is unhealthy for an extended period of time. If a shard is disabled, EventSub will retry sending the notification on another shard. To quickly address disabled shards, the new conduit.shard.disabled subscription type can be used to listen for status changes.
A series of API endpoints and an EventSub subscription type are also available beginning today to manage Conduits.
- Create Conduits - Creates a new conduit.
- Get Conduits - Retrieves the conduits for a client ID.
- Update Conduits - Updates a conduit’s shard count.
- Delete Conduit - Deletes a conduit.
- Get Conduit Shards - Lists all shards for a conduit.
- Update Conduit Shards - Updates shard(s) for a conduit.
- conduit.shard.disabled - Sends a notification when a shard is disabled due to the underlying transport status changing.
There is currently no plan to remove IRC as a third-party supported interface. Legacy systems, from bots to video game integrations, rely on this functionality and any major changes would be overly disruptive. However, as Twitch Chat evolves, our investment in new features will primarily focus on the functionality available via EventSub and the Twitch API.