Skip to main content
Google Chat The Google Chat app turns a Google Chat bot into the user-facing interface of a Prisme.ai AI Knowledge agent. Unlike most connectors, the integration is reverse-direction: Google Chat is the caller and Prisme.ai is the server. Each tenant workspace installs the app, fills its own Google service account JSON, AI Knowledge project ID and API key, and pastes a generated HTTPS endpoint URL into the Google Chat app configuration. Incoming user messages are forwarded to the configured AI Knowledge project; the reply is posted back into the same Google Chat thread, with per-thread conversational context preserved.

1:1 chats and spaces

Receives direct messages and ADDED_TO_SPACE events, with configurable greetings and fallback texts.

Per-thread context

A compact conversation history is kept per Google Chat thread and trimmed to a configurable number of turns.

Async acknowledgement

Optionally acknowledges Google Chat immediately and posts the final agent answer back to the thread asynchronously via the Google Chat REST API.

​
Prerequisites

  • A Google Workspace account with admin-level access to publish a Chat app for at least one user (a regular Gmail account cannot host a Chat app).
  • A Google Cloud project with the Google Chat API enabled at console.cloud.google.com/apis/library/chat.googleapis.com.
  • A Google service account in the same project, with a JSON key downloaded. No IAM role is required — the OAuth scope https://www.googleapis.com/auth/chat.bot is what authorizes outbound calls to the Chat REST API. The full service account JSON (including client_email, private_key, private_key_id) is what you paste in the workspace secret.
  • An AI Knowledge project that the bot will query, plus its API key (created from the project settings).

​
Installation

  1. Go to Apps in the workspace that will host the bot.
  2. Search for Google Chat and install it.
  3. Open the freshly installed app instance — endpointToken and googleChatEndpointUrl are auto-populated by the onInstall flow, and two empty workspace secrets are provisioned for you to fill (see below).

​
Configure the credentials

The googleChatServiceAccount and googleChatAgentApiKey fields are wired to workspace secrets of the same name. Fill the values in the workspace Secrets section to keep them out of the app instance configuration.
1

Open workspace Secrets

From Studio, open the workspace’s Secrets panel.
2

Fill googleChatServiceAccount

Paste the full service account JSON exported from Google Cloud Console (must contain client_email, private_key, private_key_id).
3

Fill googleChatAgentApiKey

Paste the AI Knowledge project API key.
4

Fill the AI Knowledge project ID

Back on the app instance configuration, set AI Knowledge project ID (agent.projectId) to the project the bot should query.

​
Wire the Google Chat side

1

Open the Chat API Configuration

Open Google Cloud Console → Google Chat API → Configuration. Fill the app name, avatar URL and description.
2

Pick the trigger surfaces

Under Functionality, enable Receive 1:1 messages and Join spaces and group conversations.
3

Paste the endpoint URL

Under Connection settings, select HTTP endpoint URL and paste the value of googleChatEndpointUrl from the app instance (it embeds the workspace ID, the app instance slug and a single-use token). Set Authentication Audience to the same URL.
4

Restrict the visibility

Under Visibility, choose Make this Chat app available to specific people and groups in <your-domain> and add the test email addresses. Save.
5

Test the bot

Open chat.google.com, search for the app under Internal apps, send a message and verify the acknowledgement text (config.ackText) appears immediately and the agent reply lands in the same thread.

​
Configuration

Google Chat endpoint URL and Endpoint token are populated on install — do not edit them by hand. To rotate the service account JSON or the AI Knowledge API key, update the corresponding workspace secret; the app instance picks up the new value on the next call.

​
How it works

  1. Google Chat sends an interaction event (MESSAGE, ADDED_TO_SPACE, etc.) to the configured HTTP endpoint URL. The connector validates the query-string token against the configured endpointToken and rejects mismatches with Unauthorized Google Chat request..
  2. For MESSAGE events, the incoming Google Chat payload is normalized into a compact internal shape (chatEvent) covering the text, the space name, the thread key and the sender identity.
  3. In async mode (default), the connector emits a GoogleChat.message.received event and immediately returns the acknowledgement text. The downstream onGoogleChatMessage handler:
    • calls askPrismeAgent, which forwards the conversation (with the per-thread history kept in global.googleChatThreads) to the configured AI Knowledge project,
    • posts the final reply back to the same Google Chat thread via the Chat REST API (sendGoogleChatMessage), using a JWT signed with the service account JSON (getGoogleChatAccessToken),
    • emits GoogleChat.reply.sent or GoogleChat.reply.failed for observability.
  4. In synchronous mode (asyncReplies: false), the agent call happens inline and the response text is returned in the initial HTTP response.
The conversation history is stored per threadKey (derived from space.name + message.thread.name) and trimmed to maxHistoryTurns × 2 messages.

​
Error Handling

​
Common Issues

Bot does not appear in chat.google.com — Verify the visibility section of the Google Chat app configuration lists your email (or a group you belong to), and that you searched the Internal apps tab rather than the public Marketplace. Async reply never arrives — Inspect the events emitted by onGoogleChatMessage. A missing sendGoogleChatMessage step usually means the service account JWT could not be signed (createGoogleChatJWT Custom Code error) or the Chat REST API rejected the outbound request. Replies arrive in a new thread instead of the original one — The Google Chat REST API was called with messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD; this is expected when the original chatEvent.threadName was not preserved (e.g. when the bot is added to a brand-new space).

​
External Resources

Google Chat API

Official Google Chat REST API reference.

In-app setup guide

Interactive setup guide hosted inside the connector workspace, with an endpoint URL builder for tenant administrators.