Download media from a file attachment

This guide explains how to use the download method on the Media resource of the Google Chat API to download media (a file) from a message in Google Chat.

When the user sends a message to your app, Google Chat dispatches a MESSAGE interaction event. The interaction event received by your app includes a request body, which is the JSON payload representing the interaction event, including any attachments. The data in the attachment is different depending on whether the attachment is uploaded content (a local file) or is a file stored on Drive. The Media resource represents a file uploaded to Google Chat, like images, videos, and documents. The Attachment resource represents an instance of media—a file—attached to a message. The Attachment resource includes the metadata about the attachment, such as where it's saved.



  • Python 3.6 or greater
  • The pip package management tool
  • The latest Google client libraries for Python. To install or update them, run the following command in your command-line interface:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
  • A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
  • Authorization configured for the Chat app. Downloading media supports both:

Download from a file attachment

To download media from a file attachment, pass the following in your request:

The following example downloads a file attached to a message:


  1. In your working directory, create a file named
  2. Include the following code in

    import io
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    from googleapiclient.http import MediaIoBaseDownload
    # Define your app's authorization scopes.
    # When modifying these scopes, delete the file token.json, if it exists.
    SCOPES = [""]
    def main():
        Authenticates with Chat API via user credentials,
        then downloads a file attached to a message.
        # Authenticate with Google Workspace
        # and get user authorization.
        flow = InstalledAppFlow.from_client_secrets_file(
                    'client_secrets.json', SCOPES)
        creds = flow.run_local_server()
        # Build a service endpoint for Chat API.
        chat = build('chat', 'v1', credentials=creds)
        # Download media resource.
        request =
        file = io.BytesIO()
        downloader = MediaIoBaseDownload(file, request)
        done = False
        while done is False:
            status, done = downloader.next_chunk()
            if status.total_size:
                print(f'Total size: {status.total_size}')
            print(f'Download {int(status.progress() * 100)}')
    if __name__ == '__main__':
  3. In the code, replace RESOURCE_NAME with attachmentDataRef.resourceName, which you can retrieve one of the following ways:

  4. In your working directory, build and run the sample:


If successful, this method returns the file content as bytes.

To download the file contents, choose one of the following approaches:

  • We recommend using the MediaIoBaseDownload class in Python, which contains methods to download the file in sections and save the contents to an output stream.

  • If you must make the HTTP request manually, call the download method and specify the portion of the file that you want to download by using a byte range with the Range header—for example: Range: bytes=500-999.