> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abundly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Chat

> Connect your agent to Google Chat as its own named app, in a simple or advanced mode

Your agent can communicate with you and your team through Google Chat, appearing as its own named app. People **@mention** it in a space, or **direct-message** it, and the agent replies using its full context, capabilities, and history — just like in the portal.

Each Google Chat–enabled agent has its own Google Chat app, configured in your Google Cloud project.

<Note>
  **Abundly uses the classic HTTP Chat app, not the Google Workspace add-on.** When you configure the Chat API, you point it at Abundly's HTTP endpoint — you do **not** build it as a Workspace add-on (the "gsuiteaddons" model). The add-on model makes threaded replies harder and pulls in Marketplace publishing; the classic HTTP app sidesteps both. The steps below set up the classic app.
</Note>

## Example use cases

* "@Researcher summarise everything we know about Acme Corp" — kicks off a research agent from a space
* "@Releaser time to cut a new release" — triggers your deployment agent directly in a space
* A direct message to your assistant agent for a quick, private back-and-forth

## Modes

Google Chat has two reply modes, selectable on the capability card under **Settings → Capabilities → Google Chat**. Pick based on how much setup you want and what behaviour you need.

|                                        | **Direct reply** (simple)                            | **API** (advanced)                                |
| -------------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
| Setup                                  | HTTP endpoint only                                   | + service account key                             |
| How replies are sent                   | returned in the webhook response                     | posted via the Chat REST API                      |
| Response time                          | bounded by Google's \~30s webhook timeout            | no limit — handles long, tool-using turns         |
| Threading                              | a top-level @mention's reply starts a **new thread** | reply lands **in the @mention's thread**          |
| Agent tools (post to other spaces/DMs) | —                                                    | ✅ post / reply / direct-message tools             |
| Best for                               | quick conversational replies, easy to get going      | tool-heavy or long-running agents, tidy threading |

<Tip>
  Start with **Direct reply** to get going fast. Switch to **API** when you want threaded replies, long-running turns, or the agent to post into *other* spaces.
</Tip>

### Which Google API each mode uses

* **Direct reply (sync)** — your endpoint returns a Google Chat `Message` in the HTTP response and Google posts it for you. No outbound API call, no credentials.
* **API (async)** — the agent posts via the Chat REST API (`spaces.messages.create`, `chat.bot` scope) using a service account, with `messageReplyOption` so the reply threads correctly.
* **Not used: the Workspace add-ons API** (`hostAppDataAction` / `gsuiteaddons`). Abundly deliberately runs as a classic HTTP app, so neither mode uses the add-on response format.

## Prerequisites

* A Google Cloud project **in the organization tied to your Google Workspace** (see the warning below)
* Permission to enable APIs and create service accounts in that project
* A Google Workspace account you use for Google Chat
* The Abundly agent you want to connect

<Warning>
  **The project's org must match your Workspace.** A Chat app can only post into spaces in the Workspace whose organization owns its Cloud project. A GCP organization's *display name* is not a reliable guide — match the **Directory Customer ID** instead: get your Workspace **Customer ID** from the Google Admin console (**Account → Account settings**), then run `gcloud organizations list` and pick the org whose `DIRECTORY_CUSTOMER_ID` matches. Build the Chat app in a project under **that** org. If the project is under the wrong org, posting fails with `403 "This Chat app is not a member of this space"`.
</Warning>

## How to connect

<Steps>
  <Step title="Enable the Google Chat API">
    1. In the [Google Cloud Console](https://console.cloud.google.com), select (or create) a project **under the org tied to your Workspace** (see the warning above).
    2. Enable the **Google Chat API** for that project.
  </Step>

  <Step title="Configure the Chat app (classic HTTP)">
    Open **Google Chat API → Configuration** and fill in:

    1. **Application info** — app name (e.g. your agent's name), avatar URL, description.
    2. **Interactive features** — enabled.
    3. **Connection settings** — choose **HTTP endpoint URL** (not Apps Script, Dialogflow, or Pub/Sub) and paste the messaging endpoint Abundly shows you:
       ```
       https://your-domain/api/google-chat/bot/YOUR-AGENT-ID
       ```
       If a "Use a common HTTP endpoint URL for all triggers" toggle is shown, enable it.
    4. **Authentication Audience** — set this to **App URL**. Nothing else to configure: Abundly verifies each request against the endpoint URL it gave you.

           <Note>
             Abundly verifies every request's signed audience claim against the endpoint URL and rejects mismatches — there's no fallback to "signature only". **App URL is the only supported mode**, so leave the Authentication Audience on **App URL** (not *App project number*).
           </Note>
    5. **Visibility** — add yourself (and anyone else who should use it). Set the app status to **Live**.

    <Note>
      Do **not** enable the Google Workspace Marketplace SDK or publish this as a Workspace add-on. Abundly is a classic HTTP Chat app.
    </Note>
  </Step>

  <Step title="(API mode only) Create a service account key">
    Direct-reply mode needs nothing here — skip to the next step. For **API (async)** mode, the agent posts via the Chat REST API and needs a service account:

    1. In the **same project**, go to **IAM & Admin → Service Accounts → Create service account** (no project roles required).
    2. Open it → **Keys → Add key → Create new key → JSON** and download the file.
    3. In Abundly, create a **secret** of type **Google Chat** and paste the entire JSON key into it.

    <Note>
      The service account must live in the **same project** as the Chat app — that's how `chat.bot` authentication maps the call to your app. No Marketplace publish or scope approval is needed for `chat.bot`.
    </Note>
  </Step>

  <Step title="Enable the capability in Abundly">
    In your agent's **Settings → Capabilities**, enable **Google Chat**, then on the capability card:

    1. Choose the **reply mode** — Direct reply or API.
    2. **API mode:** select the **service account key** secret you created.
    3. The **messaging endpoint URL** shown here is the one you pasted into the Chat API Configuration.
  </Step>

  <Step title="Add the app and talk to it">
    1. In Google Chat, **@mention** the app in a space, or open a **direct message** with it.
    2. In a space, the first @mention adds the app and gets a reply.

    <Check>
      The agent replies. In a DM, keep chatting — every message reaches it. In a space, @mention it each turn (see below).
    </Check>
  </Step>
</Steps>

## How conversations work

Every Google Chat conversation maps to a persistent Abundly chat, with the same instructions, memory, and capabilities the agent has in the portal. These chats appear in the sidebar alongside portal chats and are marked as "remote".

* **Direct messages (1:1 with the app)** — every message reaches the agent, no @mention needed. A free-flowing conversation.
* **Spaces (rooms)** — Google only delivers messages to an HTTP app when it's **@mentioned**, so you @mention the agent on each turn. Each space maps to its own Abundly chat.
* **Threading** — in **API mode** the reply lands in your message's thread (tidy, contiguous). In **Direct-reply mode** a top-level @mention's reply starts a new thread, because Google ignores threading on synchronous responses.
* **Group chats** — Google Chat apps can't be added to multi-person group chats; only DMs and spaces are supported.

<Tip>
  Google Chat–originated chats are read-only in the portal — reply from Google Chat to keep the thread in the agent's working context.
</Tip>

## Agent tools (API mode)

In **API mode**, the agent gets tools to post into *other* Google Chat conversations (its reply to the current conversation is always delivered automatically — these are for reaching elsewhere):

| Tool                              | Purpose                                                              |
| --------------------------------- | -------------------------------------------------------------------- |
| `post_google_chat_message`        | Post a new message to a space (room or DM space), by `spaces/...` id |
| `reply_to_google_chat_message`    | Reply inside an existing thread, by `spaces/.../threads/...`         |
| `send_google_chat_direct_message` | DM a user by `users/...` id (resolves the existing DM space)         |

All use the `chat.bot` scope — no Marketplace or admin approval. They're available only in API mode (Direct-reply mode stays minimal). A DM is just a space, so `post_google_chat_message` with a DM space id reaches a person too; the direct-message tool is the convenience for when you have a user id but not their DM space id.

## Things to know

<Note>
  **One app per agent** — each agent uses its own Google Chat app and (for API mode) its own service account.
</Note>

<Warning>
  **Direct-reply mode has a \~30-second ceiling.** Google times out the webhook, so a long or heavily tool-using turn won't post a reply in Direct-reply mode. Use **API mode** for those.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 &#x22;This Chat app is not a member of this space&#x22; (API mode)">
    The app isn't a recognized member of the space. Almost always the project is under the **wrong organization** — it must be the org tied to your Workspace (match the Directory Customer ID; see the prerequisites warning). Also confirm the **service account is in the same project** as the Chat app, and that the app has been added to the space.
  </Accordion>

  <Accordion title="403 &#x22;Method doesn’t allow unregistered callers&#x22; / &#x22;use API Key&#x22;">
    The agent made a raw, unauthenticated HTTP call instead of using the dedicated Google Chat tool. Ensure you're in **API mode** with a service account key set (which loads the `post_google_chat_message` / `reply_to_google_chat_message` tools), and restart the service so the tools are loaded.
  </Accordion>

  <Accordion title="Chat briefly shows &#x22;app not responding&#x22;, then a reply appears">
    Expected behaviour pattern when something's off in API mode — the ack and the async post are out of sync. If you see it persistently, confirm you're on the latest build (the async acknowledgement returns an empty response).
  </Accordion>

  <Accordion title="No reply in a space, but DMs work">
    In spaces, Google only forwards **@mentions** to the app. Make sure you @mention it. Unmentioned follow-ups in a space thread are not delivered to a Google Chat HTTP app (unlike Microsoft Teams, which has Resource-Specific Consent for this).
  </Accordion>

  <Accordion title="Replies don't land in the thread">
    Direct-reply (sync) mode cannot thread a top-level @mention's reply — Google ignores the thread on synchronous responses. Switch to **API mode** for threaded replies.
  </Accordion>

  <Accordion title="Auth errors in the logs (token / signature)">
    With the **App URL** audience, Google sends a standard Google-issued OpenID Connect token (`iss: accounts.google.com`). Abundly verifies its signature against Google's public keys, checks the `aud` claim equals your endpoint URL, and confirms the token's `email` is `chat@system.gserviceaccount.com` (which proves the caller is Google Chat) — rejecting any mismatch.

    Two things to check: the **Authentication Audience** in the Chat API Configuration must be **App URL** (not *App project number* — Abundly only supports App URL), and the **endpoint URL you pasted must exactly match** the one Abundly gave you. If you see audience mismatches, re-copy the messaging endpoint URL and confirm the audience is set to App URL.
  </Accordion>
</AccordionGroup>