Google Chat | Sophon

Sophon connects to Google Chat using the Google Chat REST API. You authenticate with a Google Cloud service account (recommended for full two-way messaging) or, for simple outbound-only posting, an incoming webhook URL. Inbound events arrive at Sophon's webhook endpoint and outbound replies are sent through the Chat API.

Prerequisites

A Google Cloud project with the Google Chat API enabled
Permission to create a service account and download its JSON key
A Google Workspace account where you can publish a Chat app
A publicly reachable Sophon Gateway URL (for inbound events) — see Sophon Node

Step-by-Step Setup

1. Create a Service Account

In the Google Cloud Console, select or create a project
Enable the Google Chat API under APIs & Services
Go to IAM & Admin > Service Accounts and click Create Service Account
Give it a name (e.g., "sophon-chat") and create it
Open the service account, go to the Keys tab, and click Add Key > Create new key > JSON
A JSON key file downloads — keep it safe, you will paste its full contents into Sophon

2. Configure the Chat App

In APIs & Services, open the Google Chat API configuration page
Set the app name, avatar, and description
Under Connection settings, choose App URL and point the HTTP endpoint at your Gateway's POST /webhooks/googlechat route
Enable the app for the spaces or users who should reach Sophon

3. Configure in the Sophon Dashboard

Go to Channels and click Add Channel
Select Google Chat
Paste the full Service Account JSON into the credentials field
Optionally set a Default Space ID (format spaces/AAAA...)
Click Test Connection — Sophon verifies it can obtain an access token
Click Activate

4. Test It

In a Google Chat space where the app is installed, mention the Sophon app or send it a direct message. Sophon should reply in the same space.

Configuration Reference

Field	Type	Required	Description
`serviceAccountJson`	secret	Yes*	Full JSON content of the Google Cloud service account key. Enables two-way messaging via the Chat API.
`webhookUrl`	secret	No	Incoming webhook URL for a single space. Outbound-only; use instead of a service account for simple posting.
`spaceId`	text	No	Optional default space (e.g., `spaces/AAAA...`) used when a message has no explicit target space.

*Either serviceAccountJson or webhookUrl must be provided. The service account is required for inbound messages and replying across spaces.

channels.json Example

{
  "id": "google-chat",
  "type": "googlechat",
  "name": "Sophon Google Chat",
  "enabled": true,
  "config": {
    "serviceAccountJson": "<encrypted>",
    "spaceId": "spaces/AAAAexample"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Media Support

The adapter exchanges plain text messages. Image content is sent as its caption text; other attachment types are not handled.

Type	Inbound	Outbound
Text	Yes	Yes
Images	No	Caption only (text)
Audio	No	No
Video	No	No
Documents	No	No

Troubleshooting

Test Connection fails to get a token — Confirm the pasted JSON contains valid client_email and private_key fields and that the Google Chat API is enabled for the project.
No inbound messages — Verify the Chat app's connection setting points at your Gateway's POST /webhooks/googlechat endpoint and that the URL is publicly reachable.
Bot does not reply in a space — The app must be added to that space, and with groupBehavior: "mention-only" it only responds when explicitly mentioned.
Invalid recipient errors — Space IDs must use the spaces/... format (e.g., spaces/AAAAA). A bare ID without the spaces/ prefix is rejected.
Webhook-mode messages not arriving — Incoming webhooks are outbound-only and tied to one space. For receiving messages, switch to service account credentials.

Google ChatNEW