EventSub Webhook#
Note
EventSub Webhook is targeted at programs which have to subscribe to topics for multiple broadcasters.
Should you only need to target a single broadcaster or are building a client side project, look at EventSub Websocket
EventSub lets you listen for events that happen on Twitch.
The EventSub client runs in its own thread, calling the given callback function whenever an event happens.
Requirements#
Note
Please note that Your Endpoint URL has to be HTTPS, has to run on Port 443 and requires a valid, non self signed certificate This most likely means, that you need a reverse proxy like nginx. You can also hand in a valid ssl context to be used in the constructor.
In the case that you don’t hand in a valid ssl context to the constructor, you can specify any port you want in the constructor and handle the bridge between this program and your public URL on port 443 via reverse proxy.
You can check on whether or not your webhook is publicly reachable by navigating to the URL set in callback_url.
You should get a 200 response with the text pyTwitchAPI eventsub
.
Listening to topics#
After you started your EventSub client, you can use the listen_
prefixed functions to listen to the topics you are interested in.
Look at Available Topics and Callback Payloads to find the topics you are interested in.
The function you hand in as callback will be called whenever that event happens with the event data as a parameter, the type of that parameter is also listed in the link above.
Code Example#
from twitchAPI.twitch import Twitch
from twitchAPI.helper import first
from twitchAPI.eventsub.webhook import EventSubWebhook
from twitchAPI.object.eventsub import ChannelFollowEvent
from twitchAPI.oauth import UserAuthenticator
from twitchAPI.type import AuthScope
import asyncio
TARGET_USERNAME = 'target_username_here'
EVENTSUB_URL = 'https://url.to.your.webhook.com'
APP_ID = 'your_app_id'
APP_SECRET = 'your_app_secret'
TARGET_SCOPES = [AuthScope.MODERATOR_READ_FOLLOWERS]
async def on_follow(data: ChannelFollowEvent):
# our event happened, lets do things with the data we got!
print(f'{data.event.user_name} now follows {data.event.broadcaster_user_name}!')
async def eventsub_webhook_example():
# create the api instance and get the ID of the target user
twitch = await Twitch(APP_ID, APP_SECRET)
user = await first(twitch.get_users(logins=TARGET_USERNAME))
# the user has to authenticate once using the bot with our intended scope.
# since we do not need the resulting token after this authentication, we just discard the result we get from authenticate()
# Please read up the UserAuthenticator documentation to get a full view of how this process works
auth = UserAuthenticator(twitch, TARGET_SCOPES)
await auth.authenticate()
# basic setup, will run on port 8080 and a reverse proxy takes care of the https and certificate
eventsub = EventSubWebhook(EVENTSUB_URL, 8080, twitch)
# unsubscribe from all old events that might still be there
# this will ensure we have a clean slate
await eventsub.unsubscribe_all()
# start the eventsub client
eventsub.start()
# subscribing to the desired eventsub hook for our user
# the given function (in this example on_follow) will be called every time this event is triggered
# the broadcaster is a moderator in their own channel by default so specifying both as the same works in this example
await eventsub.listen_channel_follow_v2(user.id, user.id, on_follow)
# eventsub will run in its own process
# so lets just wait for user input before shutting it all down again
try:
input('press Enter to shut down...')
finally:
# stopping both eventsub as well as gracefully closing the connection to the API
await eventsub.stop()
await twitch.close()
print('done')
# lets run our example
asyncio.run(eventsub_webhook_example())
- class twitchAPI.eventsub.webhook.EventSubWebhook#
Bases:
EventSubBase
- __init__(callback_url, port, twitch, ssl_context=None, host_binding='0.0.0.0', subscription_url=None, callback_loop=None, revocation_handler=None, message_deduplication_history_length=50)#
- Parameters:
ssl_context¶ (
Optional
[SSLContext
]) – optional ssl context to be usedDefault:None
host_binding¶ (
str
) – the host to bind the internal server toDefault:0.0.0.0
subscription_url¶ (
Optional
[str
]) – Alternative subscription URL, useful for development with the twitch-clicallback_loop¶ (
Optional
[AbstractEventLoop
]) –The asyncio eventloop to be used for callbacks.
Set this if you or a library you use cares about which asyncio event loop is running the callbacks. Defaults to the one used by EventSub Webhook.
revocation_handler¶ (
Optional
[Callable
[[dict
],Awaitable
[None
]]]) – Optional handler for when subscriptions get revoked.Default:None
message_deduplication_history_length¶ (
int
) – The amount of messages being considered for the duplicate message deduplication.Default:50
- callback_url: str#
The full URL of the webhook.
- secret: str#
A random secret string. Set this for added security.
Default:A random 20 character long string
- wait_for_subscription_confirm: bool#
Set this to false if you don’t want to wait for a subscription confirm.
Default:True
- wait_for_subscription_confirm_timeout: int#
Max time in seconds to wait for a subscription confirmation. Only used if
wait_for_subscription_confirm
is set to True.Default:30
- subscription_url: Optional[str]#
Alternative subscription URL, useful for development with the twitch-cli
- revokation_handler: Optional[Callable[[dict], Awaitable[None]]]#
Optional handler for when subscriptions get revoked.
- unsubscribe_on_stop: bool#
Unsubscribe all currently active Webhooks on calling
stop()
Default:True
- start()#
Starts the EventSub client
- Return type:
None
- Raises:
RuntimeError – if EventSub is already running
- async stop()#
Stops the EventSub client
This also unsubscribes from all known subscriptions if unsubscribe_on_stop is True
- Return type:
None
- Raises:
RuntimeError – if EventSub is not running
- async listen_automod_message_hold(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification if a message was caught by automod for review.
Requires
MODERATOR_MANAGE_AUTOMOD
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#automodmessagehold
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_automod_message_update(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when a message in the automod queue has its status changed.
Requires
MODERATOR_MANAGE_AUTOMOD
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#automodmessageupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_automod_settings_update(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when the broadcaster’s automod settings are updated.
Requires
MODERATOR_READ_AUTOMOD_SETTINGS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#automodsettingsupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_automod_terms_update(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when a broadcaster’s automod terms are updated.
Requires
MODERATOR_MANAGE_AUTOMOD
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#automodtermsupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_ad_break_begin(broadcaster_user_id, callback)#
A midroll commercial break has started running.
Requires the
CHANNEL_READ_ADS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelad_breakbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_ban(broadcaster_user_id, callback)#
A viewer is banned from the specified channel.
User Authentication with
CHANNEL_MODERATE
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelban
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_charity_campaign_donate(broadcaster_user_id, callback)#
Sends a notification when a user donates to the broadcaster’s charity campaign.
Requires the
CHANNEL_READ_CHARITY
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaigndonate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_charity_campaign_progress(broadcaster_user_id, callback)#
Sends notifications when progress is made towards the campaign’s goal or when the broadcaster changes the fundraising goal.
Requires the
CHANNEL_READ_CHARITY
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignprogress
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_charity_campaign_start(broadcaster_user_id, callback)#
Sends a notification when the broadcaster starts a charity campaign.
Requires the
CHANNEL_READ_CHARITY
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignstart
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_charity_campaign_stop(broadcaster_user_id, callback)#
Sends a notification when the broadcaster stops a charity campaign.
Requires the
CHANNEL_READ_CHARITY
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelcharity_campaignstop
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_clear(broadcaster_user_id, user_id, callback)#
A moderator or bot has cleared all messages from the chat room.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatclear
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_clear_user_messages(broadcaster_user_id, user_id, callback)#
A moderator or bot has cleared all messages from a specific user.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatclear_user_messages
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_message(broadcaster_user_id, user_id, callback)#
Any user sends a message to a specific chat room.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatmessage
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_message_delete(broadcaster_user_id, user_id, callback)#
A moderator has removed a specific message.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatmessage_delete
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_notification(broadcaster_user_id, user_id, callback)#
A notification for when an event that appears in chat has occurred.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatnotification
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_settings_update(broadcaster_user_id, user_id, callback)#
This event sends a notification when a broadcaster’s chat settings are updated.
Requires
USER_READ_CHAT
scope from chatting user. If app access token used, then additionally requiresUSER_BOT
scope from chatting user, and eitherCHANNEL_BOT
scope from broadcaster or moderator status.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchat_settingsupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_user_message_hold(broadcaster_user_id, user_id, callback)#
A user is notified if their message is caught by automod.
Note
Requires
USER_READ_CHAT
scope from the chatting user.If WebSockets is used, additionally requires
USER_BOT
from chatting user.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatuser_message_hold
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_chat_user_message_update(broadcaster_user_id, user_id, callback)#
A user is notified if their message’s automod status is updated.
Note
Requires
USER_READ_CHAT
scope from the chatting user.If WebSockets is used, additionally requires
USER_BOT
from chatting user.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchatuser_message_update
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_cheer(broadcaster_user_id, callback)#
A user cheers on the specified channel.
User Authentication with
BITS_READ
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelcheer
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_follow_v2(broadcaster_user_id, moderator_user_id, callback)#
A specified channel receives a follow.
User Authentication with
MODERATOR_READ_FOLLOWERS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelfollow
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_moderate(broadcaster_user_id, moderator_user_id, callback)#
A moderator performs a moderation action in a channel. Includes warnings.
Requires all of the following scopes:
MODERATOR_READ_BLOCKED_TERMS
orMODERATOR_MANAGE_BLOCKED_TERMS
MODERATOR_READ_CHAT_SETTINGS
orMODERATOR_MANAGE_CHAT_SETTINGS
MODERATOR_READ_UNBAN_REQUESTS
orMODERATOR_MANAGE_UNBAN_REQUESTS
MODERATOR_READ_BANNED_USERS
orMODERATOR_MANAGE_BANNED_USERS
MODERATOR_READ_CHAT_MESSAGES
orMODERATOR_MANAGE_CHAT_MESSAGES
Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelmoderate-v2
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_moderator_add(broadcaster_user_id, callback)#
Moderator privileges were added to a user on a specified channel.
User Authentication with
MODERATION_READ
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatoradd
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_moderator_remove(broadcaster_user_id, callback)#
Moderator privileges were removed from a user on a specified channel.
User Authentication with
MODERATION_READ
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelmoderatorremove
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_automatic_reward_redemption_add(broadcaster_user_id, callback)#
A viewer has redeemed an automatic channel points reward on the specified channel.
Requires
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelchannel_points_automatic_reward_redemptionadd
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_custom_reward_add(broadcaster_user_id, callback)#
A custom channel points reward has been created for the specified channel.
User Authentication with
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardadd
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_custom_reward_redemption_add(broadcaster_user_id, callback, reward_id=None)#
A viewer has redeemed a custom channel points reward on the specified channel.
User Authentication with
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionadd
- Parameters:
broadcaster_user_id¶ (
str
) – the id of the user you want to listen toreward_id¶ (
Optional
[str
]) – the id of the reward you want to get updates from.Default:None
callback¶ (
Callable
[[ChannelPointsCustomRewardRedemptionAddEvent
],Awaitable
[None
]]) – function for callback- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_custom_reward_redemption_update(broadcaster_user_id, callback, reward_id=None)#
A redemption of a channel points custom reward has been updated for the specified channel.
User Authentication with
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_reward_redemptionupdate
- Parameters:
broadcaster_user_id¶ (
str
) – the id of the user you want to listen toreward_id¶ (
Optional
[str
]) – the id of the reward you want to get updates from.Default:None
callback¶ (
Callable
[[ChannelPointsCustomRewardRedemptionUpdateEvent
],Awaitable
[None
]]) – function for callback- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_custom_reward_remove(broadcaster_user_id, callback, reward_id=None)#
A custom channel points reward has been removed from the specified channel.
User Authentication with
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardremove
- Parameters:
broadcaster_user_id¶ (
str
) – the id of the user you want to listen toreward_id¶ (
Optional
[str
]) – the id of the reward you want to get updates from.Default:None
callback¶ (
Callable
[[ChannelPointsCustomRewardRemoveEvent
],Awaitable
[None
]]) – function for callback- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_points_custom_reward_update(broadcaster_user_id, callback, reward_id=None)#
A custom channel points reward has been updated for the specified channel.
User Authentication with
CHANNEL_READ_REDEMPTIONS
orCHANNEL_MANAGE_REDEMPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelchannel_points_custom_rewardupdate
- Parameters:
broadcaster_user_id¶ (
str
) – the id of the user you want to listen toreward_id¶ (
Optional
[str
]) – the id of the reward you want to get updates from.Default:None
callback¶ (
Callable
[[ChannelPointsCustomRewardUpdateEvent
],Awaitable
[None
]]) – function for callback- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_poll_begin(broadcaster_user_id, callback)#
A poll started on a specified channel.
User Authentication with
CHANNEL_READ_POLLS
orCHANNEL_MANAGE_POLLS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_poll_end(broadcaster_user_id, callback)#
A poll ended on a specified channel.
User Authentication with
CHANNEL_READ_POLLS
orCHANNEL_MANAGE_POLLS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_poll_progress(broadcaster_user_id, callback)#
Users respond to a poll on a specified channel.
User Authentication with
CHANNEL_READ_POLLS
orCHANNEL_MANAGE_POLLS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpollprogress
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_prediction_begin(broadcaster_user_id, callback)#
A Prediction started on a specified channel.
User Authentication with
CHANNEL_READ_PREDICTIONS
orCHANNEL_MANAGE_PREDICTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_prediction_end(broadcaster_user_id, callback)#
A Prediction ended on a specified channel.
User Authentication with
CHANNEL_READ_PREDICTIONS
orCHANNEL_MANAGE_PREDICTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_prediction_lock(broadcaster_user_id, callback)#
A Prediction was locked on a specified channel.
User Authentication with
CHANNEL_READ_PREDICTIONS
orCHANNEL_MANAGE_PREDICTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionlock
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_prediction_progress(broadcaster_user_id, callback)#
Users participated in a Prediction on a specified channel.
User Authentication with
CHANNEL_READ_PREDICTIONS
orCHANNEL_MANAGE_PREDICTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelpredictionprogress
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_raid(callback, to_broadcaster_user_id=None, from_broadcaster_user_id=None)#
A broadcaster raids another broadcaster’s channel.
No authorization required.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelraid
- Parameters:
from_broadcaster_user_id¶ (
Optional
[str
]) – The broadcaster user ID that created the channel raid you want to get notifications for.to_broadcaster_user_id¶ (
Optional
[str
]) – The broadcaster user ID that received the channel raid you want to get notifications for.callback¶ (
Callable
[[ChannelRaidEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
A notification when a channel becomes active in an active shared chat session.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshared_chatbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
A notification when a channel leaves a shared chat session or the session ends.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshared_chatend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
A notification when the active shared chat session the channel is in changes.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshared_chatupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_shield_mode_begin(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when the broadcaster activates Shield Mode.
Requires the
MODERATOR_READ_SHIELD_MODE
orMODERATOR_MANAGE_SHIELD_MODE
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshield_modebegin
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster that you want to receive notifications about when they activate Shield Mode.moderator_user_id¶ (
str
) – The ID of the broadcaster or one of the broadcaster’s moderators.callback¶ (
Callable
[[ShieldModeEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_shield_mode_end(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when the broadcaster deactivates Shield Mode.
Requires the
MODERATOR_READ_SHIELD_MODE
orMODERATOR_MANAGE_SHIELD_MODE
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshield_modeend
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster that you want to receive notifications about when they deactivate Shield Mode.moderator_user_id¶ (
str
) – The ID of the broadcaster or one of the broadcaster’s moderators.callback¶ (
Callable
[[ShieldModeEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_shoutout_create(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when the specified broadcaster sends a Shoutout.
Requires the
MODERATOR_READ_SHOUTOUTS
orMODERATOR_MANAGE_SHOUTOUTS
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshoutoutcreate
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster that you want to receive notifications about when they send a Shoutout.moderator_user_id¶ (
str
) – The ID of the broadcaster that gave the Shoutout or one of the broadcaster’s moderators.callback¶ (
Callable
[[ChannelShoutoutCreateEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_shoutout_receive(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when the specified broadcaster receives a Shoutout.
Requires the
MODERATOR_READ_SHOUTOUTS
orMODERATOR_MANAGE_SHOUTOUTS
auth scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelshoutoutreceive
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster that you want to receive notifications about when they receive a Shoutout.moderator_user_id¶ (
str
) – The ID of the broadcaster that received the Shoutout or one of the broadcaster’s moderators.callback¶ (
Callable
[[ChannelShoutoutReceiveEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_subscribe(broadcaster_user_id, callback)#
A notification when a specified channel receives a subscriber. This does not include resubscribes.
User Authentication with
CHANNEL_READ_SUBSCRIPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscribe
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_subscription_end(broadcaster_user_id, callback)#
A notification when a subscription to the specified channel ends.
User Authentication with
CHANNEL_READ_SUBSCRIPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_subscription_gift(broadcaster_user_id, callback)#
A notification when a viewer gives a gift subscription to one or more users in the specified channel.
User Authentication with
CHANNEL_READ_SUBSCRIPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptiongift
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_subscription_message(broadcaster_user_id, callback)#
A notification when a user sends a resubscription chat message in a specific channel.
User Authentication with
CHANNEL_READ_SUBSCRIPTIONS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelsubscriptionmessage
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_suspicious_user_message(broadcaster_user_id, moderator_user_id, callback)#
A chat message has been sent by a suspicious user.
Requires
MODERATOR_READ_SUSPICIOUS_USERS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelsuspicious_usermessage
- Parameters:
broadcaster_user_id¶ (
str
) – User ID of the channel to receive chat message events for.moderator_user_id¶ (
str
) – The ID of a user that has permission to moderate the broadcaster’s channel and has granted your app permission to subscribe to this subscription type.callback¶ (
Callable
[[ChannelSuspiciousUserMessageEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_suspicious_user_update(broadcaster_user_id, moderator_user_id, callback)#
A suspicious user has been updated.
Requires
MODERATOR_READ_SUSPICIOUS_USERS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelsuspicious_userupdate
- Parameters:
broadcaster_user_id¶ (
str
) – The broadcaster you want to get chat unban request notifications for.moderator_user_id¶ (
str
) – The ID of a user that has permission to moderate the broadcaster’s channel and has granted your app permission to subscribe to this subscription type.callback¶ (
Callable
[[ChannelSuspiciousUserUpdateEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_unban(broadcaster_user_id, callback)#
A viewer is unbanned from the specified channel.
User Authentication with
CHANNEL_MODERATE
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelunban
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_unban_request_create(broadcaster_user_id, moderator_user_id, callback)#
A user creates an unban request.
Requires
MODERATOR_READ_UNBAN_REQUESTS
orMODERATOR_MANAGE_UNBAN_REQUESTS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelunban_requestcreate
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster you want to get chat unban request notifications for.moderator_user_id¶ (
str
) – The ID of the user that has permission to moderate the broadcaster’s channel and has granted your app permission to subscribe to this subscription type.callback¶ (
Callable
[[ChannelUnbanRequestCreateEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_unban_request_resolve(broadcaster_user_id, moderator_user_id, callback)#
An unban request has been resolved.
Requires
MODERATOR_READ_UNBAN_REQUESTS
orMODERATOR_MANAGE_UNBAN_REQUESTS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelunban_requestresolve
- Parameters:
broadcaster_user_id¶ (
str
) – The ID of the broadcaster you want to get unban request resolution notifications for.moderator_user_id¶ (
str
) – The ID of the user that has permission to moderate the broadcaster’s channel and has granted your app permission to subscribe to this subscription type.callback¶ (
Callable
[[ChannelUnbanRequestResolveEvent
],Awaitable
[None
]]) – function for callback
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_update(broadcaster_user_id, callback)#
A broadcaster updates their channel properties e.g., category, title, mature flag, broadcast, or language.
No Authentication required.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_update_v2(broadcaster_user_id, callback)#
A broadcaster updates their channel properties e.g., category, title, content classification labels or language.
No Authentication required.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_vip_add(broadcaster_user_id, callback)#
A VIP is added to the channel.
Requires
CHANNEL_READ_VIPS
orCHANNEL_MANAGE_VIPS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelvipadd
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_vip_remove(broadcaster_user_id, callback)#
A VIP is removed from the channel.
Requires
CHANNEL_READ_VIPS
orCHANNEL_MANAGE_VIPS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelvipremove
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_warning_acknowledge(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when a warning is acknowledged by a user.
Requires
MODERATOR_READ_WARNINGS
orMODERATOR_MANAGE_WARNINGS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelwarningacknowledge
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_channel_warning_send(broadcaster_user_id, moderator_user_id, callback)#
Sends a notification when a warning is send to a user. Broadcasters and moderators can see the warning’s details.
Requires
MODERATOR_READ_WARNINGS
orMODERATOR_MANAGE_WARNINGS
scope.Note
If you use webhooks, the user in moderator_user_id must have granted your app (client ID) one of the above permissions prior to your app subscribing to this subscription type.
If you use WebSockets, the ID in moderator_user_id must match the user ID in the user access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#channelwarningsend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_drop_entitlement_grant(organisation_id, callback, category_id=None, campaign_id=None)#
An entitlement for a Drop is granted to a user.
App access token required. The client ID associated with the access token must be owned by a user who is part of the specified organization.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#dropentitlementgrant
- Parameters:
organisation_id¶ (
str
) – The organization ID of the organization that owns the game on the developer portal.category_id¶ (
Optional
[str
]) – The category (or game) ID of the game for which entitlement notifications will be received.Default:None
campaign_id¶ (
Optional
[str
]) – The campaign ID for a specific campaign for which entitlement notifications will be received.Default:None
callback¶ (
Callable
[[DropEntitlementGrantEvent
],Awaitable
[None
]]) – function for callback- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_extension_bits_transaction_create(extension_client_id, callback)#
A Bits transaction occurred for a specified Twitch Extension.
The OAuth token client ID must match the Extension client ID.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#extensionbits_transactioncreate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_goal_begin(broadcaster_user_id, callback)#
A goal begins on the specified channel.
User Authentication with
CHANNEL_READ_GOALS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_goal_end(broadcaster_user_id, callback)#
A goal ends on the specified channel.
User Authentication with
CHANNEL_READ_GOALS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_goal_progress(broadcaster_user_id, callback)#
A goal makes progress on the specified channel.
User Authentication with
CHANNEL_READ_GOALS
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelgoalprogress
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_hype_train_begin(broadcaster_user_id, callback)#
A Hype Train begins on the specified channel.
User Authentication with
CHANNEL_READ_HYPE_TRAIN
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainbegin
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_hype_train_end(broadcaster_user_id, callback)#
A Hype Train ends on the specified channel.
User Authentication with
CHANNEL_READ_HYPE_TRAIN
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainend
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_hype_train_progress(broadcaster_user_id, callback)#
A Hype Train makes progress on the specified channel.
User Authentication with
CHANNEL_READ_HYPE_TRAIN
is required.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#channelhype_trainprogress
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_stream_offline(broadcaster_user_id, callback)#
The specified broadcaster stops a stream.
No authorization required.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamoffline
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_stream_online(broadcaster_user_id, callback)#
The specified broadcaster starts a stream.
No authorization required.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#streamonline
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_user_authorization_grant(client_id, callback)#
A user’s authorization has been granted to your client id.
Provided client_id must match the client id in the application access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationgrant
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_user_authorization_revoke(client_id, callback)#
A user’s authorization has been revoked for your client id.
Provided client_id must match the client id in the application access token.
For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userauthorizationrevoke
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_user_update(user_id, callback)#
A user has updated their account.
No authorization required. If you have the
USER_READ_EMAIL
scope, the notification will include email field.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types#userupdate
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async listen_user_whisper_message(user_id, callback)#
Sends a notification when a user receives a whisper. Event Triggers - Anyone whispers the specified user.
Requires
USER_READ_WHISPERS
orUSER_MANAGE_WHISPERS
scope.For more information see here: https://dev.twitch.tv/docs/eventsub/eventsub-subscription-types/#userwhispermessage
- Parameters:
- Raises:
EventSubSubscriptionConflict – if a conflict was found with this subscription (e.g. already subscribed to this exact topic)
EventSubSubscriptionTimeout – if
wait_for_subscription_confirm
is true and the subscription was not fully confirmed in timeEventSubSubscriptionError – if the subscription failed (see error message for details)
TwitchBackendException – if the subscription failed due to a twitch backend error
- Return type:
- Returns:
The id of the topic subscription
- async unsubscribe_all()#
Unsubscribe from all subscriptions
- async unsubscribe_all_known()#
Unsubscribe from all subscriptions known to this client.
- logger: Logger#
The logger used for EventSub related log messages