Skip to content

Google Chat Integration

Connect your Google Chat spaces to Raikoo to build interactive AI-powered bots that respond to user messages with rich card-based responses.

What You Can Build

  • Team assistants that answer questions using your organization's knowledge
  • Workflow triggers that execute automated processes when users send commands
  • Support bots that handle common requests and escalate complex issues

Prerequisites

Before setting up Google Chat integration, you will need:

  • A Google Cloud project with the Google Chat API enabled
  • Admin access to your Raikoo organization
  • Permission to create Chat apps in your Google Workspace

Setup Steps

Step 1: Create a Google Cloud Project

If you do not already have a Google Cloud project:

  1. Go to the Google Cloud Console
  2. Click Select a project at the top of the page
  3. Click New Project
  4. Enter a project name and click Create

Step 2: Enable the Google Chat API

  1. In your Google Cloud project, go to APIs & Services > Library
  2. Search for "Google Chat API"
  3. Click on it and then click Enable

Step 3: Configure the Chat App

  1. Go to the Google Chat API configuration page
  2. Click Configuration in the left sidebar
  3. Fill in the app details:
  4. App name: Choose a name users will see (e.g., "Raikoo Assistant")
  5. Avatar URL: Optionally provide an icon URL
  6. Description: Describe what your bot does
  7. Under Functionality, enable:
  8. "Receive 1:1 messages" if you want direct message support
  9. "Join spaces and group conversations" if you want group chat support
  10. Under Connection settings, select App URL and enter your Raikoo webhook URL (you will get this URL after creating a trigger in Raikoo)
  11. Under Visibility, configure who can install the app

Step 4: Create a Service Account

  1. Go to IAM & Admin > Service Accounts
  2. Click Create Service Account
  3. Enter a name and description
  4. Click Create and Continue
  5. Skip the optional role assignments and click Done
  6. Click on the service account you just created
  7. Go to the Keys tab
  8. Click Add Key > Create new key
  9. Select JSON and click Create
  10. Save the downloaded JSON file securely - you will need it for Raikoo

Step 5: Create a Connection in Raikoo

  1. Navigate to your organization in Raikoo
  2. Click Connections in the left navigation
  3. Click Create Connection
  4. Configure the connection:
  5. Name: Give it a descriptive name (e.g., "Google Chat Bot")
  6. Description: Optional description of the connection's purpose
  7. Platform: Select Google Chat
  8. Go to the Credentials tab
  9. Select Use custom credentials
  10. Enter your credentials:
  11. Project ID: Your Google Cloud Project ID (find this in the Google Cloud Console)
  12. Service Account Key: Paste the entire contents of the JSON key file you downloaded
  13. Click Save

Step 6: Create an Integration (Trigger)

  1. Navigate to Integrations in the left navigation
  2. Click Create Trigger
  3. Configure the trigger:
  4. Name: A descriptive name for this integration
  5. Description: What this integration does
  6. External Connection: Select the Google Chat connection you created
  7. Go to the Execution tab:
  8. Execution Mode: Choose "Chat Agent" to route messages to an AI agent, or "Workflow" to execute a specific workflow
  9. Project: Select the project containing your agent or workflow
  10. Chat Agent (if using Chat mode): Select the AI agent to handle messages
  11. Authentication Mode: Choose how to authenticate workflow executions
  12. Click Save

Step 7: Configure the Webhook URL

After saving your trigger:

  1. Go to the Webhook tab
  2. Copy the Webhook URL
  3. Go back to your Google Chat API configuration in Google Cloud Console
  4. Paste the URL in the App URL field
  5. Save the configuration

Step 8: Connect a Google Chat Space

For messaging platforms, you need to bind your Chat space to the trigger:

  1. In Raikoo, go to your trigger's Channels tab
  2. Copy the binding command (e.g., @Raikoo /connect ABC123)
  3. Add your Chat app to a Google Chat space
  4. In that space, send the binding command
  5. You should see the space appear in the Connected Channels list

Testing Your Integration

  1. Open the Google Chat space where you added the bot
  2. Send a message to the bot (e.g., "@YourBotName Hello!")
  3. You should see a response from your AI agent or a confirmation that your workflow executed

Message Formatting

Raikoo automatically converts responses to Google Chat's Cards v2 format:

Markdown Google Chat
**bold** Bold text
*italic* Italic text
[link text](url) Clickable link
# Header Bold header
Code blocks Formatted code

For complex responses, your AI agent can generate rich card layouts with sections, buttons, and other widgets.

Chat Settings

After creating your trigger, configure chat-specific settings in the Chat Settings tab. These settings control how the bot responds, which users and spaces are allowed, and how attachments are handled.

Bot Responses

Setting Default Description
Send welcome message on install On Send a greeting when the bot is added to a space
Welcome Message Built-in default Custom message shown when the bot joins a space
Hello Response Uses welcome message Custom response when a user says "hello" or "hi"
Help Response Built-in default Custom response when a user says "help"
Send typing indicator Off Show a typing status while the bot is processing

User Filtering

Control which users can interact with the bot:

Setting Description
Allowed Users (whitelist) Only process messages from these users. Supports patterns
Blocked Users (blacklist) Ignore messages from these users. Supports patterns

Channel Filtering

Setting Default Description
Allowed Channels Empty (all spaces) Whitelist of space IDs or patterns
Blocked Channels Empty Blacklist of space IDs or patterns
Allow direct messages On Process 1:1 conversations with the bot
Allow channel messages On Process messages from group spaces (when @mentioned)

Message Filtering

Setting Default Description
Required message patterns Empty Only process messages matching these glob patterns
Blocked message patterns Empty Ignore messages matching these patterns
Max message length 0 (unlimited) Skip messages longer than this (in characters)

Attachments

When users send files alongside their messages, Raikoo can process them and make them available to the AI agent.

Setting Default Description
Process attachments Off Enable attachment processing. When off, attachments are ignored
Convert to Markdown file On Create .md shadow files for PDFs and DOCX documents so the agent can read their content
Send images to AI Off Include images directly in the AI context (requires a vision-capable model)
Send PDFs to AI Off Include PDFs directly in the AI context (requires a compatible provider such as Anthropic)
Send audio to AI Off Include audio files directly in the AI context (requires a compatible provider)
Send video to AI Off Include video files directly in the AI context (requires a compatible provider)
Max attachment size (KB) 5120 (5 MB) Attachments larger than this are skipped. Set to 0 for unlimited
Allowed attachment types Empty (all types) MIME type whitelist. Example: application/pdf, image/*

How Attachment Processing Works

When a user sends a message with attachments:

  1. Attachments are downloaded from Google Chat and written to the agent's workspace as files
  2. Document conversion (if enabled) creates shadow markdown files alongside the originals (e.g., report.pdf.md)
  3. Context-stuffing (the "Send to AI" options) additionally includes the file data directly in the AI's input for models that support native file handling
  4. The AI agent is informed that files are available in its workspace and can reference them by path

Troubleshooting

Bot Not Responding

  1. Verify the webhook URL is correctly configured in Google Cloud Console
  2. Check that your trigger is set to Active
  3. Verify your service account credentials are correct
  4. Check that the Chat space is properly connected in the Channels tab

Authentication Errors

  1. Ensure your service account has the correct permissions
  2. Verify the Project ID matches your Google Cloud project
  3. Make sure the JSON key has not expired

Messages Not Reaching Raikoo

  1. Check that the Google Chat API is enabled
  2. Verify the Chat app is configured with the correct webhook URL
  3. Ensure the app has been added to the Chat space

Best Practices

  • Use descriptive names: Name your connections and triggers clearly so team members understand their purpose
  • Test in a dedicated space: Create a test space before deploying to production channels
  • Monitor for errors: Check your Raikoo logs for any processing errors
  • Use rich formatting: Take advantage of Cards v2 to create visually appealing responses

Next Steps