Setting Up the Google Chat Connector

Path: Connectors → Google Chat → Configuration

What this connector does

Google Chat is Google Workspace's team messaging surface. The Google Chat connector authenticates Wazzi as a Chat App — a Google Cloud service account that Google Workspace treats as its own user identity — so your team's AI assistants can list the spaces the app has been invited into, read and summarize conversations, post text or card messages, and reply into threads. Same posture as our Slack bot-token connector.

Wazzi authenticates using a Google Cloud service account (2-legged JWT flow, no user consent needed). Every API call runs under the app's identity — the app must be a member of the target space for the call to succeed. Auth is org-level; per-user access to individual tools is gated by Wazzi's group permissions the same way it is for every other connector.

The Wazzi connector exposes 12 tools grouped by domain:

• Spaces (3 tools) — list_spaces, get_space, find_direct_message.
• Memberships (2 tools) — list_members, get_member.
• Messages — read (2 tools) — list_messages (with time-window filter for summarization), get_message.
• Messages — write (4 tools) — send_message (text or card v2, optional threading), update_message, delete_message, create_thread_reply (post into an existing thread).
• Escape hatch — call_google_chat_endpoint for operations not yet wrapped by a typed tool (attachments, space events, read state).

Before you start

You'll need:

• A Google Cloud project. Any project works — a new one is fine.
• Google Workspace admin access on your domain — required to authorize the OAuth scopes for the Chat App (step 5). Setup can't complete without an admin performing this step.
• A downloaded service account key (JSON file) — instructions below.

Setup — configuring the Chat App

1. Enable the Google Chat API.

1. Sign in to console.cloud.google.com and open (or create) a project.
2. Navigate to APIs & Services → Library, search for Google Chat API, and click Enable.

2. Create a service account.

1. Go to IAM & Admin → Service Accounts.
2. Click Create service account. Give it a name like wazzi-chat-bot. Skip the optional role assignment — Chat API auth doesn't need IAM roles.
3. Once created, open the service account and note the Unique ID field (a big number, e.g. 100188727664130429068) — you'll need it in step 5.
4. Go to the Keys tab, click Add Key → Create new key → JSON. Download the JSON file and keep it somewhere safe — Google won't show it again.

3. Configure the Chat App.

1. Back in APIs & Services, click Google Chat API in the enabled-APIs list.
2. Open the Configuration tab.
3. Fill in:
   • App name — this is what shows in Chat when the app posts or is @-mentioned (e.g. Wazzi).
   • Avatar URL — a public HTTPS image URL.
   • Description — one-line summary.
   • Functionality — enable Receive 1:1 messages and Join spaces and group conversations so the app can be added to spaces and reached in DMs.
   • Connection settings — pick App URL and enter any valid HTTPS URL (Wazzi doesn't currently receive Chat events, so this is a placeholder). This field is required by Google but not used by this connector.
   • Visibility — add only the specific people (or Google Groups) who will actually install the Chat app into a space. In practice that's usually one or two admins or ops-team members — the person or people doing setup. Visibility controls who can find and install the app; it does not control who can use it once installed (anyone in a space where the app is a member can invoke it). Keeping this list narrow limits who can add the app to unrelated spaces. Do not paste your whole company here, and do not publish the app to Marketplace.
   • Logs — leave logging off unless you need to debug.
4. Save.

Reference: Google's step-by-step is at developers.google.com/workspace/chat/authenticate-authorize-chat-app. API surface reference: the REST reference.

4. Add the Chat App to each space you want it to reach.

The Chat API only sees spaces the app is a member of. In Google Chat, signed in as one of the people you added to the Visibility list in step 3:

1. Open the target space.
2. Click the space name → Apps & integrations → Add apps.
3. Search for the app by the name you set in step 3 and click Add.
4. Repeat for every space Wazzi should read or post in.

For direct messages, just @-mention the app in Chat and it becomes a 1:1 DM.

5. Authorize the Chat App's OAuth scopes in the Workspace admin console.

Before Wazzi can read or write on your behalf, a Google Workspace admin has to explicitly trust the service account for the scopes the connector uses. Without this step, list / read tools will 403 with "The administrator must grant the app the required OAuth authorization scope for this action."

1. Sign in to admin.google.com as a Google Workspace admin.
2. Navigate to Security → Access and data control → API controls.
3. At the bottom of the page, click Manage domain-wide delegation.
4. Click Add new.
5. Fill in:
   • Client ID — the Unique ID of the service account you noted in step 2 (a long numeric string).
   • OAuth scopes — paste the two scopes the connector uses, comma-separated:
     https://www.googleapis.com/auth/chat.bot, https://www.googleapis.com/auth/chat.app.messages.readonly
6. Click Authorize.

Propagation is usually near-instant but can take up to 5 minutes. If you plan to use list_messages or read message history authored by other users, this step is required — send-side tools (send_message, update_message, delete_message, create_thread_reply) work with just chat.bot, but read-side tools need the chat.app.messages.readonly grant.

6. Paste the service account JSON into Wazzi.

You'll land on Google Chat's Configuration tab:

1. Open the JSON file you downloaded in step 2 and copy its entire contents.
2. Paste it into the Service Account JSON field on the Wazzi Configuration tab.
3. Click Test Connection — Wazzi mints an access token and probes GET /v1/spaces?pageSize=1. On success it reports either:
   • "Connected — service account <email> reaches at least one space" — you're done.
   • "Connected — service account is valid, but the Chat app isn't a member of any space yet" — auth works, but you skipped step 4. Add the app to a space and re-test.
4. Click Save Configuration. Google Chat moves to the Active section of the catalog.

What this connector unlocks for your team

Once configured, members with the right MCP permissions can ask Claude / ChatGPT / Cursor things like:

• "Summarize the last 24 hours of conversation in the #ops space."
• "List every space Wazzi has access to and how many members each has."
• "Find the DM thread with Brendon and post 'The scorecard refresh finished — 3 red cells this week' to it."
• "Post a card summarizing today's Daily Orange for Phoenix to the market's Google Chat space."
• "Reply into the escalation thread <thread_name> with the incident postmortem link."
• "Which spaces did the app join in the last week? Pull membership timestamps."

The exact set of available actions depends on which MCP toggles are flipped on for the user's group in Wazzi — see Managing Permissions. Write tools (send / update / delete / reply) can be restricted independently from reads.

Troubleshooting

• The Chat app doesn't appear in a space's Add apps search. Almost always the Visibility field in Chat API → Configuration. The app only appears in the Add-apps search for accounts you've explicitly listed there. Add the email of the person doing the install (or a Google Group containing them), save, wait ~1–2 minutes for propagation, then retry the Add-apps dialog signed in as that account. Also confirm App status is Live and Functionality has Join spaces and group conversations enabled.
• "The administrator must grant the app the required OAuth authorization scope for this action" (403). You skipped step 5. A Google Workspace admin needs to authorize the Chat App's OAuth scopes under admin.google.com → Security → Access and data control → API controls → Manage domain-wide delegation. Add the service account's Unique ID as the Client ID, and paste both https://www.googleapis.com/auth/chat.bot and https://www.googleapis.com/auth/chat.app.messages.readonly as the scopes. Propagation is usually near-instant.
• "service_account_json is not valid JSON". The paste got truncated or a stray character snuck in. Re-open the downloaded file, select all, copy, and re-paste. Every service account JSON starts with {"type": "service_account", "project_id": ... and ends with "}.
• "Google Chat API rejected credentials: 401 UNAUTHENTICATED". The private key in the JSON was regenerated (revoking the old one) or the service account was deleted. Create a fresh key in Google Cloud Console → IAM & Admin → Service Accounts → Keys, download the new JSON, and re-paste.
• "Google Chat API rejected credentials: 403". Usually one of: (a) the Google Chat API isn't enabled on the project (enable it under APIs & Services), (b) the Chat App configuration hasn't been saved as Live, or (c) admin-console scope authorization (step 5) hasn't been done. Check the Chat API → Configuration page and confirm the app status; verify the domain-wide delegation entry exists in the admin console.
• "Connected — Chat app isn't a member of any space yet". Auth works but you skipped step 4 of setup. Add the Chat App to at least one space in Google Chat (space menu → Apps & integrations → Add apps).
• Tool calls return "PERMISSION_DENIED" for a specific space. The Chat App isn't a member of that space. Ask the space manager to add it, or use list_spaces first to see which spaces are actually reachable.
• list_messages returns 0 rows on a busy space. Chat's default order is newest-first, so it should always return something. If it's empty, the app was just added and hasn't been given permission to read history — check the app's configuration in Chat API → Configuration → Functionality, and confirm the chat.app.messages.readonly scope was authorized in step 5.
• update_message or delete_message fails with "FAILED_PRECONDITION". Chat only lets the app modify messages IT authored — you can't edit or delete a human user's messages via app auth. This is by design.

Best practices

• Keep the Visibility list narrow. Only the person or people who will install the app into spaces need to be listed. There's no benefit to adding the whole company here — it doesn't affect who can invoke the app once it's in a space.
• Use a dedicated service account. Don't reuse one that already grants access to other APIs — narrow blast radius, easier to audit, and rotation is a one-project change.
• Restrict who can invoke write tools. send_message, update_message, delete_message, and create_thread_reply post to real spaces with real people watching. Only grant those permissions to groups that need them — see Managing Permissions.
• Filter list_messages by createTime. For summarization prompts, always bound the window (e.g. filter: "createTime > \"2026-08-24T00:00:00Z\"") — unbounded lists on a busy space blow the token budget fast.
• Use thread_key for cross-run threading. If an agent posts follow-ups to the same conversation over time, pass a stable thread_key string (e.g. a Wazzi incident id) on send_message. Chat creates the thread the first time and every subsequent message with the same key lands in it — no need to remember the thread's resource name.
• Rotate the service account key periodically. Google Cloud → Service Accounts → Keys → create new → download → paste into Wazzi → delete the old key. Old keys stay valid until you explicitly delete them.
• Prefer find_direct_message over storing DM space names. DM spaces are lazily created; using the find endpoint each time avoids stale references when someone hasn't DM'd the app before.

Frequently asked questions

Does Wazzi store my service account JSON in plaintext?
No. The JSON is encrypted at rest with per-org keys and only decrypted at the moment an outbound call is made.

Who should I add to the Visibility field on the Chat API Configuration page?
Only the people (or Google Groups) who will actually install the app into a Chat space. Typically one or two admins or ops team members. Visibility controls who can find the app in Chat's "Add apps" search — it doesn't affect who can use it once it's in a space. Keeping the list narrow limits who can install the app into unrelated spaces without adding any friction for regular users.

Why does the connector need a Workspace admin to authorize scopes?
Google splits Chat API scopes into "user auth" and "app auth" flavors. The scopes this connector uses (chat.bot + chat.app.messages.readonly) are app-auth scopes for service accounts — and Google requires an admin to explicitly trust each service account for each scope via Manage domain-wide delegation. It's a one-time step per service account and doesn't need to be redone unless you rotate the service account itself.

Can users from another organization see or post to my spaces?
No. Each org's Google Chat connector is bound to that org's own service account, and Wazzi tool calls are org-scoped server-side. Cross-org access is impossible even if two orgs configured the same Chat App.

Why can't the app read messages from a space I know it's in?
Two most common causes: (a) the chat.app.messages.readonly scope was not authorized in step 5's admin console step, or (b) the app's Functionality settings in Chat API → Configuration don't have Join spaces and group conversations enabled. Some spaces (external / cross-org) may also be governed by your Workspace admin's Chat sharing policy.

Can I have multiple Google Workspace domains in one connector?
No — the connector authenticates as one service account, which lives in one Google Cloud project and is trusted by whichever domains have added the Chat App. If you need to reach spaces in multiple Workspaces, file a feature request for multi-instance support.

Can the app impersonate a specific user (post as Alice, not as the Chat App)?
Not with this connector. Impersonation requires user OAuth (a per-user consent flow) rather than app auth. That's a separate integration pattern and we haven't shipped it yet.

Does it support Google Chat's card v2 rich payloads?
Yes — send_message, update_message, and create_thread_reply all accept a cardsV2 array. See Google's card v2 reference for the payload shape.

What's next

• Restrict who in your org can invoke Google Chat actions: Managing Permissions.
• Wire Google Chat into your AI tool: Connecting Claude or Connecting ChatGPT.
• Prefer Slack? See Setting Up the Slack Connector.
• Browse other connectors: Browsing the Connectors Catalog.