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

# Google Chat

# Google Chat (Chat API)

**Delivery:** Official add-on.

Google Chat in Fased is an HTTP-only integration. The gateway verifies
Google-signed webhook requests, routes DMs and spaces into the normal session
model, and sends replies through the Chat API using your service account.

Status: supported for DMs and spaces through Google Chat webhooks.

Google Chat is an official optional add-on. Install it from **Agent >
Channels**, onboarding, or the CLI before entering credentials:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased plugins install @fased/googlechat
fased gateway restart
```

## Quick setup (beginner)

Only the Google Chat webhook path should be public. Keep the dashboard and the
rest of the gateway private behind Tailscale, your reverse proxy, or another
access boundary.

1. Create a Google Cloud project and enable the **Google Chat API**.
   * Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
   * Enable the API if it is not already enabled.
2. Create a **Service Account**:
   * Press **Create Credentials** > **Service Account**.
   * Name it whatever you want (e.g., `fased-chat`).
   * Leave permissions blank (press **Continue**).
   * Leave principals with access blank (press **Done**).
3. Create and download the **JSON Key**:
   * In the list of service accounts, click on the one you just created.
   * Go to the **Keys** tab.
   * Click **Add Key** > **Create new key**.
   * Select **JSON** and press **Create**.
4. Store the downloaded JSON file on your gateway host (e.g., `~/.fased/googlechat-service-account.json`).
5. Create a Google Chat app in the
   [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
   * Fill in the **Application info**:
     * **App name**: (e.g. `Fased`)
     * **Avatar URL**: (e.g. `https://example.com/logo.png`)
     * **Description**: (e.g. `Personal AI Assistant`)
   * Enable **Interactive features**.
   * Under **Functionality**, check **Join spaces and group conversations**.
   * Under **Connection settings**, select **HTTP endpoint URL**.
   * Under **Triggers**, select **Use a common HTTP endpoint URL for all
     triggers** and set it to your gateway's public URL followed by
     `/googlechat`.
     * *Tip: Run `fased status` to find your gateway's public URL.*
   * Under **Visibility**, check **Make this Chat app available to specific
     people and groups in \<Your Domain>**.
   * Enter your email address (e.g. `user@example.com`) in the text box.
   * Click **Save** at the bottom.
6. **Enable the app status**:
   * After saving, **refresh the page**.
   * Look for the **App status** section (usually near the top or bottom after saving).
   * Change the status to **Live - available to users**.
   * Click **Save** again.
7. Open **Agents**, select the Agent, then use **Agent > Channels > Google
   Chat** to configure the service account path + webhook audience:
   * Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
   * Or config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
8. Set the webhook audience type + value (matches your Chat app config).
9. Start or restart the gateway if the UI asks for it. Google Chat will POST to
   your webhook path.

## Add to Google Chat

Once the gateway is running and your email is added to the visibility list:

1. Go to [Google Chat](https://chat.google.com/).
2. Click the **+** (plus) icon next to **Direct Messages**.
3. In the search bar, type the **App name** you configured in Google Cloud.
   * Private apps do not appear in the public Marketplace browse list. Search
     for the app by name.
4. Select your bot from the results.
5. Click **Add** or **Chat** to start a 1:1 conversation.
6. Send "Hello" to trigger the assistant!

## Public URL (Webhook-only)

Google Chat webhooks require a public HTTPS endpoint. Expose only the
`/googlechat` path to the internet. Keep the Fased dashboard and other
sensitive endpoints on your private network.

### Option A: Tailscale Funnel (Recommended)

Use Tailscale Serve for the private dashboard and Funnel for the public webhook
path. This keeps `/` private while exposing only `/googlechat`.

1. **Check what address your gateway is bound to:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   ss -tlnp | grep 18789
   ```

   Note the IP address (e.g., `127.0.0.1`, `0.0.0.0`, or your Tailscale IP like `100.x.x.x`).

2. **Expose the dashboard to the tailnet only (port 8443):**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale serve --bg --https 8443 http://127.0.0.1:18789

   # If bound to Tailscale IP only (e.g., 100.106.161.80):
   tailscale serve --bg --https 8443 http://100.106.161.80:18789
   ```

3. **Expose only the webhook path publicly:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

   # If bound to Tailscale IP only (e.g., 100.106.161.80):
   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
   ```

4. **Authorize the node for Funnel access:**
   If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.

5. **Verify the configuration:**

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   tailscale serve status
   tailscale funnel status
   ```

Your public webhook URL will be:
`https://<node-name>.<tailnet>.ts.net/googlechat`

Your private dashboard stays tailnet-only:
`https://<node-name>.<tailnet>.ts.net:8443/`

Use the public URL (without `:8443`) in the Google Chat app config.

> Note: This configuration persists across reboots. To remove it later, run `tailscale funnel reset` and `tailscale serve reset`.

### Option B: Reverse Proxy (Caddy)

If you use a reverse proxy like Caddy, only proxy the specific path:

```caddy theme={"theme":{"light":"min-light","dark":"min-dark"}}
your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}
```

With this config, `your-domain.com/googlechat` is routed to Fased and the rest
of the domain stays outside the gateway route.

### Option C: Cloudflare Tunnel

Configure your tunnel's ingress rules to only route the webhook path:

* **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
* **Default Rule**: HTTP 404 (Not Found)

## How it works

1. Google Chat sends webhook POSTs to the gateway. Each request includes an
   `Authorization: Bearer <token>` header.
2. Fased verifies the token against the configured `audienceType` + `audience`:
   * `audienceType: "app-url"` → audience is your HTTPS webhook URL.
   * `audienceType: "project-number"` → audience is the Cloud project number.
3. Messages are routed by space:
   * DMs use session key `agent:<agentId>:googlechat:dm:<spaceId>`.
   * Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
4. DM access is pairing by default. Unknown senders receive a pairing code.
   Approve with:
   * `fased pairing approve googlechat <code>`
5. Group spaces require @-mention by default. Use `botUser` if mention detection needs the app’s user name.

## Targets

Use these identifiers for delivery and allowlists:

* Direct messages: `users/<userId>` (recommended).
* Raw email `name@example.com` is mutable. It is only used for direct allowlist
  matching when `channels.googlechat.dangerouslyAllowNameMatching: true`.
* Deprecated: `users/<email>` is treated as a user id, not an email allowlist.
* Spaces: `spaces/<spaceId>`.

## Config highlights

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}
```

Notes:

* Service account credentials can also be passed inline with `serviceAccount` (JSON string).
* `serviceAccountRef` is also supported as an env/file SecretRef, including
  per-account refs under
  `channels.googlechat.accounts.<id>.serviceAccountRef`.
* Default webhook path is `/googlechat` if `webhookPath` isn’t set.
* `dangerouslyAllowNameMatching` re-enables mutable email principal matching for
  allowlists. Treat it as compatibility mode.
* Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
* `typingIndicator` supports `none`, `message` (default), and `reaction`.
  Reaction typing requires user OAuth.
* Attachments are downloaded through the Chat API and stored in the media
  pipeline, capped by `mediaMaxMb`.

Secrets reference details: [Secrets Management](/gateway/secrets).

## Troubleshooting

### 405 Method Not Allowed

If Google Cloud Logs Explorer shows errors like:

```
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
```

This means the webhook handler isn't registered. Common causes:

1. **Channel not configured**: The `channels.googlechat` section is missing from your config. Verify with:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   fased config get channels.googlechat
   ```

   If it returns "Config path not found", add the configuration (see [Config highlights](#config-highlights)).

2. **Runtime not loaded**: Google Chat is a bundled channel extension. If
   **Agent > Channels** shows restart required after saving credentials,
   restart the gateway so the runtime registers the webhook handler.

3. **Gateway not restarted**: after adding config, restart the gateway:

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   fased gateway restart
   ```

Verify the channel is running:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
fased channels status
# Should show: Google Chat default: enabled, configured, ...
```

### Other issues

* Check `fased channels status --probe` for auth errors or missing audience config.
* If no messages arrive, confirm the Chat app's webhook URL and event
  subscriptions.
* If mention gating blocks replies, set `botUser` to the app's user resource
  name and verify `requireMention`.
* Use `fased logs --follow` while sending a test message to see if requests reach the gateway.

Related docs:

* [Gateway configuration](/gateway/configuration)
* [Security](/gateway/security)
* [Reactions](/tools/reactions)