​

Google Chat (Chat API)

fased plugins install @fased/googlechat
fased gateway restart

​

Quick setup (beginner)

1. Create a Google Cloud project and enable the Google Chat API.
   • Go to: Google Chat API 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:
   • 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. [email protected]) 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

1. Go to Google Chat.
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)

​

Option A: Tailscale Funnel (Recommended)

1. Check what address your gateway is bound to:
   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):
   # 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:
   # 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:
   tailscale serve status
   tailscale funnel status
   

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

​

Option B: Reverse Proxy (Caddy)

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

​

Option C: Cloudflare Tunnel

• 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

• Direct messages: users/<userId> (recommended).
• Raw email [email protected] 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

{
  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,
    },
  },
}

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

​

Troubleshooting

​

405 Method Not Allowed

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

1. Channel not configured: The channels.googlechat section is missing from your config. Verify with:
   fased config get channels.googlechat
   
   If it returns “Config path not found”, add the configuration (see 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:
   fased gateway restart
   

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.

• Gateway configuration
• Security
• Reactions