Create a text message

This page describes how to create messages that appear inline as if typed by a user. Use text messages to present simple information to users. For information about how you can construct more complex messages that generate cards in the chat, see Create a card message.

Prerequisites

To run the examples in this guide, you need the following prerequisites:

Python

Anatomy of a text message

Any message in Google Chat is represented as a JSON object. The following example is a basic message that specifies a simple plaintext body:

{
  "text": "Your pizza delivery is here!"
}

If posted into Google Chat, this example renders like the following:

App responding with a message that your pizza delivery is here!

Create an asynchronous text message

The following section explains how to create a text message with app authentication and user authentication.

Create a text message with app authentication

Here's how to create a text message with app authentication:

Python

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

    from httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'service_account.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. In the code, replace SPACE with a space name, which you can obtain from the spaces.list() method in the Chat API, or from a space's URL.

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

    python3 chat_create_text_message_app.py
    

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

Create a text message with user authentication

Here's how to create a text message with user authentication:

Python

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

    from __future__ import print_function
    
    import os.path
    
    from google.auth.transport.requests import Request
    from google.oauth2.credentials import Credentials
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    from googleapiclient.errors import HttpError
    
    # 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.create"]
    
    def main():
        '''
        Authenticates with Chat API via user credentials,
        then creates a text message in a Chat space.
        '''
    
        # Start with no credentials.
        creds = None
    
        # Check for the file token.json. If it exists, use it for authentication.
        # The file token.json stores the user's access and refresh tokens, and is
        # created automatically when the authorization flow completes for the first
        # time.
        if os.path.exists('token.json'):
            creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    
        # If there are no valid credentials available, let the user log in.
        if not creds or not creds.valid:
            if creds and creds.expired and creds.refresh_token:
                creds.refresh(Request())
            else:
                flow = InstalledAppFlow.from_client_secrets_file(
    
                    # The client_secrets.json file gets generated when you create
                    # an OAuth 2.0 Client ID. See Authenticate as a user in the Chat
                    # developer documentation.
                    'client_secrets.json', SCOPES)
    
                creds = flow.run_local_server(port=0)
    
            # Save the credentials for the next run in a file
            # named token.json.
            with open('token.json', 'w') as token:
                token.write(creds.to_json())
    
        # Build a service endpoint for Chat API.
        chat = build('chat', 'v1', credentials=creds)
    
        # Use the service endpoint to call Chat API.
        result = chat.spaces().messages().create(
    
            # The space to create the message in.
            #
            # Replace SPACE with a space name.
            # Obtain the space name from the spaces resource of Chat API,
            # or from a space's URL.
            parent='spaces/SPACE',
    
            # The message to create.
            body={'text': 'Hello, world!'}
    
        ).execute()
    
        # Prints details about the created membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. In the code, replace SPACE with a space name, which you can obtain from the spaces.list() method in the Chat API, or from a space's URL.

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

    python3 chat_create_text_message_user.py
    

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

Format texts in messages

Google Chat lets you add basic formatting to the message text, including bold, italic, and strikethrough. To format text, wrap it with the following symbols:

Format Symbol Example Result
Bold * *hello* hello
Italic _ (underscore) _hello_ hello
Strikethrough ~ ~hello~ hello
Monospace ` (backquote) `hello` hello
Monospace block ``` (three backquotes) ```
Hello
World
```
Hello
World

For example, consider the following JSON:

{
  "text": "Your pizza delivery *has arrived*!\nThank you for using _Pizza Bot!_"
}

This places a message like this into the Chat space:

App resonding with the text has arrived bolded.

This text markup syntax is the same syntax that applies to messages typed by users, which is why it is distinct from the HTML-based formatting applied to text inside cards.

If you include a plain link URL in your message text, such as http://example.com/, Google Chat uses this as the link text and automatically hyperlinks that text to the specified URL.

To provide alternate link text for your link, use the following syntax:

Syntax Rendering
<https://example.com/|LINK_TEXT> LINK_TEXT

The pipe and link text are optional, so that <https://example.com/> and https://example.com/ are equivalent.

Messages that @mention specific users

A Chat app can @mention a user in a message by providing their USER_ID in the following syntax. To determine the USER_ID for a user, examine the sender field of the incoming message from the user.

<users/USER_ID>

This string is substituted with an @mention of the specified user. For example, consider the following JSON:

{
    "text": "Hey <users/123456789012345678901>! Thank you for using _Pizza bot!_"
}

This produces a result like the following:

App responding with a person's username.

Messages that @mention all users

You can use the user ID all to @mention all the human users in a space. For example:

{
    "text": "Important message for <users/all>: Code freeze starts at midnight tonight!"
}