laravel-google-chat

Loading repository…

Unknown

Google Chat Notification Channel

This package provides a Google Chat notification channel for Laravel 12.x and 13.x using webhooks.

Requirements

PHP ^8.2
Laravel ^12.0 or ^13.0

Installation

Require the package via Composer:

bash

composer require eighteen73/laravel-google-chat

Then publish the configuration file to your project:

bash

php artisan vendor:publish --tag=google-chat-config

This will create config/google-chat.php in your application.

Configuration

Default Space

If your application sends notifications to a single Google Chat space, configure the space key in config/google-chat.php:

php

// config/google-chat.php

return [
    'space' => env('GOOGLE_CHAT_DEFAULT_SPACE', null),
];

Notifications that do not specify a destination room will automatically route to this default space.

CAUTION

If your application transmits sensitive data via notifications, keep space set to null to require explicit routing destinations for every notification.

Alternate Spaces (Preferred)

To route notifications to different spaces (such as #sales, #dev, or #alerts), define named spaces in config/google-chat.php:

php

// config/google-chat.php

return [
    'spaces' => [
        'sales' => env('GOOGLE_CHAT_SPACE_SALES'),
        'dev' => env('GOOGLE_CHAT_SPACE_DEV'),
        'alerts' => env('GOOGLE_CHAT_SPACE_ALERTS'),
    ],
];

You can target a named space when sending a notification:

php

// Explicit route call
Notification::route('googleChat', 'sales')->notify(new InvoicePaid($invoice));

// Inside your GoogleChatMessage builder
GoogleChatMessage::create()->to('dev')->text('Deployment complete.');

// Inside your Notifiable model
public function routeNotificationForGoogleChat(): string
{
    return 'alerts';
}

Explicit Webhook URLs

You can also pass full webhook URLs directly instead of space aliases:

php

GoogleChatMessage::create()
    ->to('https://chat.googleapis.com/v1/spaces/XXXX/messages?key=YYYY&token=ZZZZ')
    ->text('Direct notification');

Local Development / Test Space Override

During local development, you can override all notification routing to direct messages into a single test space without modifying existing notification code.

Set the GOOGLE_CHAT_TEST_SPACE environment variable in your .env file:

dotenv

GOOGLE_CHAT_TEST_SPACE=https://chat.googleapis.com/v1/spaces/XXXX/messages?key=YYYY&token=ZZZZ

When this value is present, all outbound Google Chat notifications will be directed to this test space endpoint.

Usage

Specify GoogleChatChannel::class in the via() method of your notification class:

php

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use NotificationChannels\GoogleChat\GoogleChatChannel;
use NotificationChannels\GoogleChat\GoogleChatMessage;

class OrderPlacedNotification extends Notification
{
    public function via(object $notifiable): array
    {
        return [
            GoogleChatChannel::class,
        ];
    }

    public function toGoogleChat(object $notifiable): GoogleChatMessage
    {
        return GoogleChatMessage::create('A new order has been placed!');
    }
}

Simple Messages

GoogleChatMessage provides fluent methods to format text:

php

public function toGoogleChat(object $notifiable): GoogleChatMessage
{
    return GoogleChatMessage::create()
        ->bold('System Alert!')
        ->line('An unhandled exception occurred:')
        ->monospaceBlock($this->errorMessage)
        ->italic('Need assistance? ')
        ->link('https://status.example.com', 'View Status Page');
}

Available text styling methods:

text(string $text): Append text.
line(string $text): Append text on a new line.
bold(string $text): Append bold text.
italic(string $text): Append italic text.
strikethrough(string $text) / strike(string $text): Append strikethrough text.
monospace(string $text) / mono(string $text): Append inline monospace text.
monospaceBlock(string $text): Append a block of monospace text.
link(string $url, ?string $label = null): Append a link.
mention(string $userId): Mention a specific user ID.
mentionAll(?string $prepend = null, ?string $append = null): Mention @all.

Card Messages

Card messages provide structured layouts with headers, key-value rows, images, and buttons.

php

use NotificationChannels\GoogleChat\Card;
use NotificationChannels\GoogleChat\Section;
use NotificationChannels\GoogleChat\Widgets\KeyValue;
use NotificationChannels\GoogleChat\Widgets\TextParagraph;
use NotificationChannels\GoogleChat\Components\Button\TextButton;
use NotificationChannels\GoogleChat\Enums\Icon;
use NotificationChannels\GoogleChat\Enums\ImageStyle;

public function toGoogleChat(object $notifiable): GoogleChatMessage
{
    return GoogleChatMessage::create()
        ->text('New Payment Received')
        ->card(
            Card::create()
                ->header(
                    'Invoice #1048',
                    'Paid by Acme Corp',
                    'https://cdn.example.com/logo.png',
                    ImageStyle::CIRCULAR
                )
                ->section(
                    Section::create(
                        KeyValue::create('Amount Paid', 'GBP 1,250.00')
                            ->icon(Icon::DOLLAR)
                            ->button(
                                TextButton::create('https://example.com/invoices/1048', 'View Invoice')
                            )
                    )
                )
        );
}

Card Layout Structure

Card
|-- Header (optional)
|-- Sections
    |-- Section
        |-- Header (optional)
        |-- Widgets
            |-- KeyValue
            |-- TextParagraph
            |-- Image
            |-- Buttons

Message Threads

To group notifications into threads or reply to an existing thread in spaces configured with inline replies:

php

// Thread by key (creates a new thread or replies to an existing key)
GoogleChatMessage::create('Follow-up comment')
    ->thread('order-1048');

// Thread by resource name
GoogleChatMessage::create('Follow-up comment')
    ->thread('spaces/AAAA/threads/BBBB', true);

API Reference

GoogleChatMessage

NotificationChannels\GoogleChat\GoogleChatMessage

Method	Description
`static create(?string $text = null)`	Instantiates a new message instance.
`to(string $space)`	Target space key or webhook URL.
`thread(string $thread, bool $isResourceName = false)`	Attach thread key or resource name.
`text(string $text)`	Append text to simple content.
`line(string $text)`	Append line break and text.
`bold(string $text)`	Append bold text.
`italic(string $text)`	Append italic text.
`strikethrough(string $text)`	Append strikethrough text.
`monospace(string $text)`	Append inline code snippet.
`monospaceBlock(string $text)`	Append code block snippet.
`link(string $url, ?string $label = null)`	Append a hyperlink.
`mention(string $userId)`	Mention specific user by ID.
`mentionAll(?string $prependText = null, ?string $appendText = null)`	Mention `@all`.
`card(Card\|array $card)`	Attach card component(s).

Card & Section

NotificationChannels\GoogleChat\Card

static create(Section|array|null $sections = null)
header(string $title, ?string $subtitle = null, ?string $imageUrl = null, ?string $imageStyle = null)
section(Section|array $sections)

NotificationChannels\GoogleChat\Section

static create(AbstractWidget|array|null $widgets = null)
header(string $text)
widget(AbstractWidget|array $widgets)

Widgets

TextParagraph: Rich text formatting within card sections (bold, italic, underline, strikethrough, color, link, break).
KeyValue: Structured key-value rows with optional icon, click action, and button (topLabel, content, bottomLabel, icon, onClick, button).
Image: Display image with optional click-through action (imageUrl, onClick).
Buttons: Container for horizontal button actions (button).

Buttons

TextButton: Text button with destination URL (create($url, $displayText)).
ImageButton: Icon/image button with destination URL (create($url, $icon)).

Google Chat Notification Channel ​

Requirements ​

Installation ​

Configuration ​

Default Space ​

Alternate Spaces (Preferred) ​

Explicit Webhook URLs ​

Local Development / Test Space Override ​

Usage ​

Simple Messages ​

Card Messages ​

Card Layout Structure ​

Message Threads ​

API Reference ​

GoogleChatMessage ​

Card & Section ​

Widgets ​

Buttons ​