README
¶
Google Chat — Installation & Configuration Guide
This guide walks you through connecting Genie to Google Chat using HTTP push for incoming events and the Chat API for outgoing messages. A public-facing HTTP endpoint is required to receive push events from Google Chat.
Prerequisites
- A Google Workspace account (Google Chat is not available on personal Gmail accounts).
- Access to Google Cloud Console (https://console.cloud.google.com).
- A public endpoint (URL) where Google Chat can send push events — this can be achieved via:
- A cloud VM or container with a public IP
- A reverse proxy / tunnel (e.g., ngrok for development)
- Access to your Genie configuration file (
.genie.toml).
Step 1: Create a Google Cloud Project
- Go to Google Cloud Console.
- Click the project dropdown → New Project.
- Enter a project name (e.g.,
genie-bot) and click Create. - Select the newly created project.
Step 2: Enable the Google Chat API
- Navigate to APIs & Services → Library.
- Search for Google Chat API.
- Click Google Chat API → Enable.
Step 3: OAuth credentials (same as Gmail/Calendar/Drive)
Google Chat uses the logged-in user OAuth token — the same one used for Gmail, Calendar, and Drive. No service account is required.
- In APIs & Services → Credentials, create an OAuth 2.0 Client ID (Desktop app or Web application, with redirect URI as used by
genie grant). - Build Genie with
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETset (or configure them in your deployment). - Run
genie grant(or complete the Google sign-in duringgenie setup) so the token is stored. The default browser flow includes thechat.messagesscope.
Step 4: Configure the Chat App
- Navigate to APIs & Services → Google Chat API → Configuration tab (or search for "Google Chat API" in the console and click Manage).
- Fill in the app settings:
| Setting | Value |
|---|---|
| App name | Genie (or your preferred name) |
| Avatar URL | (Optional) URL to your bot's avatar image |
| Description | AI-powered assistant |
| Functionality | Check Receive 1:1 messages and Join spaces and group conversations |
| Connection settings | Select HTTP endpoint URL |
| HTTP endpoint URL | https://your-domain.com/ (your public endpoint — Genie listens on /) |
| Visibility | Choose who can discover and use the bot in your organization |
- Click Save.
Step 5: Configure Genie
Add the following to your .genie.toml configuration file:
[messenger]
platform = "googlechat"
[messenger.googlechat]
# No fields; uses logged-in user token (SecretProvider).
No credentials_file is used. Genie uses the same logged-in user token as Gmail/Calendar/Drive (from genie grant or TokenFile/keyring). Ensure you have signed in with Google so the token includes the Chat scope.
Step 6: Add the Bot to a Space
- In Google Chat, open an existing space or create a new one.
- Click the space name → Manage members → Add people & bots.
- Search for your bot's name (e.g.,
Genie). - Select it and click Add.
For 1:1 conversations, find the bot in the Chat search bar and start a direct message.
Verification
After starting Genie, you should see the log messages:
starting Google Chat HTTP push listener addr=:8080
connected to Google Chat
Send a message to the bot in Google Chat to confirm everything is working.
Troubleshooting
| Issue | Solution |
|---|---|
Google Chat requires WithSecretProvider |
The app passes the secret provider when creating the messenger; ensure you are running the official Genie binary that wires this. |
google chat token / google chat credentials |
Sign in with Google via genie grant (or setup). Ensure the OAuth client has the Chat API scope and the token is stored (keyring or TokenFile). |
failed to create Google Chat service |
Ensure the Chat API is enabled in your GCP project and your OAuth client is configured for the Chat API. |
| Bot doesn't receive messages | Verify the HTTP endpoint URL in the Chat API configuration matches your public URL. |
405 Method Not Allowed |
Google Chat sends POST requests. Ensure your endpoint accepts POST. |
| Bot not visible in Chat | Check the Visibility settings in the Chat API configuration. The bot may be restricted to specific users or OUs. |
Required Configuration Summary
| Item | Where to Find |
|---|---|
| Logged-in user token | Run genie grant or complete Google sign-in during setup; token is stored in keyring or TokenFile. |
| Chat API HTTP endpoint | GCP Console → APIs & Services → Google Chat API → Configuration |
Network Requirements
Genie must be reachable from the internet for Google Chat to deliver push events. Ensure your firewall or security group allows inbound HTTPS traffic to the shared HTTP server.
Google Chat push events originate from Google's infrastructure. Refer to Google's IP ranges if you need to allowlist source IPs.
Documentation
¶
Overview ¶
Package googlechat provides a Messenger adapter for Google Chat using HTTP push for incoming events and the Chat API for outgoing messages.
The adapter wraps google.golang.org/api/chat/v1 and exposes an HTTP endpoint that receives push events from Google Chat. Outgoing messages are sent via the Chat API's spaces.messages.create method.
Transport: HTTP push (public endpoint required for incoming events).
Authentication ¶
Google Chat uses the same logged-in user OAuth token as Gmail/Calendar/Drive. The application must pass messenger.WithSecretProvider(sp) when creating the messenger so the adapter can resolve the token (TokenFile, keyring, or env). No service account credentials file is used.
Migration from service account ¶
Previous versions used credentials_file and listen_addr with a service account. That configuration has been removed. Existing deployments should migrate to logged-in user OAuth: run setup and connect Google (same token as Gmail/Calendar). See the installation documentation for migration steps.
Usage ¶
m := googlechat.New(googlechat.Config{}, messenger.WithSecretProvider(sp))
if err := m.Connect(ctx); err != nil { /* handle */ }
defer m.Disconnect(ctx)
Index ¶
- type Config
- type Messenger
- func (m *Messenger) Connect(ctx context.Context) (http.Handler, error)
- func (m *Messenger) ConnectionInfo() string
- func (m *Messenger) Disconnect(ctx context.Context) error
- func (m *Messenger) FormatApproval(req messenger.SendRequest, info messenger.ApprovalInfo) messenger.SendRequest
- func (m *Messenger) FormatClarification(req messenger.SendRequest, info messenger.ClarificationInfo) messenger.SendRequest
- func (m *Messenger) Platform() messenger.Platform
- func (m *Messenger) Receive(_ context.Context) (<-chan messenger.IncomingMessage, error)
- func (m *Messenger) Send(ctx context.Context, req messenger.SendRequest) (messenger.SendResponse, error)
- func (m *Messenger) UpdateMessage(_ context.Context, _ messenger.UpdateRequest) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct{}
Config holds Google Chat-specific configuration. Authentication uses the logged-in user token via SecretProvider (pass WithSecretProvider when creating the messenger).
type Messenger ¶
type Messenger struct {
// contains filtered or unexported fields
}
Messenger implements the messenger.Messenger interface for Google Chat. It manages the Chat API client, returns an HTTP handler for incoming push events, and tracks connection state through an internal mutex.
func (*Messenger) Connect ¶
Connect initializes the Chat API client and returns an http.Handler for receiving Google Chat push events. The caller mounts this handler on a shared HTTP mux at the desired context path.
The adapter DOES NOT start its own http.Server.
func (*Messenger) ConnectionInfo ¶
ConnectionInfo returns connection instructions for the Google Chat adapter.
func (*Messenger) Disconnect ¶
Disconnect gracefully shuts down the Google Chat adapter.
func (*Messenger) FormatApproval ¶
func (m *Messenger) FormatApproval(req messenger.SendRequest, info messenger.ApprovalInfo) messenger.SendRequest
FormatApproval builds a Google Chat Cards v2 message for an approval notification. This satisfies the messenger.ApprovalFormatter interface, keeping all Google Chat-specific formatting inside the adapter.
func (*Messenger) FormatClarification ¶
func (m *Messenger) FormatClarification(req messenger.SendRequest, info messenger.ClarificationInfo) messenger.SendRequest
FormatClarification builds a Google Chat Cards v2 message for a clarification question.
func (*Messenger) Send ¶
func (m *Messenger) Send(ctx context.Context, req messenger.SendRequest) (messenger.SendResponse, error)
Send delivers a message to a Google Chat space. If req.Metadata["cards_v2"] contains a []*chat.CardWithId, the message is sent with Cards v2 formatting (the text field is used as the plaintext fallback).
func (*Messenger) UpdateMessage ¶
UpdateMessage is a no-op for Google Chat — the adapter does not currently support editing previously sent messages. Returns nil to satisfy the Messenger interface without error.
Source Files