Google Cloud & Service Account Setup

Pre-release Version

These documentation pages are for the pre-release v2 of this package.

Setting up authentication for Google Chat API in Google Cloud Console (GCP) can be confusing due to the mix of Cloud Projects, Service Accounts, IAM permissions, and Chat App configurations. This guide walks you through setting up everything step by step.

Do You Need a Service Account?

Before setting up a Service Account, check whether your application actually requires one:

Feature / Use Case	Webhook Transport (webhook)	Service Account Transport (service_account)
Send text & rich card notifications	Yes	Yes
Reply to thread by thread key	Yes	Yes
GCP / Service Account required	No (Skip GCP entirely)	Yes (Requires GCP setup)
Update / patch existing sent cards	No	Yes
Delete posted messages	No	Yes
Route dynamically to space IDs (spaces/AAA...)	No	Yes

TIP

If your application only needs to post new notifications to pre-configured spaces using Webhook URLs, you can skip Service Account setup entirely and use the default webhook transport.

Step 1: Create a Google Cloud Project & Enable Google Chat API

1. Navigate to the Google Cloud Console.
2. Click the project selector dropdown in the top header and click New Project (or select an existing project).
3. Enter a project name (e.g. My Laravel Application) and click Create.
4. In the left navigation menu, go to APIs & Services → Library.
5. Search for Google Chat API, click on it, and click Enable.

Step 2: Create a Service Account & Download JSON Key

1. Go to IAM & Admin → Service Accounts in the left menu.
2. Click + Create Service Account at the top.
3. Enter service account details:
   • Service account name: laravel-google-chat-bot
   • Description: Automated notification bot for Laravel
4. Click Create and Continue, then click Done.
5. In the Service Accounts list, click on your newly created service account email.
6. Click the Keys tab, then click Add Key → Create new key.
7. Choose JSON as the key type and click Create.
8. A .json key file will download to your computer.

CAUTION

Never commit your Service Account JSON key file to version control. Store it securely within your application directory (e.g. storage/app/google-chat-key.json) or pass its content via environment variables.

Step 3: Configure Google Chat App Settings in GCP

Google Chat requires your Service Account to be configured as a Google Chat App in Google Cloud Console before Google Chat spaces will accept messages from it.

1. In Google Cloud Console, go to APIs & Services → Enabled APIs & Services.
2. Click Google Chat API, then select the Configuration tab.
3. Complete the form fields:
   • Application info:
     • App name: Enter a name for your bot (e.g. Laravel Notification Bot). This is the name users will see in Google Chat.
     • Avatar URL: (Optional) An HTTPS URL to a square PNG icon (256x256 pixels).
     • Description: Enter a short description (e.g. Sends notifications from app). Maximum 40 characters.
   • Interactive features: Turn on the Enable interactive features toggle switch.
   • Functionality: Check Join spaces and group conversations so the app can be added to room spaces.
   • Connection settings:
     • Select HTTP endpoint URL.
     • Under Triggers, select Use a common HTTP endpoint URL for all triggers.
     • HTTP endpoint URL: Enter a dedicated endpoint URL on your application domain (e.g. https://your-domain.com/webhooks/google-chat or https://your-domain.com/api/google-chat/events).

       NOTE

       GCP requires a valid HTTPS URL for this field. If your application only sends outbound notifications from Laravel and does not process incoming user commands, any valid HTTPS endpoint path on your domain can be entered. Outbound notification delivery will function regardless.

   • Visibility:
     • Check Make this Chat app available to specific people and groups in your domain.
     • Enter email addresses to add individuals and groups in your domain: Enter your email address or group email so members in your domain can add the Chat app to spaces.
4. Click Save at the bottom of the page.

Step 4: Add the Chat App to Your Google Chat Space

Google Chat API calls will fail with 403 Permission Denied or 404 Not Found if the bot has not been explicitly added to the target space first.

1. Open Google Chat.
2. Navigate to the target space where notifications will be delivered.
3. Click the space name in the top header and select Apps & integrations.
4. Click Add apps.
5. Search for your App Name (Laravel Notification Bot) and click Add.

Google Workspace App Allowlisting

If your Chat app does not appear when searching under Add apps, your organisation's Google Workspace Marketplace settings may be restricting unapproved apps. Ask your Google Workspace administrator to review and adjust your domain's app allowlist settings in the Google Admin Console.

Step 5: Configure Laravel

Update your .env file to set the service_account transport driver and the path to your Service Account JSON key file:

GOOGLE_CHAT_DRIVER=service_account
GOOGLE_CHAT_CREDENTIALS=storage/app/google-chat-key.json

Automatic OAuth 2.0 Token Generation & Caching

You do not need to manually generate or refresh OAuth access tokens. The package automatically:

1. Reads your Service Account JSON key file or JSON string.
2. Signs a JWT assertion using native OpenSSL (RS256).
3. Exchanges the assertion with Google's OAuth 2.0 endpoint (https://oauth2.googleapis.com/token) for a Bearer access token.
4. Caches the access token via Laravel's Cache facade for 50 minutes (3000 seconds) to ensure optimal performance.

Troubleshooting & Common Errors

Chat App Does Not Appear When Searching in Google Chat

• Cause: Your Google Workspace domain requires Marketplace app allowlisting.
• Fix: Ask your Google Workspace administrator to update allowlist permissions in the Google Admin Console.

403 Permission Denied or 404 Space Not Found

• Cause: The Google Chat App has not been added to the target space in Google Chat, or the space resource ID is incorrect.
• Fix: Open Google Chat space settings → Apps & integrations → Add apps and add your app name.

Invalid Google Chat Service Account credentials

• Cause: The file path specified in GOOGLE_CHAT_CREDENTIALS does not exist or contains invalid JSON.
• Fix: Verify the file path relative to your Laravel root directory or supply an absolute path.

400 Bad Request: Invalid grant

• Cause: System clock drift when signing JWT assertions, or private key mismatch.
• Fix: Ensure server NTP time synchronisation is active.