community.general.google_chat module – Send Google Chat notifications

Note

This module is part of the community.general collection (version 13.1.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.google_chat.

New in community.general 13.1.0

Synopsis

  • Sends notifications to a Google Chat space using an incoming webhook.

  • Incoming webhooks are one-way. They send messages but cannot receive or respond to them.

Parameters

Parameter

Comments

create_new_thread

boolean

Controls behavior when thread_key is set but no matching thread exists.

When true, a new thread is started if no matching thread is found.

When false, the message is only posted if a matching thread already exists, otherwise it fails.

Only used when thread_key is set.

Choices:

  • false

  • true ← (default)

key

string / required

The key request parameter from the incoming webhook URL.

Keep this value secret as it grants the ability to post to the space.

space

string / required

The identifier of the Chat space to post to, taken from the incoming webhook URL.

For a webhook URL of the form https://chat.googleapis.com/v1/spaces/AAAA/messages?key=...&token=..., this is the AAAA part.

text

string / required

The text of the message to send.

Emoji must be supplied as Unicode characters (for example 🚀). The Chat API does not render :shortcode: style emoji in plain text messages as they appear as literal text.

thread_key

string

An arbitrary key used to start or reply to a message thread.

When set, create_new_thread controls the behavior when the thread is not found.

token

string / required

The token request parameter from the incoming webhook URL.

Keep this value secret as it grants the ability to post to the space.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

Google Chat incoming webhooks

Google’s reference for sending messages to Chat with incoming webhooks.

Examples

- name: Send a notification to Google Chat
  community.general.google_chat:
    space: SPACE_ID
    key: KEY
    token: TOKEN
    text: '{{ inventory_hostname }} completed'
  delegate_to: localhost

- name: Start a thread
  community.general.google_chat:
    space: SPACE_ID
    key: KEY
    token: TOKEN
    text: 'Starting a thread'
    thread_key: 'deploy-2026-06-01'
    create_new_thread: true

# Post each deploy step into a single thread. The first message creates the thread
# with create_new_thread=true. Follow-ups use create_new_thread=false so they only
# post if the opening message went through, rather than leaving orphan threads.
# Note: webhooks are rate-limited to 1 request per second per space.
- name: Announce deploy start (starts the thread)
  community.general.google_chat:
    space: "{{ chat_space }}"
    key: "{{ chat_key }}"
    token: "{{ chat_token }}"
    text: "🚀 Starting deploy of *{{ app_version | default('latest') }}* to {{ inventory_hostname }}"
    thread_key: "{{ deploy_thread }}"
    create_new_thread: true
  delegate_to: localhost
  run_once: true
  # deploy_thread is defined once for the play, for example:
  #   deploy_thread: "deploy-{{ inventory_hostname }}-{{ ansible_date_time.iso8601_basic_short }}"

- name: Report a step into the same thread
  community.general.google_chat:
    space: "{{ chat_space }}"
    key: "{{ chat_key }}"
    token: "{{ chat_token }}"
    text: "✅ Step 1/3 – code checked out"
    thread_key: "{{ deploy_thread }}"
    create_new_thread: false
  delegate_to: localhost
  run_once: true

# Wrap risky tasks so a failure posts to the same thread before a play aborts.
- name: Deploy with failure notification
  block:
    - name: Restart service
      ansible.builtin.systemd:
        name: app
        state: restarted

    - name: Report success
      community.general.google_chat:
        space: "{{ chat_space }}"
        key: "{{ chat_key }}"
        token: "{{ chat_token }}"
        text: "🎉 Deploy to {{ inventory_hostname }} complete"
        thread_key: "{{ deploy_thread }}"
        create_new_thread: false
      delegate_to: localhost
      run_once: true
  rescue:
    - name: Report failure into the thread
      community.general.google_chat:
        space: "{{ chat_space }}"
        key: "{{ chat_key }}"
        token: "{{ chat_token }}"
        text: "❌ Deploy to {{ inventory_hostname }} *failed* – {{ ansible_failed_task.name }}"
        thread_key: "{{ deploy_thread }}"
        create_new_thread: false
      delegate_to: localhost
      run_once: true

    - name: Re-raise the failure
      ansible.builtin.fail:
        msg: "Deploy failed at {{ ansible_failed_task.name }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

name

string

Resource name of the created message, returned by the Chat API.

Returned: success

Sample: "spaces/AAAA/messages/BBBB.BBBB"

thread_name

string

Resource name of the thread the message belongs to.

Returned: when the response includes a thread

Sample: "spaces/AAAA/threads/CCCC"

Authors

  • Tom Scholz (@tomscholz)