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.

    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() 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
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
  • user_id (str) – ID of the User

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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
  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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
  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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
  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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
  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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_READ_SUBSCRIPTIONS AuthScope.

Parameters
  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
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
  • user_id (str) – ID of the User

  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
listen_automod_queue(moderator_id: str, channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) uuid.UUID

AutoMod flags a message as potentially inappropriate, and when a moderator takes action on a message.

Requires the twitchAPI.types.AuthScope.CHANNEL_MODERATE AuthScope.

Parameters
  • moderator_id (str) – ID of the Moderator

  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
listen_user_moderation_notifications(user_id: str, channel_id: str, callback_func: Callable[[uuid.UUID, dict], None]) uuid.UUID

A user’s message held by AutoMod has been approved or denied.

Requires the twitchAPI.types.AuthScope.CHAT_READ AuthScope.

Parameters
  • user_id (str) – ID of the User

  • channel_id (str) – ID of the Channel

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Returns

UUID of this subscription

Return type

UUID

Raises
listen_undocumented_topic(topic: str, callback_func: Callable[[uuid.UUID, dict], None]) uuid.UUID

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
  • topic (str) – the topic string

  • callback_func (Callable[[UUID,dict],None]) – Function called on event

Return type

UUID

Raises