Google Chat (Chat API)

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. Go to: Google Chat API Credentials
3. Enable the API if it is not already enabled.
4. Create a Service Account:
   • Press Create Credentials > Service Account.
   • Name it whatever you want (e.g., openclaw-chat).
   • Leave permissions blank (press Continue).
   • Leave principals with access blank (press Done).
5. Press Create Credentials > Service Account.
6. Name it whatever you want (e.g., openclaw-chat).
7. Leave permissions blank (press Continue).
8. Leave principals with access blank (press Done).
9. 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.
10. In the list of service accounts, click on the one you just created.
11. Go to the Keys tab.
12. Click Add Key > Create new key.
13. Select JSON and press Create.
14. Store the downloaded JSON file on your gateway host (e.g., ~/.openclaw/googlechat-service-account.json).
15. Create a Google Chat app in the Google Cloud Console Chat Configuration:
    • Fill in the Application info:
      • App name: (e.g. OpenClaw)
      • Avatar URL: (e.g. https://openclaw.ai/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 openclaw 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.
16. Fill in the Application info:
    • App name: (e.g. OpenClaw)
    • Avatar URL: (e.g. https://openclaw.ai/logo.png)
    • Description: (e.g. Personal AI Assistant)
17. App name: (e.g. OpenClaw)
18. Avatar URL: (e.g. https://openclaw.ai/logo.png)
19. Description: (e.g. Personal AI Assistant)
20. Enable Interactive features.
21. Under Functionality, check Join spaces and group conversations.
22. Under Connection settings, select HTTP endpoint URL.
23. 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 openclaw status to find your gateway’s public URL.
24. Tip: Run openclaw status to find your gateway’s public URL.
25. Under Visibility, check Make this Chat app available to specific people and groups in <Your Domain>.
26. Enter your email address (e.g. user@example.com) in the text box.
27. Click Save at the bottom.
28. 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.
29. After saving, refresh the page.
30. Look for the App status section (usually near the top or bottom after saving).
31. Change the status to Live - available to users.
32. Click Save again.
33. Configure OpenClaw with 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".
34. Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
35. Or config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
36. Set the webhook audience type + value (matches your Chat app config).
37. Start the gateway. Google Chat will POST to your webhook path.

• Go to: Google Chat API Credentials
• Enable the API if it is not already enabled.

• Press Create Credentials > Service Account.
• Name it whatever you want (e.g., openclaw-chat).
• Leave permissions blank (press Continue).
• Leave principals with access blank (press Done).

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

• Fill in the Application info:
  • App name: (e.g. OpenClaw)
  • Avatar URL: (e.g. https://openclaw.ai/logo.png)
  • Description: (e.g. Personal AI Assistant)
• App name: (e.g. OpenClaw)
• Avatar URL: (e.g. https://openclaw.ai/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 openclaw status to find your gateway’s public URL.
• Tip: Run openclaw 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.

• App name: (e.g. OpenClaw)
• Avatar URL: (e.g. https://openclaw.ai/logo.png)
• Description: (e.g. Personal AI Assistant)

• Tip: Run openclaw status to find your gateway’s public URL.

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

• Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
• Or config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".

Add to Google Chat

1. Go to Google Chat.
2. Click the + (plus) icon next to Direct Messages.
3. In the search bar (where you usually add people), type the App name you configured in the Google Cloud Console.
   • Note: The bot will not appear in the “Marketplace” browse list because it is a private app. You must search for it by name.
4. Note: The bot will not appear in the “Marketplace” browse list because it is a private app. You must search for it by name.
5. Select your bot from the results.
6. Click Add or Chat to start a 1:1 conversation.
7. Send “Hello” to trigger the assistant!

• Note: The bot will not appear in the “Marketplace” browse list because it is a private app. You must search for it by name.

Public URL (Webhook-only)

Option A: Tailscale Funnel (Recommended)

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

   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):
   Copy

   # 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:
   Copy

   # 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:
   Copy

   tailscale serve status
   tailscale funnel status
   

ss -tlnp | grep 18789

# 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

# 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

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. OpenClaw 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. audienceType: "app-url" → audience is your HTTPS webhook URL.
4. audienceType: "project-number" → audience is the Cloud project number.
5. Messages are routed by space:
   • DMs use session key agent:<agentId>:googlechat:dm:<spaceId>.
   • Spaces use session key agent:<agentId>:googlechat:group:<spaceId>.
6. DMs use session key agent:<agentId>:googlechat:dm:<spaceId>.
7. Spaces use session key agent:<agentId>:googlechat:group:<spaceId>.
8. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
   • openclaw pairing approve googlechat <code>
9. openclaw pairing approve googlechat <code>
10. Group spaces require @-mention by default. Use botUser if mention detection needs the app’s user name.

• audienceType: "app-url" → audience is your HTTPS webhook URL.
• audienceType: "project-number" → audience is the Cloud project number.

• DMs use session key agent:<agentId>:googlechat:dm:<spaceId>.
• Spaces use session key agent:<agentId>:googlechat:group:<spaceId>.

• openclaw pairing approve googlechat <code>

Targets

• Direct messages: users/<userId> or users/<email> (email addresses are accepted).
• Spaces: spaces/<spaceId>.

Config highlights

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890", "name@example.com"],
      },
      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).
• Default webhook path is /googlechat if webhookPath isn’t set.
• Reactions are available via the reactions tool and channels action when actions.reactions is enabled.
• typingIndicator supports none, message (default), and reaction (reaction requires user OAuth).
• Attachments are downloaded through the Chat API and stored in the media pipeline (size 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:
   Copy

   openclaw config get channels.googlechat
   
   If it returns “Config path not found”, add the configuration (see Config highlights).
2. Plugin not enabled: Check plugin status:
   Copy

   openclaw plugins list | grep googlechat
   
   If it shows “disabled”, add plugins.entries.googlechat.enabled: true to your config.
3. Gateway not restarted: After adding config, restart the gateway:
   Copy

   openclaw gateway restart
   

openclaw config get channels.googlechat

openclaw plugins list | grep googlechat

openclaw gateway restart

openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

Other issues

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

• Gateway configuration
• Security
• Reactions