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

# Google Chat

> Deploy your agent to Google Chat spaces and direct messages

Deploy your agent to Google Chat and let users interact with it directly from any space, group chat, or 1:1 direct message. Once activated, Noxus invites the bot to the configured space and routes incoming messages to your agent.

## Choosing an event delivery mode

Google Chat can deliver events to Noxus in two ways. Pick one **before** you configure the deployment.

| Mode                          | When to use it                                                                                                                                                                                              |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTPS webhook** *(default)* | Your Noxus relay has a public URL Google Chat can POST to. Simpler to set up, no Google Cloud IAM work.                                                                                                     |
| **Cloud Pub/Sub**             | Your Noxus relay can't expose a public endpoint (on-prem, locked-down VPC, firewalled deployment). The customer's Google Cloud project owns the topic; Noxus pulls events with service-account credentials. |

The choice is exposed as the **Event delivery** dropdown in the deployment's **Conversation triggers** section. Switching modes requires deactivating and reactivating the deployment.

## Setting Up the Google Chat Deployment

There are two ways to authenticate the bot: as a **workspace user** via OAuth (the Noxus-managed Google account flow) or as an **app-style bot** via a Google Cloud **service account**. Pick the option that matches how you want the bot to appear in Chat.

<Note>
  **Cloud Pub/Sub delivery requires the service-account path (Option B).** OAuth user tokens don't pair with Pub/Sub IAM and Noxus will reject activation. If you need Pub/Sub delivery, use a service account.
</Note>

### Option A: Connect with a Google Workspace user (OAuth)

The simplest path. The bot acts on behalf of the connected user — messages it sends are attributed to that user and it can only post in spaces the user has access to.

<Steps>
  <Step title="Create a Google Chat connection">
    In Noxus, open **Settings → Integrations**, find **Google Chat**, and click **Connect**.

    Choose **Google Chat (Workspace user)** as the provider and complete the Google sign-in. Grant the requested Chat scopes: read messages, send messages, react, and manage memberships.
  </Step>

  <Step title="Create a Google Chat deployment">
    Navigate to your agent's **Deployments** page and create a new Google Chat deployment. Pick the connection you just authorised.
  </Step>

  <Step title="Enter the space resource name">
    Open the target Chat space in your browser. The URL contains the space ID — copy the resource name in the form `spaces/AAAAxxxxxxx`.

    Paste it into **Space resource name** in the deployment configuration.
  </Step>

  <Step title="Activate the deployment">
    Set the deployment **Online**. Noxus calls the Chat API to add the bot to the space. The bot is now ready to receive messages.
  </Step>
</Steps>

<Tip>
  The bot only sees messages in spaces it's been invited to. If activation fails with a permissions error, make sure the connected user has at least the Chat **Member** role in the target space.
</Tip>

### Option B: Connect with a service account (app-style bot)

Use this option when you want a dedicated bot identity (separate from any human user) — the recommended path for production deployments and required for **domain-wide delegation**.

<Steps>
  <Step title="Create a Google Cloud Chat app">
    In the [Google Cloud Console](https://console.cloud.google.com), enable the **Google Chat API** for your project. Open **Chat API → Configuration** and configure your Chat app — give it a name, avatar, and description. Note the **Project number** (not the project ID).
  </Step>

  <Step title="Set the HTTPS connection settings">
    Still in **Chat API → Configuration**, under **Connection settings**, choose **HTTP endpoint URL** and paste the webhook URL shown in the deployment configuration:

    ```
    https://relay.your-noxus-domain.com/webhooks/<group_id>
    ```

    The exact URL is shown in the **Webhook URL** banner on the deployment screen — copy that one.
  </Step>

  <Step title="Create a service account key">
    In Google Cloud Console, open **IAM & Admin → Service Accounts**. Create a new service account (or pick an existing one) and grant it the Chat scopes:

    * `https://www.googleapis.com/auth/chat.bot`
    * `https://www.googleapis.com/auth/chat.messages`
    * `https://www.googleapis.com/auth/chat.messages.reactions`
    * `https://www.googleapis.com/auth/chat.spaces`
    * `https://www.googleapis.com/auth/chat.memberships`

    Then click **Keys → Add Key → Create new key → JSON** to download a JSON key file.
  </Step>

  <Step title="Enter credentials in Noxus">
    In Noxus, open the Google Chat connection dialog and choose **API Credentials**:

    * **Service account JSON** — paste the entire contents of the JSON key file
    * **Impersonation subject** *(optional)* — only set this if you've configured **domain-wide delegation** in Google Workspace and want the bot to act on behalf of a specific user (e.g. `bot-runner@yourdomain.com`)

    Click **Connect** — Noxus mints a token and calls the Chat API to verify everything is wired up.
  </Step>

  <Step title="Add the bot to a space and activate">
    Open the target Chat space and copy its resource name (`spaces/AAAAxxxxxxx`). Paste it into **Space resource name** on the deployment, then set the deployment **Online**. Noxus invites the bot to the space automatically.
  </Step>
</Steps>

<Warning>
  The same webhook URL handles every Google Chat deployment in your workspace. Noxus verifies every inbound event's JWT against this exact URL (the audience Google signs into the token), so make sure the URL pasted into Cloud Console matches the **Webhook URL** banner exactly — including scheme and any path prefix.
</Warning>

### Option C: Cloud Pub/Sub delivery

Use this when the Noxus relay can't accept inbound HTTPS — for example, on-prem deployments or VPC-locked environments. Instead of Chat POSTing events to a URL, Chat publishes them to a **Cloud Pub/Sub topic** in your Google Cloud project. Noxus pulls from a subscription on that topic with service-account credentials.

This mode reuses the **service-account** Chat connection from Option B above (Pub/Sub delivery is not compatible with OAuth-user credentials).

<Steps>
  <Step title="Create the Pub/Sub topic and subscription">
    In Google Cloud Console, open **Pub/Sub → Topics** in the **same project that owns the Chat app**. Create a topic — for example, `chat`. The full topic name will be `projects/YOUR_PROJECT/topics/chat`.

    Create a **pull** subscription on that topic — for example, `chat-sub`, with name `projects/YOUR_PROJECT/subscriptions/chat-sub`. Defaults are fine; no push endpoint is needed.
  </Step>

  <Step title="Grant &#x22;Pub/Sub Publisher&#x22; to the Google Chat service agent on the topic">
    Google Chat publishes events from a Google-managed service agent. The agent's email is shown on the **Chat API → Configuration** page under **Service Account Email**, in the form:

    ```
    service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com
    ```

    On the **topic** (not the subscription), grant this email the **`roles/pubsub.publisher`** role.

    ```bash theme={null}
    gcloud pubsub topics add-iam-policy-binding chat \
      --project=YOUR_PROJECT \
      --member=serviceAccount:service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com \
      --role=roles/pubsub.publisher
    ```

    <Warning>
      Without this grant **Google Chat silently drops every event** — the Chat API UI shows no error, but no message ever reaches the subscription. Verify by pulling the subscription directly (`gcloud pubsub subscriptions pull projects/YOUR_PROJECT/subscriptions/chat-sub --auto-ack`) after sending a test message; if it's empty, the publisher role is missing.
    </Warning>
  </Step>

  <Step title="Grant &#x22;Pub/Sub Subscriber&#x22; to your Noxus service account on the subscription">
    The same service account JSON you uploaded to Noxus (Option B, step 3) is what Noxus uses to pull from the subscription. On the **subscription** (not the topic), grant that SA the **`roles/pubsub.subscriber`** role.

    ```bash theme={null}
    gcloud pubsub subscriptions add-iam-policy-binding chat-sub \
      --project=YOUR_PROJECT \
      --member=serviceAccount:<your-noxus-sa>@<your-project>.iam.gserviceaccount.com \
      --role=roles/pubsub.subscriber
    ```

    Without this grant, Noxus's pre-flight check fails at activation with a precise error message telling you which SA and which subscription need the role.
  </Step>

  <Step title="Configure the Chat app to publish to the topic">
    In **Chat API → Configuration → Connection settings**, choose **Cloud Pub/Sub** and paste the topic name (e.g. `projects/YOUR_PROJECT/topics/chat`). Save.
  </Step>

  <Step title="Configure the Noxus deployment">
    On the agent's Google Chat deployment in Noxus, set **Event delivery** to **Cloud Pub/Sub** and paste the subscription name (`projects/YOUR_PROJECT/subscriptions/chat-sub`) into the **Pub/Sub subscription** field.

    Set the deployment **Online**. Noxus runs a one-shot Pub/Sub pull as part of activation to confirm the subscriber role is in place — if either IAM grant is missing, activation fails with an actionable error before the deployment goes live.
  </Step>
</Steps>

<Note>
  **Two IAM grants, two different principals, two different resources** — these are the most common point of confusion:

  | Direction            | Principal                                                                                                                                        | Resource                     | Role                      |
  | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- | :------------------------ |
  | Google Chat → topic  | `service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com` (Google's Chat-side service agent, shown in **Chat API → Configuration**) | The Pub/Sub **topic**        | `roles/pubsub.publisher`  |
  | Subscription → Noxus | Your own service account (the one in the JSON key uploaded to Noxus)                                                                             | The Pub/Sub **subscription** | `roles/pubsub.subscriber` |
</Note>

<Tip>
  Pub/Sub deployments listen on **every space the Chat app is added to**, not just one. The **Space resource name** and **Direct messages only** fields become content filters in this mode — leave them blank and the bot responds in any space it's invited to. Set them only if you want to ignore events from other spaces.
</Tip>

## Deployment Settings

Once your Google Chat connection is established, configure how the agent behaves. Settings are organised into the sections below.

### Deployment

| Field       | Description                                                                                                                   |
| :---------- | :---------------------------------------------------------------------------------------------------------------------------- |
| **Status**  | Toggle the deployment **Online** or **Offline**. Going Online adds the bot to the configured space; going Offline removes it. |
| **Version** | The published agent version this deployment uses.                                                                             |

<Note>
  A published **version** is required before you can set a deployment to Online. Switch to **Offline** to edit configuration.
</Note>

### Configuration

| Field                      | Description                                                                                                                     |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| **Google Chat Connection** | The Google Chat connection to use (OAuth user or service account). Manage connections in your workspace's connections settings. |
| **Custom Instructions**    | Per-deployment instructions appended to the agent's system prompt (e.g. `"Always respond in Spanish"`).                         |

### Conversation Triggers

A new conversation starts when a user posts in the configured space. You can optionally restrict to direct messages or filter by keyword.

| Field                    | Description                                                                                                                                                                                                                                                                                                                                                            |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Direct messages only** | When enabled, the bot listens to **every** direct message it receives in this workspace and ignores events from rooms or group chats. Turning this on hides the space resource name field — DM spaces are created on demand by Google Chat the first time a user messages the bot, so there's no single space to pin. Useful for personal-assistant style deployments. |
| **Space resource name**  | *(Hidden when "Direct messages only" is on.)* The Chat space resource name (e.g. `spaces/AAAAxxxxxxx`). The bot is added to this space on activation.                                                                                                                                                                                                                  |
| **Trigger keywords**     | One or more keywords that must appear in the message (e.g. `/start`, `help`). Leave empty to respond to every message.                                                                                                                                                                                                                                                 |

<Note>
  Keyword filtering only gates **conversation creation**. Once a conversation is active, follow-up messages don't need to repeat the keyword.
</Note>

<Warning>
  Only one **Direct messages only** deployment should exist per workspace at a time. Multiple DM-only deployments in the same workspace will all fire on every incoming DM, which is rarely what you want.
</Warning>

### Reply Behavior

| Field                              | Description                                                                                                                                      |
| :--------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reply mode**                     | `Auto` — reply in the same context. `Thread` — always reply in a thread. `Tool-based` — agent decides when and where to send messages via tools. |
| **Batch messages before replying** | When enabled, the agent waits for a pause before responding, batching multiple incoming messages together.                                       |
| **Quiet period (seconds)**         | How long to wait after the last message before replying. New messages reset the timer. Default: `5`.                                             |

### Channel Tools

Toggle which Google Chat-specific tools the agent can use during conversations.

| Tool                 | Description                              |
| :------------------- | :--------------------------------------- |
| **Send Message**     | Send messages to the Chat space.         |
| **React To Message** | Add Unicode emoji reactions to messages. |
| **Reply In Thread**  | Reply to messages in a thread.           |

### Rate Limits

| Field                              | Description                                                                                              |
| :--------------------------------- | :------------------------------------------------------------------------------------------------------- |
| **Max messages per minute**        | Limit how many messages the agent sends per minute. `0` for unlimited.                                   |
| **Max new conversations per hour** | Limit how many new conversations can be started per hour. `0` for unlimited.                             |
| **Conversation timeout (minutes)** | After this many minutes of inactivity, the next message starts a fresh conversation. `0` for no timeout. |

### Display

| Field               | Description                                                           |
| :------------------ | :-------------------------------------------------------------------- |
| **Show thinking**   | Display the agent's reasoning steps in Chat messages. Off by default. |
| **Show tool calls** | Display tool call status in Chat messages. Off by default.            |
| **Show sources**    | Display source citations in Chat messages. On by default.             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Activation fails with 'cannot add the bot to the space'">
    The connected credential lacks the `chat.memberships` scope. For OAuth, reconnect and grant the **Manage memberships** permission. For a service account, add the `https://www.googleapis.com/auth/chat.memberships` scope to the SA and either re-grant domain-wide delegation or invite the bot to the space manually.
  </Accordion>

  <Accordion title="No events arrive at the deployment">
    Two things to check:

    1. The URL pasted into Cloud Console (**Chat API → Configuration → Connection settings → HTTP endpoint URL**) matches the **Webhook URL** banner on the deployment **exactly** — same scheme, host, and path. Google signs the JWT with that URL as the audience, and Noxus verifies the audience against `RELAY_URL + /webhooks/<group_id>`. A mismatch logs `[GCHAT] JWT rejected (expected_aud=...)` in the relay and returns 401.
    2. The bot is **invited to the space**. For service-account auth this happens automatically at activation. For OAuth-user auth, the user must be a member of the target space.
  </Accordion>

  <Accordion title="The bot's reply shows in conversation history but never appears in Chat">
    Almost always a missing scope on the connection. The conversation runs successfully on the Noxus side, but `chat.googleapis.com/v1/{space}/messages` returns `403`. Add the `chat.messages` scope (OAuth) or grant the corresponding scope to the service account, then reconnect.
  </Accordion>

  <Accordion title="The bot replies in spaces but ignores direct messages (or vice versa)">
    Check the **Direct messages only** toggle in **Conversation Triggers**. When enabled the bot drops every event whose space type isn't `DIRECT_MESSAGE`. Disable it to respond in spaces and rooms as well.
  </Accordion>

  <Accordion title="Pub/Sub mode: activation fails with a permissions / IAM error">
    Pub/Sub-mode activation runs a one-shot pull against the configured subscription to surface IAM problems before the deployment goes live. Two common cases:

    * **`PermissionDenied … pubsub.subscriptions.consume`** — the service account whose JSON key you uploaded to Noxus is missing **`roles/pubsub.subscriber`** on the subscription. Grant the role on the **subscription** (not the topic). The error message includes the exact SA email and subscription path to grant against.
    * **`NotFound … subscription`** — the subscription resource name is wrong, or it exists in a different Google Cloud project than the one in the path. Double-check the project ID and subscription name.
  </Accordion>

  <Accordion title="Pub/Sub mode: deployment is online but no events arrive">
    If activation succeeded but the bot never responds, Chat is failing to publish events. The Chat API UI gives no feedback when this happens — events are dropped silently. Confirm in this order:

    1. **Publisher role.** On the topic, grant `roles/pubsub.publisher` to the Google-side Chat service agent (`service-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com`, shown in **Chat API → Configuration → Service Account Email**). This is the most common cause.
    2. **Verify the pipe with `gcloud`.** Pull the subscription directly while sending a test message:
       ```bash theme={null}
       gcloud pubsub subscriptions pull projects/YOUR_PROJECT/subscriptions/chat-sub \
         --project=YOUR_PROJECT --limit=5 --auto-ack
       ```
       If the pull returns no messages, Chat is the problem (recheck the publisher role and the topic name in **Chat API → Configuration**). If the pull returns messages but Noxus isn't reacting, check the deployment's **Events** tab — runtime failures (e.g. a revoked subscriber role) surface there with the exact exception class and message.
    3. **Bot membership.** Pub/Sub mode receives events for every space the Chat app is in — but Chat only generates events for spaces where the bot has been invited or for DMs that users have initiated. Start a DM with the bot (or `@mention` it in a space) so Chat has something to publish.
  </Accordion>
</AccordionGroup>