Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

FieldDescription
📖 Setup guideRead-only field whose description links to the in-app setup guide page hosted by the connector workspace
Google Chat endpoint URLPaste this value in the Google Chat app’s HTTP endpoint URL field
Endpoint tokenEmbedded in the endpoint URL query string and validated on every incoming Google Chat request
Send replies asynchronouslyWhen true (default), the connector immediately returns the acknowledgement text to Google Chat and posts the final agent reply later via the Google Chat REST API. When false, the synchronous reply path waits for the agent answer before returning
Acknowledgement textImmediate message returned to Google Chat in async mode (default I am working on it.)
Added to space textText returned when the bot is added to a space (ADDED_TO_SPACE event)
Empty message textText returned when no user text can be extracted from the incoming event
Error textFallback message sent to users when the agent call fails
Google Chat API base URLDefault https://chat.googleapis.com/v1
Google Chat OAuth scopeOAuth scope used when minting the access token. Default https://www.googleapis.com/auth/chat.bot
Google service account JSONAuto-wired by onInstall to {{config.googleChatServiceAccount}}. The actual JSON value lives in the workspace secret googleChatServiceAccount
AI Knowledge API keyAuto-wired by onInstall to {{config.googleChatAgentApiKey}}. The actual key lives in the workspace secret googleChatAgentApiKey
AI Knowledge project IDIdentifier of the AI Knowledge project the bot should query
Optional model overrideOptional chat-completion model override
Max Google Chat history turnsNumber of user / assistant turns kept per Google Chat thread (default 12)
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

SymptomCauseResolution
Unauthorized Google Chat request. returned to GoogleThe query-string token does not match the configured endpointTokenRe-copy the auto-populated googleChatEndpointUrl from the app instance into the Google Chat app HTTP endpoint URL field
I could not get an answer from the Prisme.ai agent. posted in chatThe AI Knowledge call failed (invalid project ID, missing API key, quota exceeded, agent returned an empty response)Check the workspace events for GoogleChat.reply.failed and the underlying AgentRequestFailed / EmptyAgentResponse payload
Missing client_email or private_key in service account. in eventsThe googleChatServiceAccount secret is empty or malformedRe-paste the full service account JSON in the workspace secret (must include client_email, private_key, private_key_id)
Google Chat HTTP 401 on outbound replyThe minted access token was rejected by the Chat REST API (service account misconfigured or scope mismatch)Verify the service account belongs to the same Google Cloud project as the Chat app and that the scope is https://www.googleapis.com/auth/chat.bot
Send-as the bot to space step in Google Cloud rejects the endpointThe endpoint URL is not HTTPS, missing the ?token=… query string or unreachableRe-check the URL is exactly the value of googleChatEndpointUrl from the installed app instance

​
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.