Skip to main content

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.

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.

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

​
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.
1

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

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

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

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

​
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.
1

Create a Google Cloud Chat app

In the Google Cloud Console, 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).
2

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

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

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. [email protected])
Click Connect — Noxus mints a token and calls the Chat API to verify everything is wired up.
5

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

​
Deployment Settings

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

​
Deployment

FieldDescription
StatusToggle the deployment Online or Offline. Going Online adds the bot to the configured space; going Offline removes it.
VersionThe published agent version this deployment uses.
A published version is required before you can set a deployment to Online. Switch to Offline to edit configuration.

​
Configuration

FieldDescription
Google Chat ConnectionThe Google Chat connection to use (OAuth user or service account). Manage connections in your workspace’s connections settings.
Custom InstructionsPer-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.
FieldDescription
Direct messages onlyWhen 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 keywordsOne or more keywords that must appear in the message (e.g. /start, help). Leave empty to respond to every message.
Keyword filtering only gates conversation creation. Once a conversation is active, follow-up messages don’t need to repeat the keyword.
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.

​
Reply Behavior

FieldDescription
Reply modeAuto — 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 replyingWhen 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.
ToolDescription
Send MessageSend messages to the Chat space.
React To MessageAdd Unicode emoji reactions to messages.
Reply In ThreadReply to messages in a thread.

​
Rate Limits

FieldDescription
Max messages per minuteLimit how many messages the agent sends per minute. 0 for unlimited.
Max new conversations per hourLimit 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

FieldDescription
Show thinkingDisplay the agent’s reasoning steps in Chat messages. Off by default.
Show tool callsDisplay tool call status in Chat messages. Off by default.
Show sourcesDisplay source citations in Chat messages. On by default.

​
Troubleshooting

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