Chatter

Attributes
Methods
class twitchio.Chatter

Class which represents a User in a chat room and has sent a message.

This class inherits from PartialUser and contains additional information about the chatting user. Most of the additional information is received in the form of the badges sent by Twitch.

Note

You usually wouldn’t construct this class yourself. You will receive it in Command callbacks, via Context and in the event_message event.

property channel: PartialUser

Property returning the channel in the form of a PartialUser this chatter belongs to.

property staff: bool

A property returning a bool indicating whether the chatter is Twitch Staff.

This bool should always be True when the chatter is a Twitch Staff.

property admin: bool

A property returning a bool indicating whether the chatter is Twitch Admin.

This bool should always be True when the chatter is a Twitch Admin.

property broadcaster: bool

A property returning a bool indicating whether the chatter is the broadcaster.

This bool should always be True when the chatter is the broadcaster.

property moderator: bool

A property returning a bool indicating whether the chatter is a moderator.

This bool should always be True when the chatter is a moderator.

property lead_moderator: bool

A property returning a bool indicating whether the chatter is the lead moderator.

This bool should always be True when the chatter is the lead moderator.

property vip: bool

A property returning a bool indicating whether the chatter is a VIP.

property artist: bool

A property returning a bool indicating whether the chatter is an artist for the channel.

property founder: bool

A property returning a bool indicating whether the chatter is a founder of the channel.

property subscriber: bool

A property returning a bool indicating whether the chatter is a subscriber of the channel.

property no_audio: bool

A property returning a bool indicating whether the chatter is watching without audio.

property no_video: bool

A property returning a bool indicating whether the chatter is watching without video.

property partner: bool

A property returning a bool indicating whether the chatter is a Twitch partner.

property turbo: bool

A property returning a bool indicating whether the chatter has Twitch Turbo.

property prime: bool

A property returning a bool indicating whether the chatter has Twitch Prime.

property colour: twitchio.utils.Colour | None

Property returning the colour of the chatter as a Colour.

There is an alias for this property named color.

Could be None if the chatter has not set a colour.

property color: twitchio.utils.Colour | None

Property returning the color of the chatter as a Colour.

There is an alias for this property named colour.

Could be None if the chatter has not set a color.

property badges: list[ChatMessageBadge]

Property returning a list of ChatMessageBadge associated with the chatter in this channel.

async ban(moderator: str | PartialUser, reason: str | None = None) → Ban

This function is a coroutine.

Ban the chatter from the associated channel/broadcaster.

Important

This is different to the ban_user() as it will ban this chatter directly in the associated channel in the object.

Note

You must have a user access token that includes the moderator:manage:banned_users scope to do this.

Parameters

  • moderator (str | PartialUser) – The ID of or the PartialUser object of the moderator issuing this action. You must have a token stored with the moderator:manage:banned_users scope for this moderator.

  • reason (str | None) – An optional reason this chatter is being banned. If provided the length of the reason must not be more than 500 characters long. Defaults to None.

Raises

  • ValueError – The length of the reason parameter exceeds 500 characters.

  • TypeError – You can not ban the broadcaster.

  • HTTPException – The request to ban the chatter failed.

Returns

The Ban object for this ban.

Return type

Ban

async timeout(moderator: str | PartialUser | None = None, duration: int = 600, reason: str | None = None) → Timeout

This function is a coroutine.

Timeout the chatter from the associated channel/broadcaster.

Important

This is different to the timeout_user() as it will timeout this chatter directly in the associated channel in the object.

Note

You must have a user access token that includes the moderator:manage:banned_users scope to do this.

Parameters

  • moderator (str | PartialUser | None) – The ID of or the PartialUser object of the moderator issuing this action. You must have a token stored with the moderator:manage:banned_users scope for this moderator.

  • duration (int) –

    The duration of the timeout in seconds. The minimum duration is 1 second and the maximum is 1_209_600 seconds (2 weeks).

    To end the chatters timeout early, set this field to 1, or use the unban_user() endpoint.

    The default is 600 which is ten minutes.

  • reason (str | None) – An optional reason this chatter is being banned. If provided the length of the reason must not be more than 500 characters long. Defaults to None.

async warn(moderator: str | twitchio.user.PartialUser, reason: str) → Warning

This function is a coroutine.

Send this chatter a warning, preventing them from chat interaction until the warning is acknowledged. New warnings can be issued to a chatter / user when they already have a warning in the channel (new warning will replace old warning).

Important

This is different to the warn_user() as it will warn this chatter directly for the associated channel in the object.

Note

Requires a user access token that includes the moderator:manage:warnings scope. moderator id must match the user id in the user access token.

Parameters

  • moderator (str | int | PartialUser) – The ID, or PartialUser, of the user who requested the warning.

  • reason (str) – The reason provided for warning.

Returns

Warning object.

Return type

Warning

async delete_message(moderator: str | twitchio.user.PartialUser) → None

This function is a coroutine.

Delete the message that this Chatter object was created from.

Important

Restrictions:

  • The message must have been created within the last 6 hours.

  • The chatter must not be the broadcaster.

  • The chatter must not be another moderator.

Note

The moderator provided must have the moderator:manage:chat_messages scope.

Parameters

moderator (str | int | PartialUser) – The ID, or PartialUser, of the user that has permission to moderate the broadcaster’s chat room. This ID must match the user ID in the user access token.

async block(source: Optional[Literal['chat', 'whisper']] = None, reason: Optional[Literal['harassment', 'spam', 'other']] = None) → None

This function is a coroutine.

Blocks this chatter from interacting with or having contact with the broadcaster.

The user ID in the OAuth token identifies the broadcaster who is blocking the user.

Important

This is different to the block_user() as it will block this chatter directly from the associated channel in the object.

Note

Requires a user access token that includes the user:manage:blocked_users scope.

Parameters

  • source (Literal["chat", "whisper"] | None) –

    The location where the harassment took place that is causing the brodcaster to block the user. Possible values are:

    • chat

    • whisper

  • reason (Literal["harassment", "spam", "other"] | None) –

    The reason that the broadcaster is blocking the user. Possible values are:

    • harassment

    • spam

    • other

Return type

None

async follow_info() → ChannelFollowerEvent | None

This function is a coroutine.

Check whether this Chatter is following the broadcaster. If the user is not following then this will return None.

Important

You must have a user token for the broadcaster / channel that this chatter is being checked in.

Note

Requires user access token that includes the moderator:read:followers scope.

Return type

ChannelFollowerEvent | None