Google Chat - Idun Engine

Connect your Idun agent to Google Chat so users can interact with it by @mentioning the bot in spaces and direct messages.

Prerequisites

A running Idun agent (engine)
A Google Workspace account with access to Google Chat
A Google Cloud project (free to create, no billing required for Chat API config)
Your engine must be publicly reachable (use ngrok for local development)

Setup

Admin UI
Config file

Open the integrations admin page

Navigate to /admin/integrations/ in the running standalone. The channel catalog shows the available channels including Google Chat.

Create the Google Chat integration

Click Google Chat and fill in the credentials.

Field	Value
`service_account_credentials_json`	Full JSON key file content from your GCP service account
`project_number`	GCP project number (found on the Cloud Console dashboard)

Save

Save the form. The reload pipeline registers the Google Chat webhook handler on the running engine.

Create a GCP project and enable the Chat API

Go to the Google Cloud Console
Create a new project (or use an existing one)
Navigate to APIs & Services > Library
Search for Google Chat API and click Enable

Create a service account

Go to IAM & Admin > Service Accounts
Click Create Service Account
Give it a name (e.g. “idun-chat-bot”)
Click Done (no additional roles needed)
Click on the service account > Keys tab > Add Key > Create new key > JSON
Save the downloaded JSON key file

Configure the Chat app

Go to the Google Chat API configuration
Fill in the app details:
- App name: Your agent’s name (this is what users will @mention)
- Avatar URL: Optional icon URL
- Description: Brief description of what the bot does
Under Connection settings, select HTTP endpoint URL
Set the URL to:

https://<your-domain>/integrations/google-chat/webhook

Under Authentication Audience, select Project Number
Under Visibility, choose who can discover and use the app
Click Save

Configure the integration

Add the Google Chat integration to your engine config:

config.yaml

integrations:
  - provider: "GOOGLE_CHAT"
    enabled: true
    config:
      service_account_credentials_json: '{"type": "service_account", "project_id": "my-project", ...}'
      project_number: "123456789012"

Field	Description
`service_account_credentials_json`	Full JSON content of the service account key file from step 2
`project_number`	GCP project number (found on the Cloud Console project dashboard, not the project ID)

You can also store the credentials JSON in an environment variable and reference it in the config to avoid putting secrets in YAML files.

Test it

Open Google Chat
Start a direct message with your bot, or add it to a space
@mention the bot followed by your message: @YourBotName do stuff for me
Your agent processes the message and replies in the same space

How it works

User @mentions the bot in a space or sends a direct message
Google Chat POSTs the interaction event to your engine’s webhook
Engine verifies the JWT bearer token (signed by chat@system.gserviceaccount.com) using the project number as audience
Engine extracts the message text (stripping the @mention prefix via argumentText)
Engine invokes the agent with the cleaned text
Engine sends the agent’s reply back via the Google Chat API (spaces.messages.create)

Session tracking: The Google Chat user resource name (users/123456) is used as the session ID, so conversation context is maintained per user. Bot messages ignored: The handler skips messages from senders with type BOT to avoid infinite loops. @mention stripping: Google Chat provides an argumentText field that contains the message text without the @mention. The engine uses this so your agent receives clean input (e.g. “do stuff for me” instead of “@BotName do stuff for me”).

Next steps

Slack

Connect your agent to Slack DMs and channels.

Microsoft Teams

Reach the same agent through Bot Framework in Teams.

Production hardening

Secure the engine before exposing webhooks to the public internet.

Documentation Index

​Prerequisites

​Setup

​How it works

​Next steps

Slack

Microsoft Teams

Production hardening

Prerequisites

Setup

How it works

Next steps