PubSub#
This is a full implementation of the PubSub API of twitch. PubSub enables you to subscribe to a topic, for updates (e.g., when a user cheers in a channel).
Read more about it on the Twitch API Documentation.
Note
You always need User Authentication while using this!
Code Example#
from twitchAPI.pubsub import PubSub
from twitchAPI.twitch import Twitch
from twitchAPI.helper import first
from twitchAPI.type import AuthScope
from twitchAPI.oauth import UserAuthenticator
import asyncio
from pprint import pprint
from uuid import UUID
APP_ID = 'my_app_id'
APP_SECRET = 'my_app_secret'
USER_SCOPE = [AuthScope.WHISPERS_READ]
TARGET_CHANNEL = 'teekeks42'
async def callback_whisper(uuid: UUID, data: dict) -> None:
print('got callback for UUID ' + str(uuid))
pprint(data)
async def run_example():
# setting up Authentication and getting your user id
twitch = await Twitch(APP_ID, APP_SECRET)
auth = UserAuthenticator(twitch, [AuthScope.WHISPERS_READ], force_verify=False)
token, refresh_token = await auth.authenticate()
# you can get your user auth token and user auth refresh token following the example in twitchAPI.oauth
await twitch.set_user_authentication(token, [AuthScope.WHISPERS_READ], refresh_token)
user = await first(twitch.get_users(logins=[TARGET_CHANNEL]))
# starting up PubSub
pubsub = PubSub(twitch)
pubsub.start()
# you can either start listening before or after you started pubsub.
uuid = await pubsub.listen_whispers(user.id, callback_whisper)
input('press ENTER to close...')
# you do not need to unlisten to topics before stopping but you can listen and unlisten at any moment you want
await pubsub.unlisten(uuid)
pubsub.stop()
await twitch.close()
asyncio.run(run_example())
Class Documentation#
- class twitchAPI.pubsub.PubSub#
Bases:
object
The PubSub client
- __init__(twitch, callback_loop=None)#
-
ping_frequency:
int
# With which frequency in seconds a ping command is send. You probably don’t want to change this. This should never be shorter than 12 + ping_jitter seconds to avoid problems with the pong timeout.
Default:120
-
ping_jitter:
int
# time in seconds added or subtracted from ping_frequency. You probably don’t want to change this.
Default:4
-
listen_confirm_timeout:
int
# maximum time in seconds waited for a listen confirm.
Default:30
- start()#
Start the PubSub Client
- Raises:
RuntimeError – if already started
- Return type:
- stop()#
Stop the PubSub Client
- Raises:
RuntimeError – if the client is not running
- Return type:
- async unlisten(uuid)#
Stop listening to a specific Topic subscription.
- Parameters:
uuid¶ (UUID) – The UUID of the subscription you want to stop listening to
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the server response is something else than suspected
PubSubListenTimeoutException – if the unsubscription is not confirmed in the time set by listen_confirm_timeout
- Return type:
- async listen_whispers(user_id, callback_func)#
You are notified when anyone whispers the specified user or the specified user whispers to anyone.
Requires the
WHISPERS_READ
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_bits_v1(channel_id, callback_func)#
You are notified when anyone cheers in the specified channel.
Requires the
BITS_READ
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_bits(channel_id, callback_func)#
You are notified when anyone cheers in the specified channel.
Requires the
BITS_READ
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_bits_badge_notification(channel_id, callback_func)#
You are notified when a user earns a new Bits badge in the given channel, and chooses to share the notification with chat.
Requires the
BITS_READ
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_channel_points(channel_id, callback_func)#
You are notified when a custom reward is redeemed in the channel.
Requires the
CHANNEL_READ_REDEMPTIONS
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_channel_subscriptions(channel_id, callback_func)#
You are notified when anyone subscribes (first month), resubscribes (subsequent months), or gifts a subscription to a channel. Subgift subscription messages contain recipient information.
Requires the
CHANNEL_READ_SUBSCRIPTIONS
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_chat_moderator_actions(user_id, channel_id, callback_func)#
Supports moderators listening to the topic, as well as users listening to the topic to receive their own events. Examples of moderator actions are bans, unbans, timeouts, deleting messages, changing chat mode (followers-only, subs-only), changing AutoMod levels, and adding a mod.
Requires the
CHANNEL_MODERATE
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_automod_queue(moderator_id, channel_id, callback_func)#
AutoMod flags a message as potentially inappropriate, and when a moderator takes action on a message.
Requires the
CHANNEL_MODERATE
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_user_moderation_notifications(user_id, channel_id, callback_func)#
A user’s message held by AutoMod has been approved or denied.
Requires the
CHAT_READ
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_low_trust_users(moderator_id, channel_id, callback_func)#
The broadcaster or a moderator updates the low trust status of a user, or a new message has been sent in chat by a potential ban evader or a bans shared user.
Requires the
CHANNEL_MODERATE
AuthScope.- Parameters:
- Return type:
- Returns:
UUID of this subscription
- Raises:
TwitchAuthorizationException – if Token is not valid
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
MissingScopeException – if required AuthScope is missing from Token
- async listen_undocumented_topic(topic, callback_func)#
Listen to one of the many undocumented PubSub topics.
Make sure that you have the required AuthScope for your topic set, since this lib can not check it for you!
Warning
Using a undocumented topic can break at any time, use at your own risk!
- Parameters:
- Raises:
TwitchAuthorizationException – if Token is not valid or does not have the required AuthScope
TwitchBackendException – if the Twitch Server has a problem
TwitchAPIException – if the subscription response is something else than suspected
PubSubListenTimeoutException – if the subscription is not confirmed in the time set by listen_confirm_timeout
- Return type:
-
listen_confirm_timeout:
-
ping_jitter: