ContextQMD
Back to Eliza

Google Chat Connector

packages/docs/connectors/googlechat.md

2.0.16.9 KB
Original Source

Google Chat Connector

Connect your agent to Google Chat for DMs and space conversations using the @elizaos/plugin-google-chat package.

Prerequisites

  • A Google Cloud project with the Google Chat API enabled
  • A service account with Chat Bot permissions

Configuration

FieldValue
Package@elizaos/plugin-google-chat
Registry IDgoogle-chat
Config keyconnectors.googlechat
Auto-enable triggerbotToken, token, or apiKey is truthy in connector config

The connector auto-enables when botToken, token, or apiKey is truthy in the connector config. The serviceAccountFile/audience fields alone do not trigger auto-enable -- you must include one of the trigger fields or add the plugin to plugins.allow.

Configure in ~/.eliza/eliza.json:

Google Chat authenticates via a service account JSON file, not an API key. The apiKey field below is only used to trigger auto-enable — it has no functional role in authentication.

json
{
  "connectors": {
    "googlechat": {
      "apiKey": "placeholder",
      "serviceAccountFile": "./service-account.json",
      "audienceType": "project-number",
      "audience": "123456789",
      "webhookPath": "/google-chat"
    }
  }
}

If you don't want to set a trigger field, add the plugin explicitly:

json
{
  "plugins": {
    "allow": ["@elizaos/plugin-google-chat"]
  },
  "connectors": {
    "googlechat": {
      "serviceAccountFile": "./service-account.json",
      "audienceType": "project-number",
      "audience": "123456789",
      "webhookPath": "/google-chat"
    }
  }
}

To disable:

json
{
  "connectors": {
    "googlechat": {
      "enabled": false
    }
  }
}

Setup

  1. Create a Google Cloud project and enable the Google Chat API.
  2. Create a service account with the Chat Bot role.
  3. Download the service account key file or configure inline credentials.
  4. Configure the Chat app in the Google Cloud Console with an HTTP endpoint pointing to your Eliza instance.
  5. Add the credentials and webhook path to your Eliza config.
  6. Start your agent.

Features

Environment Variables

The following environment variables are supported by the plugin:

VariableDescription
GOOGLE_CHAT_SERVICE_ACCOUNT_FILEPath to service account JSON key file
GOOGLE_CHAT_SERVICE_ACCOUNTInline service account JSON
GOOGLE_APPLICATION_CREDENTIALSStandard Google Cloud credentials path
GOOGLE_CHAT_AUDIENCE_TYPEAuthentication audience type (app-url or project-number)
GOOGLE_CHAT_AUDIENCEApp URL or project number
GOOGLE_CHAT_BOT_USERBot user identifier
GOOGLE_CHAT_WEBHOOK_PATHWebhook endpoint path
GOOGLE_CHAT_SPACESComma-separated list of spaces to join
GOOGLE_CHAT_ENABLEDSet to true to enable
GOOGLE_CHAT_REQUIRE_MENTIONOnly respond when @mentioned

Full Configuration Reference

All fields are defined under connectors.googlechat in eliza.json.

Core Fields

FieldTypeDefaultDescription
serviceAccountFilestring—Path to service account JSON key file
serviceAccountstring | object—Inline service account JSON (alternative to file)
audienceType"app-url" | "project-number"—Authentication audience type
audiencestring—App URL or project number (matches audienceType)
namestring—Account display name
enabledboolean—Explicitly enable/disable
capabilitiesstring[]—Capability flags
webhookPathstring—Webhook endpoint path (e.g., /google-chat)
webhookUrlstring—Full webhook URL override
botUserstring—Bot user identifier
configWritesboolean—Allow config writes from Google Chat events
allowBotsboolean—Allow interactions from other bots
requireMentionboolean—Only respond when @mentioned
dmPolicy"pairing" | "allowlist" | "open" | "disabled""pairing"DM access policy
groupPolicy"open" | "disabled" | "allowlist""allowlist"Group join policy
groupAllowFrom(string|number)[]—Allowed group/space IDs
historyLimitinteger >= 0—Max messages in context
dmHistoryLimitinteger >= 0—History limit for DMs
dmsobject—Per-DM history overrides keyed by DM ID. Each value: {historyLimit?: int}
textChunkLimitinteger > 0—Max characters per message chunk
chunkMode"length" | "newline"—Long message splitting strategy
mediaMaxMbnumber > 0—Max media file size in MB
blockStreamingboolean—Disable streaming responses
blockStreamingCoalesceobject—Coalescing settings: minChars, maxChars, idleMs
replyToMode"off" | "first" | "all"—Reply threading mode
typingIndicator"none" | "message" | "reaction""none"Typing indicator mode

Actions

FieldTypeDescription
actions.reactionsbooleanSend reactions to messages

DM Configuration

The dm sub-object provides additional DM-level policy:

FieldTypeDefaultDescription
dm.enabledboolean—Enable/disable DMs
dm.policy"pairing" | "allowlist" | "open" | "disabled""pairing"DM access policy. "open" requires dm.allowFrom to include "*"
dm.allowFrom(string|number)[]—User IDs allowed to DM

Group Configuration

Per-group settings are defined under groups.<group-id>:

FieldTypeDescription
enabledbooleanEnable/disable this group
allowbooleanAllow messages in this group
requireMentionbooleanOnly respond when @mentioned
users(string|number)[]Allowed user IDs in this group
systemPromptstringGroup-specific system prompt

Multi-Account Support

The accounts field allows running multiple Google Chat bots from a single agent:

json
{
  "connectors": {
    "googlechat": {
      "accounts": {
        "workspace-1": {
          "serviceAccountFile": "./sa-1.json",
          "audienceType": "project-number",
          "audience": "111111111"
        },
        "workspace-2": {
          "serviceAccountFile": "./sa-2.json",
          "audienceType": "project-number",
          "audience": "222222222"
        }
      },
      "defaultAccount": "workspace-1"
    }
  }
}

Account-level settings override the base connector settings. Use defaultAccount to specify which account is used when none is explicitly selected.