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

Python 3.6 or greater
The pip package management tool

The Google client libraries for Python. Install the client libraries:

pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client

A published Chat app with membership in a Chat space:
- To create and publish a Chat app, see Build a Google Chat app with Cloud Functions.
- To add a Chat app to a Chat space, see Add apps to spaces or conversations in Google Chat.
Authorization configured for the Chat app:
- To set up a service account, see Authenticate and authorize as a service account.
- To set up user authentication, see Authenticate and authorize users.

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

In your working directory, create a file named chat_create_text_message_app.py.

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)

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.
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

In your working directory, create a file named chat_create_text_message_user.py.

Include the following code in chat_create_text_message_user.py:

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

    # 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)

    # 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()

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.
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.

Include links in message text

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!"
}