> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idun-group.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Chat

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

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](https://workspace.google.com) account with access to Google Chat
* A [Google Cloud](https://console.cloud.google.com) project (free to create, no billing required for Chat API config)
* Your engine must be publicly reachable (use [ngrok](https://ngrok.com) for local development)

## Setup

<Tabs>
  <Tab title="Admin UI">
    <Steps>
      <Step title="Open the integrations admin page">
        Navigate to `/admin/integrations/` in the running standalone. The channel catalog shows the available channels including Google Chat.
      </Step>

      <Step title="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) |
      </Step>

      <Step title="Save">
        Save the form. The reload pipeline registers the Google Chat webhook handler on the running engine.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Config file">
    <Steps>
      <Step title="Create a GCP project and enable the Chat API">
        1. Go to the [Google Cloud Console](https://console.cloud.google.com)
        2. Create a new project (or use an existing one)
        3. Navigate to **APIs & Services** > **Library**
        4. Search for **Google Chat API** and click **Enable**
      </Step>

      <Step title="Create a service account">
        1. Go to **IAM & Admin** > **Service Accounts**
        2. Click **Create Service Account**
        3. Give it a name (e.g. "idun-chat-bot")
        4. Click **Done** (no additional roles needed)
        5. Click on the service account > **Keys** tab > **Add Key** > **Create new key** > **JSON**
        6. Save the downloaded JSON key file
      </Step>

      <Step title="Configure the Chat app">
        1. Go to the [Google Chat API configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
        2. 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
        3. Under **Connection settings**, select **HTTP endpoint URL**
        4. Set the URL to:

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

        5. Under **Authentication Audience**, select **Project Number**
        6. Under **Visibility**, choose who can discover and use the app
        7. Click **Save**
      </Step>

      <Step title="Configure the integration">
        Add the Google Chat integration to your engine config:

        ```yaml config.yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
        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) |

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

      <Step title="Test it">
        1. Open Google Chat
        2. Start a direct message with your bot, or add it to a space
        3. @mention the bot followed by your message: `@YourBotName do stuff for me`
        4. Your agent processes the message and replies in the same space
      </Step>
    </Steps>
  </Tab>
</Tabs>

## How it works

1. User @mentions the bot in a space or sends a direct message
2. Google Chat POSTs the interaction event to your engine's webhook
3. Engine verifies the JWT bearer token (signed by `chat@system.gserviceaccount.com`) using the project number as audience
4. Engine extracts the message text (stripping the @mention prefix via `argumentText`)
5. Engine invokes the agent with the cleaned text
6. 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

<Card title="Slack" icon="hash" horizontal href="/integrations/slack">
  Connect your agent to Slack DMs and channels.
</Card>

<Card title="Microsoft Teams" icon="users" horizontal href="/integrations/teams">
  Reach the same agent through Bot Framework in Teams.
</Card>

<Card title="Production hardening" icon="shield-halved" horizontal href="/deployment/hardening">
  Secure the engine before exposing webhooks to the public internet.
</Card>