Google Chat Adapter

The Google Chat adapter (chat_sdk-gchat) integrates with Google Chat using the Google Chat API and Card v2.

InstallationCopy Anchor Link

# Gemfile
gem "chat_sdk"
gem "chat_sdk-gchat"

ConfigurationCopy Anchor Link

require "chat_sdk"
require "chat_sdk/gchat"

gchat = ChatSDK::GChat::Adapter.new(
  project_number: ENV["GOOGLE_CHAT_PROJECT_NUMBER"],
  endpoint_url: "https://your-domain.com/webhooks/gchat",
  pubsub_audience: ENV["GOOGLE_CHAT_PUBSUB_AUDIENCE"],
  pubsub_service_account_email: ENV["GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL"],
  workspace_add_on_service_account_email: ENV["GOOGLE_CHAT_WORKSPACE_ADDON_SERVICE_ACCOUNT_EMAIL"],
  credentials: nil  # Uses Application Default Credentials
)

Credentials OptionsCopy Anchor Link

The credentials parameter accepts several formats:

# 1. nil -- Use Application Default Credentials (ADC)
gchat = ChatSDK::GChat::Adapter.new(project_number: "123456")

# 2. String -- Path to a service account JSON file
gchat = ChatSDK::GChat::Adapter.new(
  project_number: "123456",
  credentials: "/path/to/service-account.json"
)

# 3. Hash -- Service account JSON as a Ruby hash
gchat = ChatSDK::GChat::Adapter.new(
  project_number: "123456",
  credentials: {
    "type" => "service_account",
    "project_id" => "my-project",
    # ...
  }
)

# 4. Pre-built credentials object
gchat = ChatSDK::GChat::Adapter.new(
  project_number: "123456",
  credentials: my_credentials_object
)

Environment VariablesCopy Anchor Link

Webhook VerificationCopy Anchor Link

Direct Google Chat webhooks support two authentication audience modes:

• Project number: Set project_number or GOOGLE_CHAT_PROJECT_NUMBER. Tokens are verified against Google's X.509 certificates for chat@system.gserviceaccount.com, with the project number as the audience.
• HTTP endpoint URL: Set endpoint_url to the configured public webhook URL. This value has no environment-variable fallback and is used as the exact OIDC audience. The verified token must identify chat@system.gserviceaccount.com or exactly match the configured workspace_add_on_service_account_email.

When both direct-webhook options are configured, either token mode is accepted. The endpoint URL is never inferred from the incoming request.

The normal webhook endpoint also accepts Pub/Sub pushes. Configure both pubsub_audience and pubsub_service_account_email (or their environment variables) to validate the OIDC audience and exact, verified service-account email. The endpoint detects Pub/Sub envelopes, verifies them with this separate verifier, and parse_events decodes them; a direct-webhook verifier alone does not authenticate Pub/Sub pushes.

The adapter requires at least one direct-webhook verifier, a Pub/Sub audience, or disable_signature_verification: true. The explicit disable option (or GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true) accepts requests without a verifier for that transport and logs a warning once. Use it only when verification is intentionally handled elsewhere.

Google Cloud SetupCopy Anchor Link

1. In the Google Cloud Console, enable the Google Chat API.
2. Create a service account with the Chat Bot scope.
3. Configure your Chat app in the Google Cloud Console:
   • Set the app URL to your webhook endpoint.
   • Configure slash commands if needed.
4. Publish the app to your organization or make it available in Google Workspace Marketplace.

Webhook URLCopy Anchor Link

https://your-domain.com/webhooks/gchat

map "/webhooks/gchat" do
  run bot.webhooks[:gchat]
end

CapabilitiesCopy Anchor Link

Resource NamesCopy Anchor Link

Google Chat uses resource names like spaces/SPACE_ID/messages/MESSAGE_ID. ChatSDK extracts the last segment as the ID, so message.id returns just MESSAGE_ID and channel_id is SPACE_ID.

Cards RenderingCopy Anchor Link

Cards are rendered as Google Chat Card v2 JSON using CardV2Renderer.

Mention FormattingCopy Anchor Link

Google Chat uses the format <users/USER_ID>:

thread.mention_user("12345")  # => "<users/12345>"

Direct Client AccessCopy Anchor Link

gchat_adapter = bot.adapter(:gchat)
client = gchat_adapter.client  # Google::Apps::Chat::V1::ChatService::Client

Pub/Sub EventsCopy Anchor Link

For apps using Google Workspace Events with a Cloud Pub/Sub subscription, configure pushes to the normal Google Chat webhook endpoint shown above. That endpoint verifies the Pub/Sub token and parse_events decodes the envelope's base64-encoded message.data.

If a custom route calls parse_pubsub_event directly, verify the request first. The parser does not authenticate requests:

post "/custom/pubsub/gchat" do
  gchat_adapter.verify_request!(request)
  events = gchat_adapter.parse_pubsub_event(request)
  events.each { |event| handle(event) }
  status 200
end

The adapter delegates decoded payloads to the same EventParser used for direct webhooks.