Google Chat Integration

Connect your agent to Google Chat for seamless communication within Google Workspace.

Overview

Google Chat integration provides:

• Direct messaging with your bot
• Google Workspace Spaces support with @mention triggers
• Document Q&A — upload a file and ask the bot about it (paid plans)
• Space Knowledge Base — Spaces remember every document shared in them and answer from the whole collection
• Cited answers — the bot names the document or source it answered from
• Space-level agent routing — assign different agents to different Spaces
• Conversation memory and opt-in space context awareness
• Async processing with instant acknowledgment
• Enterprise-ready security with domain-based isolation

Prerequisites

• An active AI agent (created in the Agents section)
• A Google Workspace account (personal Gmail accounts are not supported)
• A verified domain — verify your domain ownership in Settings > Domains before connecting

Setup Steps

1. Verify Your Domain (One-Time Setup)

Before connecting Google Chat, verify your domain ownership:

1. Go to Settings from the sidebar
2. Click the Domains tab
3. Your domain is auto-detected from your account email
4. Add a TXT record in your DNS provider with the values shown:
   • Type: TXT
   • Name: _cuneiform-verify (or the full value shown)
   • Content: The verification string displayed (e.g., cuneiform-verify=abc123...)
5. Click Verify Now — DNS changes can take up to 48 hours to propagate
6. Once the status changes to Verified, proceed to create the integration

Quick links to common DNS providers (Cloudflare, GoDaddy, Namecheap, Route 53, DigitalOcean, Hostinger) are shown on the verification card.

2. Create Google Chat Integration

1. Go to Integrations from the sidebar
2. Under “Google Chat Bots”, click Connect Bot
3. Select the Agent that will be the default for DMs and unlinked Spaces
4. Enter a Bot Name (for your reference in the admin panel)
5. Click Connect Bot
6. Copy the Verification Code displayed (format: VERIFY-XXXXXX)

3. Complete Bot Verification

After creating the integration, you’ll receive a verification code:

1. Open Google Chat
2. Click Start a chat → Find apps
3. Search for the platform bot
4. Start a direct message with the bot
5. Send the verification code (e.g., VERIFY-ABC123)
6. The bot will confirm: “Setup complete! Your workspace (yourdomain.com) is now connected. Send a message to start chatting!”

Your integration status will change from “Pending Verification” to “Active”.

Using the Bot

Direct Messages

Users can start a conversation:

1. Open Google Chat
2. Click Start a chat → Find apps
3. Search for your bot name
4. Start chatting naturally — the bot responds to all messages in DMs

DMs are always handled by the default agent.

In Spaces

Add the bot to a Space:

1. Open the Space
2. Click the Space name → Manage apps
3. Add your bot
4. Mention the bot with @Cuneiform Chat to interact — the bot only responds to @mentions in Spaces

Space-Level Agent Routing

Each Space can optionally use a different agent than the default. Use these bot commands in a Space (requires @mention):

How routing works:

• DMs → always use the default agent
• Space with custom agent → uses the assigned agent
• Space without custom agent → falls back to the default agent

Thread History Awareness

By default, the bot only sees the message that directly @mentioned it. If team members send context messages first (in other threads or earlier in the Space) and then @mention the bot, it won’t have that context — unless a Space manager runs /connect.

How It Works

1. A Space manager sends @Cuneiform Chat /connect in the Space
2. The bot sends a one-time authorization link (expires in 10 minutes)
3. The manager clicks the link and signs in with their Google Workspace account
4. The bot can now read the Space’s most recent messages (up to 10) from the past 24 hours before each @mention

Once connected, on every @mention the bot automatically reads recent Space messages as context — understanding what the team was discussing before it was @mentioned.

Example: Team members post “what are the pricing plans?” and “what’s included in starter?” then @mention the bot with “can you help?” — the bot sees all three messages and responds with full context.

Requirements and Privacy

• Only Space managers (not regular members) can run /connect
• Authorization is per-Space — each Space needs its own /connect
• The space manager’s Google OAuth token is encrypted and stored securely
• Only messages visible to that manager’s account are readable
• Removing the bot from a Space automatically deletes the stored token

Re-authorization

If the bot loses access (e.g., token revoked in your Google account), it will notify the Space:

⚠️ Thread history access has expired or been revoked. A space manager should run /connect to restore it.

Run /connect again to restore access.

Features

Async Responses

When you send a message, the bot immediately replies with a brief acknowledgment (e.g., “Working on it…”) and then delivers the full answer once processing is complete. This typically takes 3–8 seconds depending on the complexity of your question.

Conversation Memory

The bot remembers context within a session, so you can ask follow-up questions without repeating yourself.

Space context awareness (opt-in): After a Space manager runs /connect, the bot reads the Space’s most recent messages (up to 10) from the past 24 hours before each @mention — so it understands what the team was already discussing without you needing to repeat context. See Thread History Awareness below for setup steps.

Message Queuing

If you send additional messages while the bot is still processing, they are queued and included in the next response. You’ll see a message like “I’m still working on your previous question. I’ll include this in my next response.”

/help Command

Type /help or help to see usage instructions, including available space commands.

Domain-Based Access

Only users from your Google Workspace domain can interact with your bot, ensuring enterprise-level security.

Text Replies

The bot replies in text — it doesn’t send images, interactive buttons, or card attachments, and responses are limited to approximately 30,000 characters. You can send documents to the bot, though — see Working with Documents below.

Working with Documents

On paid plans, team members can upload a document and ask the bot about it — in a DM or a Space.

Attach and Ask

1. In a DM or Space (with an @mention in Spaces), attach a file and ask your question
2. The bot reads the document and answers from it
3. Keep asking follow-up questions — the document stays active for the conversation, no re-attaching needed

Supported file types: PDF, DOCX, PPTX, TXT, and Markdown.

File size limits: up to 10 MB on Starter, 50 MB on Plus, and 100 MB on Enterprise.

One document per message: if you attach several files at once, the bot uses the first and asks you to send the rest one at a time.

Cited Answers

When the bot answers from a document or your knowledge base, it names the source — for example, “According to handbook.pdf, …” — so your team can trust where each answer came from. Citations are on by default.

Space Knowledge Base

In a Space, the bot can remember every document shared there and build a living knowledge base for the team. Once a document is shared in a Space, the bot answers questions about it in any thread of that Space — not only the thread where it was uploaded — alongside your organization’s main knowledge base.

• On by default in Spaces (paid plans) — no setup required
• Documents accumulate — each file shared in the Space is remembered; newer uploads don’t replace older ones
• Stays within the Space — documents remembered in one Space are never used to answer in another
• Counts toward your document quota — unlike one-off attachments, documents kept in a Space’s knowledge base count against your organization’s document allowance
• Cleanup — remembered documents are cleared automatically if the bot is removed from the Space

Manage it per-Space with bot commands:

Managing Your Integration

Each integration card displays:

• Bot name - The display name you configured
• Status badge - Active, Pending Verification, or Error
• Domain name - Your Google Workspace domain (after verification)
• Default agent - Dropdown to change the default agent (used for DMs + unlinked Spaces)
• Space mappings - Collapsible section showing which Spaces have custom agent assignments
• Space commands - Collapsible section showing available bot commands
• Last activity timestamp

Available Actions

Troubleshooting

Bot Not Appearing in Google Chat

1. Ensure you’re using a Google Workspace account (not personal Gmail)
2. Search for the bot name in “Find apps”
3. Wait a few minutes for the app to propagate

Google Chat Section Not Visible

1. Google Chat only appears for organizations using Google Workspace
2. If your organization uses a different email provider (e.g., Microsoft 365), the section is hidden
3. The system automatically detects your email provider via MX records

Domain Verification Issues

1. DNS changes can take up to 48 hours to propagate — wait and try Verify Now again
2. Check that you added the TXT record with the exact values shown in Settings > Domains
3. Verify the record is on the correct domain (e.g., _cuneiform-verify.yourdomain.com)
4. Use the DNS provider quick links on the verification card for easy access

Verification Code Not Working

1. Ensure you’re sending the code from your Google Workspace email
2. Check that the code is entered exactly as shown (including the VERIFY- prefix)
3. Verify the integration is still in “Pending Verification” status
4. Try creating a new integration if the code has expired

Bot Says “Working on it…” But No Response Follows

1. The bot processes messages asynchronously — wait up to 25 seconds for the full response
2. If no response arrives, try sending your message again
3. Check that the associated agent is properly configured

Messages Not Being Processed

1. Confirm your workspace has been verified (status should be “Active”)
2. For Spaces, ensure you’re @mentioning the bot
3. Check that the associated agent is properly configured

”Organization hasn’t connected” Message

This means the bot doesn’t recognize your Google Workspace domain:

1. Your admin hasn’t created the integration yet
2. The domain hasn’t been verified with a verification code
3. You’re messaging from a personal Gmail account (not supported)

/set-agent Says Agent Not Found

1. Check the exact agent name in the admin panel (case-sensitive)
2. Ensure the agent is in “Active” status
3. Agent names with spaces are supported — type the full name after /set-agent

/connect Says “Only space managers can run /connect”

You must be a Space manager to run /connect. Ask a Space manager in your Space to run the command.

/connect Authorization Link Expired

The link is valid for 10 minutes. Run @Cuneiform Chat /connect again to get a fresh link.

Bot Says “Thread history access has expired”

A Space manager needs to run @Cuneiform Chat /connect again to re-authorize. This happens when the Google OAuth token is revoked (e.g., in Google account settings).

Uploaded Document Came Back Empty

1. Scanned or image-only PDFs often can’t be read by the standard parser — ask an admin to enable premium parsing on the Google Chat integration
2. Confirm the file type is supported (PDF, DOCX, PPTX, TXT, Markdown) — spreadsheets/CSV, images, and Drive links are not
3. Check the file is within your plan’s size limit (10 MB Starter, 50 MB Plus, 100 MB Enterprise)

Can’t Upload Documents

1. Document attachments are a paid-plan feature — they aren’t available on the free trial
2. An admin can confirm “Allow document attachments” is enabled on the Google Chat integration card

Security

• Domain ownership verification — DNS TXT record proves your organization owns the domain before connecting
• Google Workspace detection — MX record check confirms your domain uses Google Workspace
• Domain-based isolation — only your organization’s Google Workspace users can interact with your bot
• Webhook verification — every incoming request is validated against your platform’s Google Cloud project
• Verification codes are single-use and tied to your domain
• Messages processed over secure, encrypted connections

Disconnecting

To remove the Google Chat integration:

1. Go to Integrations from the sidebar
2. Find your Google Chat integration card
3. Click the three-dot menu
4. Select Disconnect

Important Notes

• Google Workspace required: Personal Gmail accounts cannot use this integration. If your org doesn’t use Google Workspace, the Google Chat section won’t appear.
• Domain verification required: Verify your domain in Settings > Domains before connecting Google Chat.
• One integration per organization: Each organization can have one Google Chat integration
• Text replies: The bot replies in text (no images or interactive buttons), but it can receive and answer questions about uploaded documents on paid plans — see Working with Documents
• Managed at org level: Google Chat is configured on the Integrations page, not per-agent
• Space routing: Use /set-agent in Spaces to assign specialized agents to different teams
• Default agent: Change the default agent anytime using the dropdown — no disconnect needed