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.

​
Choosing an event delivery mode

Google Chat can deliver events to Noxus in two ways. Pick one before you configure the deployment.
ModeWhen 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/SubYour 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.
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.

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

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

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

Grant "Pub/Sub Publisher" 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.
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
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.
3

Grant "Pub/Sub Subscriber" 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.
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.
4

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

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.
Two IAM grants, two different principals, two different resources — these are the most common point of confusion:
DirectionPrincipalResourceRole
Google Chat → topicservice-<PROJECT_NUMBER>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com (Google’s Chat-side service agent, shown in Chat API → Configuration)The Pub/Sub topicroles/pubsub.publisher
Subscription → NoxusYour own service account (the one in the JSON key uploaded to Noxus)The Pub/Sub subscriptionroles/pubsub.subscriber
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.

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