Threading & Message Updates ​

This guide explains how to group notifications into Google Chat conversation threads and update or replace existing cards using REST API calls.

Message Threading ​

Google Chat supports grouping related notifications into named threads so that updates appear sequentially under the same conversation thread.

Threading by Custom Key (threadKey) ​

Assign a custom string key to group messages together:

php
use NotificationChannels\GoogleChat\GoogleChatMessage;

public function toGoogleChat(object $notifiable): GoogleChatMessage
{
    return GoogleChatMessage::create()
        ->threadKey('order-1048')
        ->text('Order #1048 status changed: Dispatched via Courier');
}

When multiple notifications share the same threadKey, Google Chat threads them under the same conversation in the space.

Threading Options (MessageReplyOption Enum) ​

You can specify how thread creation behaves using MessageReplyOption:

php
use NotificationChannels\GoogleChat\Enums\MessageReplyOption;

GoogleChatMessage::create()
    ->threadKey('order-1048')
    ->replyOption(MessageReplyOption::REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
    ->text('Package delivered to customer.');

Available MessageReplyOption Values: ​

  • MessageReplyOption::REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD (Default): Attempts to post as a reply to an existing thread matching the thread key, or creates a new thread if none exists.
  • MessageReplyOption::REPLY_MESSAGE_OR_FAIL: Replies to the existing thread matching the key, or fails if the thread does not exist.

Updating Sent Messages (PATCH REST API) ​

In many workflows (such as CI/CD deployment pipelines, task approvals, or system incidents), you may want to update or replace an existing card message instead of posting a new message to the room.

To update an existing message, set the target message resource name and update mask using updateMessage():

php
use NotificationChannels\GoogleChat\GoogleChatMessage;
use NotificationChannels\GoogleChat\Card;
use NotificationChannels\GoogleChat\Section;

public function toGoogleChat(object $notifiable): GoogleChatMessage
{
    return GoogleChatMessage::create()
        ->updateMessage(
            name: 'spaces/AAAA1234/messages/msg-98765',
            updateMask: ['cardsV2', 'text']
        )
        ->text('Deployment Completed Successfully!')
        ->card(function (Card $card) {
            $card->header('Deployment #482', 'Status: SUCCESS')
                ->section(function (Section $section) {
                    $section->decoratedText('Build #482 finished in 45s.');
                });
        });
}

Requirements for Message Updates ​

  1. Service Account Transport Driver: Message updates require the service_account driver (GOOGLE_CHAT_DRIVER=service_account).
  2. Resource Name: The target message name must be in the format spaces/{space_id}/messages/{message_id}.
  3. Update Mask: The updateMask array specifies which fields to overwrite in Google Chat (e.g. ['cardsV2'] or ['cardsV2', 'text']).

Google API Reference ​

For detailed documentation on space messages REST endpoints, threading parameters, and patch update masks, consult Google's official REST API reference:

Copyright © 2025 eighteen73