Update a message

This guide explains how to use the patch method on the Message resource of the Google Chat API to update a text or card message in a space. Update a message to change message attributes, such as what it says, or the content of a card. You can also prepend a text message to a card message, or append a card to a text message.

Chat API also supports the update method, but we strongly recommend calling the patch method because it uses a PATCH HTTP request while update uses a PUT HTTP request. To learn more, see the AIP-134's PATCH and PUT section.

The Message resource represents a text or card message in Google Chat. You can create, get, update, or delete a message in the Google Chat API by calling corresponding methods. To learn more about text and card messages, see Google Chat messages overview.

Prerequisites

Python

  • 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 google-auth
  • 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:

Update a text message, or prepend a text message to a card message, with user authentication

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

  • The chat.messages authorization scope.
  • The name of the message to update.
  • updateMask='text'
  • A body that specifies the updated message.

If the updated message is a card message, then the text message prepends to the card message (which continues to display).

Here's how to update a text message, or prepend a text message to a card message with user authentication:

Python

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

  2. Include the following code in chat_update_text_message_user.py:

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

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.messages"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then updates 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)

    # Update a Chat message.
    result = chat.spaces().messages().patch(

      # The message to update, and the updated message.
      #
      # Replace SPACE with a space name.
      # Obtain the space name from the spaces resource of Chat API,
      # or from a space's URL.
      #
      # Replace MESSAGE with a message name.
      # Obtain the message name from the response body returned
      # after creating a message asynchronously with Chat REST API.
      name='spaces/SPACE/messages/MESSAGE',
      updateMask='text',
      body={'text': 'Updated message!'}

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace the following:

    • SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
    • MESSAGE: a message name, which you can obtain from the response body returned after creating a message asynchronously with the Chat API, or with the custom name assigned to the message at creation.

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

    python3 chat_update_text_message_user.py

Update a text message, or prepend a text message to a card message, with app authentication

To update a text message with app authentication, pass the following in your request:

  • The chat.bot authorization scope.
  • The name of the message to update.
  • updateMask='text'
  • A body that specifies the updated message.

If the updated message is a card message, then the text message prepends to the card message (which continues to display).

Here's how to update a text message to a text message, or prepend a text message to a card message with app authentication:

Python

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

  2. Include the following code in chat_update_text_message_app.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=CREDENTIALS)

# Update a Chat message.
result = chat.spaces().messages().patch(

  # The message to update, and the updated message.
  #
  # Replace SPACE with a space name.
  # Obtain the space name from the spaces resource of Chat API,
  # or from a space's URL.
  #
  # Replace MESSAGE with a message name.
  # Obtain the message name from the response body returned
  # after creating a message asynchronously with Chat REST API.
  name='spaces/SPACE/messages/MESSAGE',
  updateMask='text',
  body={'text': 'Updated message!'}

).execute()

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

  3. In the code, replace the following:

    • SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
    • MESSAGE: a message name, which you can obtain from the response body returned after creating a message asynchronously with the Chat API, or with the custom name assigned to the message at creation.

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

    python3 chat_update_text_message_app.py

Update a card message, or append a card message to a text message

To update a card message, pass the following in your request:

  • The chat.bot authorization scope. Updating a card message requires app authentication.
  • The name of the message to update.
  • updateMask='cardsV2'
  • A body that specifies the updated message.

If the updated message is a text message, then a card appends to the text message (which continues to display). If the updated message is itself a card, then the displayed card is updated.

Here's how to update a message to a card message:

Python

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

  2. Include the following code in chat_update_card_message.py:

    from google.oauth2 import service_account
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', credentials=CREDENTIALS)

# Update a Chat message.
result = chat.spaces().messages().patch(

  # The message to update, and the updated message.
  #
  # Replace SPACE with a space name.
  # Obtain the space name from the spaces resource of Chat API,
  # or from a space's URL.
  #
  # Replace MESSAGE with a message name.
  # Obtain the message name from the response body returned
  # after creating a message asynchronously with Chat REST API.
  name='spaces/SPACE/messages/MESSAGE',
  updateMask='cardsV2',
  body=
  {
    'cardsV2': [{
      'cardId': 'updateCardMessage',
      'card': {
        'header': {
          'title': 'An Updated Card Message!',
          'subtitle': 'Updated with Chat REST API',
          'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
          'imageType': 'CIRCLE'
        },
        'sections': [
          {
            'widgets': [
              {
                'buttonList': {
                  'buttons': [
                    {
                      'text': 'Read the docs!',
                      'onClick': {
                        'openLink': {
                          'url': 'https://developers.google.com/chat'
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }]
  }

).execute()

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

  3. In the code, replace the following:

    • SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.

    • MESSAGE: a message name, which you can obtain from the response body returned after creating a message asynchronously with the Chat API, or with the custom name assigned to the message at creation.

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

    python3 chat_update_card_message.py

The Chat API returns an instance of Message that details the message that's updated.

Update a message with multiple field paths simultaneously

When a message is updated, you can update multiple message field paths at the time. For example, in an update message request, you can specify a change to the text and cardsv2 field paths at the same time, which updates both the message's text and card. If the message includes only text and no card, a card is added to the message. For more information about the supported field paths, see updateMask parameters.

To update both the text and card of a message with user authentication, pass the following in your request:

  • The chat.messages authorization scope.
  • The name of the message to update.

  • An updateMask that specifies the message field paths to update, separated by commas: updateMask='text', 'cardsV2'.

  • A body that specifies the updated message, including all updated field paths.

Here's how to update the text and cardsV2 field paths in a message with user authentication:

Python

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

  2. Include the following code in chat_update_text_message_user.py:

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

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.messages"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then updates 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)

    # Update a Chat message.
    result = chat.spaces().messages().patch(

      # The message to update, and the updated message.
      #
      # Replace SPACE with a space name.
      # Obtain the space name from the spaces resource of Chat API,
      # or from a space's URL.
      #
      # Replace MESSAGE with a message name.
      # Obtain the message name from the response body returned
      # after creating a message asynchronously with Chat REST API.
      name='spaces/SPACE/messages/MESSAGE',
      updateMask='text,cardsV2',
      body=
      {'text': 'Updated message!',
            'cardsV2': [{
              'cardId': 'updateCardMessage',
              'card': {
                'header': {
                  'title': 'An Updated Card Message!',
                  'subtitle': 'Updated with Chat REST API',
                  'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
                  'imageType': 'CIRCLE'
                },
                'sections': [
                  {
                    'widgets': [
                      {
                        'buttonList': {
                          'buttons': [
                            {
                              'text': 'Read the docs!',
                              'onClick': {
                                'openLink': {
                                  'url': 'https://developers.google.com/chat'
                                }
                              }
                            }
                          ]
                        }
                      }
                    ]
                  }
                ]
              }
            }]
      }

    ).execute()

    # Prints details about the created membership.
    print(result)

if __name__ == '__main__':
    main()

  3. In the code, replace the following:

    • SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
    • MESSAGE: a message name, which you can obtain from the response body returned after creating a message asynchronously with the Chat API, or with the custom name assigned to the message at creation.

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

    python3 chat_update_text_message_user.py