class chat_downloader.ChatDownloader(headers=None, cookies=None, proxy=None)

Bases: object

Class used to create sessions and download chats.

__init__(headers=None, cookies=None, proxy=None)

Initialise a new session for making requests. Parameters are saved and are sent to the relevant constructor when creating a new session.

  • headers (dict, optional) – Headers to use for subsequent requests, defaults to None

  • cookies (str, optional) – Path of cookies file, defaults to None

  • proxy (str, optional) – Use the specified HTTP/HTTPS/SOCKS proxy. To enable SOCKS proxy, specify a proper scheme. For example socks5:// Pass in an empty string (–proxy “”) for direct connection. Defaults to None


Close all sessions associated with the object

create_session(chat_downloader_class, overwrite=False)
get_chat(url=None, start_time=None, end_time=None, max_attempts=15, retry_timeout=None, interruptible_retry=True, timeout=None, inactivity_timeout=None, max_messages=None, message_groups=<chat_downloader.sites.common.SiteDefault object>, message_types=None, output=None, overwrite=True, sort_keys=True, indent=4, format=<chat_downloader.sites.common.SiteDefault object>, format_file=None, chat_type='live', ignore=None, message_receive_timeout=0.1, buffer_size=4096)

Used to get chat messages from a livestream, video, clip or past broadcast.

  • url (str, optional) – The URL of the livestream, video, clip or past broadcast, defaults to None

  • start_time (float, optional) – Start time in seconds or hh:mm:ss, defaults to None (as early as possible)

  • end_time (float, optional) – End time in seconds or hh:mm:ss, defaults to None (until the end)

  • max_attempts (int, optional) – Maximum number of attempts to retrieve chat messages, defaults to 15

  • retry_timeout (float, optional) – Number of seconds to wait before retrying. Setting this to a negative number will wait for user input. Default is None (use exponential backoff, i.e. immediate, 1s, 2s, 4s, 8s, …)

  • interruptible_retry (bool, optional) – Have the option to skip waiting and immediately retry. Defaults to True

  • timeout (float, optional) – Stop retrieving chat after a certain duration (in seconds), defaults to None

  • inactivity_timeout (float, optional) – Stop getting messages after not receiving anything for a certain duration (in seconds), defaults to None

  • max_messages (int, optional) – Maximum number of messages to retrieve, defaults to None (unlimited)

  • message_groups (SiteDefault, optional) – List of messages groups (a predefined, site-specific collection of message types) to include

  • message_types (list, optional) – List of messages types to include, defaults to None

  • output (str, optional) – Path of the output file, defaults to None (print to standard output)

  • overwrite (bool, optional) – If True, overwrite output file. Otherwise, append to the end of the file. Defaults to True. In both cases, the file (and directories) is created if it does not exist.

  • sort_keys (bool, optional) – Sort keys when outputting to a file, defaults to True

  • indent (Union[int, str], optional) – Number of spaces to indent JSON objects by. If nonnumerical input is provided, this will be used to indent the objects. Defaults to 4

  • format (SiteDefault, optional) – Specify how messages should be formatted for printing, defaults to the site’s default value

  • format_file (str, optional) – Specify the path of the format file to choose formats from, defaults to None

  • chat_type (str, optional) – Specify chat type, defaults to ‘live’

  • ignore (list, optional) – Ignore a list of video ids, defaults to None

  • message_receive_timeout (float, optional) – Time before requesting for new messages, defaults to 0.1

  • buffer_size (int, optional) – Specify a buffer size for retrieving messages, defaults to 4096

  • URLNotProvided – if no URL is provided

  • ChatGeneratorError – if no valid generator can be found for a site

  • SiteNotSupported – if no matching site can be found

  • InvalidURL – if the URL provided is not valid


The appropriate Chat object, given these parameters

Return type:




  1. Message groups and types

    Options are specified as a list of strings.

    from chat_downloader import ChatDownloader
    downloader = ChatDownloader()
    url = ''
    # 1. Using message groups:
    groups_example = downloader.get_chat(url, message_groups=['messages', 'superchat'])
    # 2. Using message types:
    types_example = downloader.get_chat(url, message_types=['membership_item'])
  2. 2