With the [`MessagePin` resource](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messagePins)
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](https://support.google.com/chat/answer/15622437).

## Prerequisites


### Node.js

- A Business or Enterprise [Google Workspace](https://support.google.com/a/answer/6043576) account with access to [Google Chat](https://workspace.google.com/products/chat/).

<!-- -->

- Set up your environment:
  - [Create a Google Cloud project](https://developers.google.com/workspace/guides/create-project).
  - [Configure the OAuth consent screen](https://developers.google.com/workspace/guides/configure-oauth-consent).
  - [Enable and configure the Google Chat API](https://developers.google.com/workspace/chat/configure-chat-api) with a name, icon, and description for your Chat app.
  - Install the Node.js [Cloud Client Library](https://developers.google.com/workspace/chat/libraries?tab=nodejs#cloud-client-libraries).
  - [Create OAuth client ID credentials](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#step-2:) for a desktop application. To run the sample in this guide, save the credentials as a JSON file named `credentials.json` to your local directory.

  For guidance, complete the steps for setting up your environment in this [quickstart](https://developers.google.com/workspace/chat/api/guides/quickstart/nodejs
  #set-up-environment).
- [Choose an authorization scope](https://developers.google.com/workspace/chat/authenticate-authorize#asynchronous-chat-calls) that supports user authentication.


> [!NOTE]
> The code samples in this page use the gRPC API interface with the Google Cloud client libraries. Alternatively, you can use the REST API interface. For more information about the gRPC and REST interfaces, see [Google Chat API overview](https://developers.google.com/workspace/chat/api/reference).

<br />

## 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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
pass the following in your request:

- Specify the `chat.spaces.pins` or `chat.spaces` authorization scope.
- Call [`messagePins.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.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`](https://developers.google.com/workspace/chat/api/reference/rpc/google.chat.v1#google.chat.v1.Space.FIELDS.string.google.chat.v1.Space.name).
   - `MESSAGE`: the ID from the message's [`name`](https://developers.google.com/workspace/chat/api/reference/rpc/google.chat.v1#google.chat.v1.Message.FIELDS.string.google.chat.v1.Message.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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), pass the following in your request:

- Specify the `chat.spaces.pins` or `chat.spaces` authorization scope.
- Call [`messagePins.delete`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.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`](https://developers.google.com/workspace/chat/api/reference/rpc/google.chat.v1#google.chat.v1.Space.FIELDS.string.google.chat.v1.Space.name).
   - `MESSAGE`: the ID from the message's [`name`](https://developers.google.com/workspace/chat/api/reference/rpc/google.chat.v1#google.chat.v1.Message.FIELDS.string.google.chat.v1.Message.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](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user), 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`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.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`](https://developers.google.com/workspace/chat/api/reference/rpc/google.chat.v1#google.chat.v1.Space.FIELDS.string.google.chat.v1.Space.name).

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

       python3 chat_list_pinned_messages.py

## Related topics

- [Format a message](https://developers.google.com/workspace/chat/format-messages).
- [Delete a message](https://developers.google.com/workspace/chat/delete-messages).
- [Get details about a message](https://developers.google.com/workspace/chat/get-messages).
- [List messages in a space](https://developers.google.com/workspace/chat/list-messages).
- [Update a message](https://developers.google.com/workspace/chat/update-messages).
- [Send a message](https://developers.google.com/workspace/chat/create-messages).