Pin or unpin messages in Google Chat spaces

With the MessagePin resource in the Chat API, your app can pin messages, unpin messages, and get a list of all pinned messages in Google Chat spaces. Pinned messages are visible in the Chat interface for all members of the space. This API helps your app manage pinned messages on behalf of a user.

For information on how users pin messages in spaces, see Pin messages, files & links in spaces & messages.

Prerequisites

Node.js

Considerations

  • You can only pin messages that already exist in a space. You can't create a new message and pin it in the same request.
  • You can't pin messages that are only visible to you. For example, you can't pin private messages that you receive from an app.
  • Each Chat space can have up to 100 pinned messages. If your app tries to pin a 101st message, the API returns an error.

Pin a message

To pin a message with user authentication, pass the following in your request:

  • Specify the chat.spaces.pins or chat.spaces authorization scope.
  • Call messagePins.create.
  • Specify the parent (the space name) and provide a body with the message resource name of the original message.

The following sample pins a message in a space:

Python

  1. In your working directory, create a file named chat_pin_message.py.

  2. Include the following code in chat_pin_message.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.pins"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then pins a message in a space.
    '''

    # Authenticate with Google Workspace and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    service = build('chat', 'v1', credentials=creds)

    # Pin a message.
    result = service.spaces().messagePins().create(
        # The space to pin the message in.
        #
        # Replace SPACE with a space ID or name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',

        # The message to pin.
        body={
            'message': 'spaces/SPACE/messages/MESSAGE'
        }
    ).execute()

    # Print Chat API's response in your command line interface.
    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace the following:

    • SPACE: the ID from the space's name.
    • MESSAGE: the ID from the message's name.

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

    python3 chat_pin_message.py

Unpin a message

To unpin a message with user authentication, pass the following in your request:

  • Specify the chat.spaces.pins or chat.spaces authorization scope.
  • Call messagePins.delete.
  • Set name to the resource name of the MessagePin to delete.

Here's how to unpin a message:

Python

  1. In your working directory, create a file named chat_unpin_message.py.

  2. Include the following code in chat_unpin_message.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.pins"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then unpins a message from a space.
    '''

    # Authenticate with Google Workspace and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    service = build('chat', 'v1', credentials=creds)

    # Unpin a message.
    result = service.spaces().messagePins().delete(
        # The resource name of the message pin to delete.
        #
        # Replace SPACE with a space ID or name, and MESSAGE with the message ID.
        name='spaces/SPACE/messagePins/MESSAGE'
    ).execute()

    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace the following:

    • SPACE: the ID from the space's name.
    • MESSAGE: the ID from the message's name.

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

    python3 chat_unpin_message.py

Get a list of pinned messages

To get a list of pinned messages in spaces that you have access to, use user authentication, and pass the following in your request:

  • Specify one of the reading scopes: chat.spaces.pins.readonly, chat.spaces.readonly, chat.spaces.pins, or chat.spaces.
  • Call messagePins.list.
  • Specify parent as the space name to fetch pinned messages from.

Here's how to list pinned messages:

Python

  1. In your working directory, create a file named chat_list_pinned_messages.py.

  2. Include the following code in chat_list_pinned_messages.py:

    from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
SCOPES = ["https://www.googleapis.com/auth/chat.spaces.pins.readonly"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then lists pinned messages in a space.
    '''

    # Authenticate with Google Workspace and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    service = build('chat', 'v1', credentials=creds)

    # List pinned messages.
    result = service.spaces().messagePins().list(
        # The space to list pinned messages from.
        #
        # Replace SPACE with a space ID or name.
        parent='spaces/SPACE'
    ).execute()

    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace SPACE with the space ID from the space's name.

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

    python3 chat_list_pinned_messages.py