twitchAPI.pubsub¶
PubSub client¶
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!
Short code example:¶
from twitchAPI.pubsub import PubSub
from twitchAPI.twitch import Twitch
from twitchAPI.types import AuthScope
from pprint import pprint
from uuid import UUID
def callback_whisper(uuid: UUID, data: dict) -> None:
print('got callback for UUID ' + str(uuid))
pprint(data)
# setting up Authentication and getting your user id
twitch = Twitch('my_app_id', 'my_app_secret')
twitch.authenticate_app([])
# you can get your user auth token and user auth refresh token following the example in twitchAPI.oauth
twitch.set_user_authentication('my_user_auth_token', [AuthScope.WHISPERS_READ], 'my_user_auth_refresh_token')
user_id = twitch.get_users(logins=['my_username'])['data'][0]['id']
# starting up PubSub
pubsub = PubSub(twitch)
pubsub.start()
# you can either start listening before or after you started pubsub.
uuid = 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
pubsub.unlisten(uuid)
pubsub.stop()
Class Documentation:¶
-
class
twitchAPI.pubsub.
PubSub
(twitch: twitchAPI.twitch.Twitch)¶ The PubSub client
Variables: - 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.
-
listen_bits
(channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ You are notified when anyone cheers in the specified channel.
Requires the
twitchAPI.types.AuthScope.BITS_READ
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_bits_badge_notification
(channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ 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
twitchAPI.types.AuthScope.BITS_READ
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_bits_v1
(channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ You are notified when anyone cheers in the specified channel.
Requires the
twitchAPI.types.AuthScope.BITS_READ
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_channel_points
(channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ You are notified when a custom reward is redeemed in the channel.
Requires the
twitchAPI.types.AuthScope.CHANNEL_READ_REDEMPTIONS
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_channel_subscriptions
(channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ 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
twitchAPI.types.AuthScope.CHANNEL_SUBSCRIPTIONS
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_chat_moderator_actions
(user_id: str, channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ 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
twitchAPI.types.AuthScope.CHANNEL_MODERATE
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
listen_whispers
(user_id: str, callback_func: Callable[[uuid.UUID, dict], None]) → uuid.UUID¶ You are notified when anyone whispers the specified user or the specified user whispers to anyone.
Requires the
twitchAPI.types.AuthScope.WHISPERS_READ
AuthScope.Parameters: Returns: UUID of this subscription
Return type: 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
-
start
() → None¶ Start the PubSub Client
Raises: RuntimeError – if already started
-
stop
() → None¶ Stop the PubSub Client
Raises: RuntimeError – if the client is not running
-
unlisten
(uuid: uuid.UUID) → None¶ 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