Google Chat

Your agent answers as a Google Chat app. Google Chat sends each message to the agent’s webhook, and VirtuAI posts the answer back through the Google Chat API.

Before you start

• A workspace role that can edit Settings and Agents
• A Google Cloud project with the Google Chat API enabled, and permission to configure a Chat app in your Google Workspace
• A service account in that project, with a JSON key
• An agent already created in VirtuAI. See Create your first agent.

1. Add the service account

In Settings, set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON to the full contents of the service account’s JSON key. VirtuAI uses it to post replies and to download audio attachments.

Then check GOOGLE_CHAT_PROJECT_NUMBER, the number of the Google Cloud project where the Chat app is configured. VirtuAI uses it to verify that each request really comes from your Chat app (see step 6):

• When you save the service account JSON, VirtuAI looks up the project number and fills it in. The lookup needs the service account to have the resourcemanager.projects.get permission on its project, for example through the Browser role (roles/browser).
• If the setting is still empty after saving, the service account can’t read its project. Type the number yourself: it’s shown as Project number on the project’s dashboard in the Google Cloud console. The lookup runs only when the JSON changes, so saving the same JSON again doesn’t repeat it.

The service account must belong to the same project as the Chat app.

Optionally, change what people see while the agent works:

Setting	What it does
GOOGLE_CHAT_WAITING_MESSAGE	The text of the waiting message. The default is in Spanish, so set your own if your users aren’t.
GOOGLE_CHAT_WAITING_IMAGE_URL	An image or animated GIF shown with the waiting message

2. Turn on Google Chat for the agent

Edit the agent. In Channels, make sure Google Chat is on. It’s on by default, and the card reads Responds in Google Chat spaces. In AI Model Configuration, choose the model, then save.

3. Copy the webhook URL

In the agent’s Integration URLs, copy Google Chat Webhook. It looks like this and belongs to this agent only:

https://<your-virtuai-host>/googlechat/webhook/<agent-id>

4. Configure the Chat app

In the Google Cloud console, open the Google Chat API configuration for your project:

1. Give the app a name, avatar and description.
2. Under connection settings, choose an HTTP endpoint and paste the webhook URL.
3. Set Authentication audience to Project number. VirtuAI only accepts requests whose token is issued for your project number.
4. Choose who in your Google Workspace can find and use the app.
5. Save.

5. Add slash commands (optional)

The agent understands five commands. To make them show up in Google Chat’s command menu, add them in the Chat API configuration with these command IDs:

Command	Command ID	What it does
/new [title]	1	Starts a new conversation, with an optional title
/resume	2	Lists your last 5 conversations. /resume 2 switches to the second one.
/status	3	Tells you whether the agent is still working, and for how long
/cancel	4	Stops the running task
/help	5	Lists the commands

6. Check request verification

Google Chat signs every request it sends to your app with a token issued for your project. VirtuAI checks that token against GOOGLE_CHAT_PROJECT_NUMBER and rejects with 401 any request that doesn’t carry a valid token for that project. If you run the app as a Google Workspace add-on, VirtuAI checks that the request comes from your project’s add-on service agent instead, and there is nothing else to configure.

Before you go live, check that:

• GOOGLE_CHAT_PROJECT_NUMBER is set in Settings.
• The Chat app’s Authentication audience is Project number.

Google Chat doesn’t use integration keys: once the project number is set, Google’s token replaces them.

7. Test

1. Message the app directly and send a greeting.
2. Ask a real business question.
3. Add the app to a space, mention it with @, and ask again.
4. Check that the conversation appears in Conversations.

How messages behave

• Waiting message. The app first posts the waiting message. While a deep agent works, it shows one card with the plan and each step, updated in place.
• Conversations. Each person has their own conversation with the agent in each space or direct message. Use /new to start fresh.
• Busy agent. If you write while a deep agent is still working, the app answers “Got it — I’ll respond once I finish your current request.” and handles your message next.
• Replies to messages. When you reply to or quote a message, the quoted text is sent to the agent as context.
• Attachments. Audio attachments are passed to the agent. Other attachments, such as images and documents, are ignored.
• Your accounts. If the sender’s Google email matches a member of your VirtuAI workspace, the agent uses that member’s connected accounts, for example their Gmail or Drive.
• Budgets. If the workspace has run out of budget, the app replies with the budget message instead of an answer.
• Channel off. If Google Chat is off for the agent, the app replies “This agent is not available on Google Chat.”

Troubleshooting

No reply in Google Chat : Check GOOGLE_CHAT_SERVICE_ACCOUNT_JSON, that Google Chat is on for the agent, and that the app’s endpoint is this agent’s webhook URL. Then check request verification.

Requests are rejected with 401 : VirtuAI couldn’t verify Google’s token. Check that the Chat app’s Authentication audience is Project number, not HTTP endpoint URL, and that GOOGLE_CHAT_PROJECT_NUMBER in Settings is the number of the project where the Chat app is configured.

The waiting message appears, but no answer follows : The agent failed while working. Check the agent’s model and tools in web chat, then look at the conversation in Conversations.

Authentication or permission errors when posting : The service account must belong to the project where the Chat app is configured.

The wrong agent replies : The app’s endpoint has another agent’s ID. Copy the URL again from the right agent’s Integration URLs.