(Official API) API Reference¶

Client¶

class Client(client_id: str, client_secret: str, loop: asyncio.AbstractEventLoop | None = None)¶

Represents a client to connect Chzzk (Naver Live Streaming).

async connect(addition_connect: bool = False) → str¶

Connect to session to handle donation or chatting A Client session can have more than one connection. (Maximum Connection: 10)

Parameters:: addition_connect (Optional[bool]) – This parameter used for multiple connections, by default False If addition_connect is False, the connection is completed and a main task is blocked to wait for a response. However addition_connect is True, a task waiting for a response is processed in the background.
Returns:: Returns an unique session ID, if the gateway connects succeeds. A session ID used by subscribe, unsubscribe method.
Return type:: str

Warning

If the main task is empty, as if addition_connect parameter used for all connections is true, all connections are aborted.

Raises:: ChatConnectFailed.max_connection – A Client Session can connect up to 10 sessions. When connection request more than 10 sessions, ChatConnectFailed exception raised.

async disconnect(session_id: str | None = None)¶

Disconnect from session.

Parameters:: session_id (Optional[str]) – A session ID to disconnect from session. When session parameter is empty, all client sessions are disconnected.

async generate_access_token(code: str, state: str) → AccessToken¶

Generate an Access Token. An access token is used by features that require user authentication. (example. creating chat, receiving chat)

Parameters:

code (str) – A code received from generate_authorization_token_url().
state (str) – A state code. This value must be the same as the state of generate_authorization_token_url().

Returns:

A instance that contain user authentic.

Return type:

AccessToken

generate_authorization_token_url(redirect_url: str, state: str) → str¶

Get an url to generate chzzk access token.

Parameters:

redirect_url (str) – Redirect URL after login.
state (str) – A state code to use in state parameter of generate_access_token() method.

async generate_user_client(code: str, state: str) → UserClient¶

Generate user client instance.

Parameters:

code (str) – A code received from generate_authorization_token_url().
state (str) – A state code. This value must be the same as the state of generate_authorization_token_url().

async get_category(query: str, size: int | None = 20) → list[Category]¶

Get category information

Parameters:

query (str) – A name of category.
size (Optional[int], optional) – A number of categories to load at once, by default 20

async get_channel(channel_ids: list[str]) → list[Channel]¶

Get channel information.

Parameters:: channel_ids (list[str]) – An unique ID of the channel to lookup.

async get_live(size: int = 20) → SearchResult[Live]¶

Get live information

Parameters:: size (Optional[int], optional) – A number of lives to load at once, by default 20

async get_user_client(access_token: AccessToken) → UserClient¶

Generate UserClient with prepared access token.

Parameters:: access_token (AccessToken) – A prepared instance of access token.

get_user_client_cached(channel_id: str) → UserClient | None¶

Get UserClient as channel_id. The channel id of UserClient can be obtained via the subscription event of session or when the client has the 유저 정보 조회 scope.

If the channel Id of UserClient is not filled, it can’t found client.

Parameters:: channel_id (str) – A channel ID to get UserClient

async login(state: str | None = None, redirect_url: str | None = None, remote_host: str = 'localhost', remote_port: int = 8080, remote_path: str = '/', success_response: webResponse | None = None, ssl: bool = False) → UserClient¶

Get UserClient instance with oauth2 login process. This login() provides a convenient login method using the aiohttp web server.

Parameters:

state (Optional[str]) – A code used in the authentication process.
redirect_url (Optional[str]) – A redirect_url used in the authentication process.
remote_host (str) – A host url for the temporarily operated web server, default by localhost. If the public environment required, enter “0.0.0.0” value to this parameter.
remote_port (int) – A port for the temporarily operated web server, default by 8080.
remote_path (int) – A path for the temporarily operated web server, default by ‘/’.
success_response (aiohttp.web.Response) – A content to be displayed on the website after successful login.
ssl (bool) – Whether to use http(s) during opening the web browser.

async refresh_access_token(refresh_token: str) → AccessToken¶

Regenerate an Access Token. The Access Token in chzzk follows Open Authorization 2.0 protocol,

which means that access tokens expire after a certain amount of time.

Parameters:: refresh_token (str) – A refresh token to re-generated access token.

async refresh_user_client(refresh_token: str) → UserClient¶

Get UserClient instance with refresh_token.

Parameters:: refresh_token (str) – A refresh token to re-generated access token.

async wait_until_connect()¶: Waits until the session connected.

User Client¶

class UserClient(parent: Client, access_token: AccessToken)¶

Represents a user client to provide feature that requires user authentication.

async add_restrict_channel(user_id: str) → None¶

Add an user to restrict activity.

Parameters:: user_id (str) – A channel id of user to add restrict activity.

async connect(permission: UserPermission, addition_connect: bool = False)¶

Connect to user session to handle donation or chatting

Parameters:

permission (UserPermission) – The permissions to receive, such as chat or donation. After connecting, permission is granted via subscription method.
addition_connect (Optional[bool]) – This parameter used for multiple connections, by default False If addition_connect is False, the connection is completed and a main task is blocked to wait for a response. However addition_connect is True, a task waiting for a response is processed in the background.

Returns:

Returns an unique session ID, if the gateway connects succeeds. A session ID used by subscribe, unsubscribe method.

Return type:

str

Warning

If the main task is empty, as if addition_connect parameter used for all connections is true, all connections are aborted.

async disconnect()¶: Disconnect from session.

async fetch_self() → Channel¶

Get channel based on access token. This method required “유저 정보 조회” API Scope on the access token.

Returns:: A channel based on the access token.
Return type:: Channel

async get_channel_administrator() → list[ChannelPermission]¶: Get users who have channel management permission.

async get_chat_setting() → ChatSetting¶: Get the chat settings.

async get_followers(size: int = 30) → SearchResult[FollowerInfo]¶

Get followers for this channel.

Parameters:: size (Optional[int]) – A number of followers to load at once, by default 30

async get_live_setting() → BrodecastSetting¶: Get the live settings.

async get_restriction(size: int = 20) → SearchResult[RestrictUser]¶

Get users with restricted activities.

Parameters:: size (Optional[int], optional) – A number of lives to load at once, by default 20

async get_stream_key() → str¶: Get the stream key to brodecast

async get_subscribers(size: int = 30, sort: Literal['RECENT', 'LONGER'] = 'RECENT') → SearchResult[SubscriberInfo]¶

Get subscribers for this channel.

Parameters:

size (Optional[int]) – A number of subscribers to load at once, by default 30
sort (Optional[Literal['RECENT', 'LONGER']]) – A method of sorting subscribers.

async refresh()¶: Refresh the access token.

async remove_restrict_channel(user_id: str) → None¶

Remove an user to restrict activity.

Parameters:: user_id (str) – A channel id of user to remove restrict activity.

async revoke()¶: Revoke the access token.

async send_announcement(content: str)¶

Send the announcement to channel This method required “채팅 공지 등록” API Scope on the access token.

Parameters:: content (str) – A content of announcement.

async send_message(content: str) → SentMessage¶

Send the message to channel This method required “채팅 메시지 전송” API Scope on the access token.

Parameters:: content (str) – A content of message.

async subscribe(permission: UserPermission, session_id: str | None = None)¶

Subcribe to events based on UserPermission. Subsribed events are recived in the session.

Parameters:

permission (UserPermission) – The session subscribed evnet.
session_id (Optional[str]) – ID of the session to receive event, by default None The session ID is provided as a parameter in on_connect event

async unsubscribe(permission: UserPermission, session_id: str | None = None)¶

Unsubcribe to events based on UserPermission. The events specified by UserPermission are no longer received.

Parameters:

permission (UserPermission) – The session unsubscribed evnet.
session_id (Optional[str]) – ID of the session to block event, by default None

async wait_until_connect()¶: Waits until the session connected.

property is_connected: bool¶: Returns the gateway had been connected.

property is_expired: bool¶: An access token for user expires after a certain amount of time. Returns status that an access token had been expired.

Event Refenence¶

This section describes the events listened that ChatClient received. You can received event with decorator event method.

For example:

>>> @client.event
... async def on_chat(message: Message):
...     print(message.content)

All event method must be a coroutine. Otherwise, unexpected errors may occur.

async on_chat(message: message.Message)¶

Call when a ChatMesage is created and sent.

Parameters:: message (Message) – The current message.

async on_connect(session_id: str)¶

Called when the client has successfully connected to chzzk chat.

Parameters:: session_id (str) – The unique ID of sesssion. It’s used to subscribe or unsubscribe method.

async on_donation(donation: Donation)¶

Called when a broadcaster received donation. Donation types include Chat, and Video, which are all invoked.

Parameters:: donation (Donation) – The message included donation info.

async on_subscription(subscription: Subscription)¶

Called when a broadcast participant registered a new subscription.

Parameters:: subscription (Subscription) – The message included channel subscription info.

async on_permission_invoked(EventSubscribeMessage message)¶

Called when new permissions are granted by subscribe method.

Parameters:: message (EventSubscribeMessage) – The message included event subscription info.

async on_permission_reinvoked(EventSubscribeMessage message)¶

Called when permissions are retrieved by unsubscribe method.

Parameters:: message (EventSubscribeMessage) – The message included event subscription info.

async on_permission_reinvoked_force(EventSubscribeMessage message)¶

Called when permissions are revoked due to user consent withdrawal, etc.

Parameters:: message (EventSubscribeMessage) – The message included event subscription info.

User Permission¶

class UserPermission¶

The UserPermission Flag is used by session for event subscriptions.

classmethod all() → UserPermission¶: A factory method that creates a UserPermission with everything enabled.

chat¶

Whether chat event are enabled.

Type:: bool

donation¶

Whether donation event are enabled.

Type:: bool

subscription¶

Whether subscription event are enabled.

Type:: bool

Enumeration¶

class FollowingPeriod¶

DAY = 1440¶

FIVE_MINUTE = 5¶

HALF_HOUR = 30¶

HOUR = 60¶

MONTH = 43200¶

NONE = 0¶

TEN_MINUTE = 10¶

WEEK = 10080¶

Authorization¶

class AccessToken¶

access_token: str¶

expires_in: int¶

refresh_token: str¶

scope: str | None¶

token_type: str¶

Category¶

class Category¶

id: str¶

image: str | None¶

name: str¶

type: Literal['GAME', 'SPORTS', 'ETC'] | None¶

Channel¶

class Channel¶

follower_count: int | None¶

id: str¶

image: str | None¶

name: str¶

verified_mark: bool¶

class ChannelPermission¶

created_date: datetime¶

role: Literal['STREAMING_CHANNEL_OWNER', 'STREAMING_CHANNEL_MANAGER', 'STREAMING_CHAT_MANAGER', 'STREAMING_SETTLEMENT_MANAGER']¶

user_id: str¶

user_name: str¶

class FollowerInfo¶

created_date: datetime¶

user_id: str¶

user_name: str¶

class SubscriberInfo¶

created_date: datetime¶

month: int¶

tier_no: int¶

user_id: str¶

user_name: str¶

Chat¶

class ChatSetting¶

allow_subscriber_in_follower_mode: bool¶

chat_available_condition: Literal['NONE', 'REAL_NAME']¶

chat_available_group: Literal['ALL', 'FOLLOWER', 'MANAGER', 'SUBSCRIBER']¶

min_follower_minute: FollowingPeriod¶

Live¶

class Live¶

adult: bool¶

property category: Category | None¶

property channel: Channel¶

concurrent_user_count: int¶

live_id: int¶

live_image_url: str¶

live_title: str¶

open_date: datetime¶

tags: list[str]¶

class BrodecastSetting¶

category: Category¶

tags: list[str]¶

title: str¶

Message¶

class Profile¶

badges: list[Any]¶

nickname: str¶

verified_mark: bool¶

class Message¶

A message instance received from the live. Messages can be received via the on_chat event.

async send(content)¶

Send a message to the received channel

Parameters:: content (str) – A content of message to send.
Returns:: A instance containing the contents of the sent
Return type:: SentMessage

channel: str¶

content: str¶

created_time: datetime.datetime¶

profile: Profile¶

user_id: str¶

class Donation¶

A donation instance received form the live. Donations can be received via the on_donation event.

async send(content)¶

Send a message to the received channel

Parameters:: content (str) – A content of message to send.
Returns:: A instance containing the contents of the sent
Return type:: SentMessage

channel: str¶

donation_text: str¶

donator_id: str¶

donator_name: str¶

pay_amount: int¶

type: Literal['CHAT', 'VIDEO']¶

class Subscription¶

A subscription instance received form the live. Subscription can be received via the on_subscription event.

async send(content)¶

Send a message to the received channel

Parameters:: content (str) – A content of message to send.
Returns:: A instance containing the contents of the sent
Return type:: SentMessage

channel: str¶

month: int¶

subscriber_id: str¶

subscriber_name: str¶

tier_name: str¶

tier_no: int¶

class SentMessage¶

Represents a message sent by client.send() method

async pin() → None¶: Pin the sent message for announcement.

content: str¶

created_time: datetime.datetime¶

id: str¶

Restrict¶

class RestrictUser¶

channel_id: str¶

channel_name: str¶

created_date: datetime¶

release_date: datetime¶

Exceptions¶

exception LoginRequired¶: Exception that’s raised when a method need login.

exception ChatConnectFailed¶

exception ReceiveErrorPacket¶

exception HTTPException¶: Exception that’s raised when an HTTP request operation fails.

exception BadRequestException¶: Exception that’s raised for when status code 400 occurs.

exception UnauthorizedException¶: Exception that’s raised for when status code 401 occurs.

exception ForbiddenException¶: Exception that’s raised for when status code 403 occurs.

exception NotFoundException¶: Exception that’s raised for when status code 404 occurs.

exception TooManyRequestsException¶: Exception that’s raised for when status code 429 occurs.