Google Chat

Your agents answer direct messages and mentions in Google Chat through a Chat app that you create once, in your own Google Cloud project. All of the workspace's agents share that one bot: the space (or the person writing) decides which agent answers.

What you'll need

• A Google Workspace account. Personal Gmail accounts can't host Chat apps.
• Permission to create a project and a Chat app in Google Cloud.
• About 10 minutes, once per workspace.

Step 1 — Create a project and enable the Chat API

1. Open Google Cloud Console and create a project, or pick an existing one.
2. Go to APIs & Services → Library and enable the Google Chat API.

Step 2 — Create a service account and download its key

1. Go to IAM & Admin → Service Accounts → Create service account.
2. Name it (for example agent-chat). Skip the role and access steps.
3. Open the service account, then Keys → Add key → Create new key → JSON.
4. A .json file downloads. Keep it private: it lets its holder post as your Chat app.

Step 3 — Copy your workspace's endpoint URL

1. In the app, go to Settings → Channels.
2. In Google Chat — shared bot, copy the endpoint URL. Leave the page open.

Step 4 — Configure the Chat app

1. In Google Cloud, go to APIs & Services → Google Chat API → Configuration.
2. Fill in the app name, avatar URL and description.
3. Under Functionality, enable Receive 1:1 messages and Join spaces and group conversations. The second is required for the bot to be added to spaces.
4. Under Connection settings, choose HTTP endpoint URL and paste the endpoint URL from Step 3. If Google asks about triggers, choose Use a common HTTP endpoint URL for all triggers.
5. Set Authentication audience to HTTP endpoint URL.
6. Under Visibility, make the app available to the people who should use it.
7. Scroll to the bottom and click Save.

Step 5 — Connect in the app

1. In Google Chat — shared bot, paste the whole contents of the .json key file into Service account key.
2. If Google showed a service account email in Step 4, paste it into Add-on service account email.
3. Click Connect. This can take a minute or two while the agents' gateways restart.

Who answers

• People: add the emails of everyone who should get replies. Anyone else is ignored.
• Direct messages: each person can have their own agent; everyone else gets the default agent.
• Spaces: add the bot to a space in Google Chat (type @ and the app's name, then Add to space). The space appears in settings; pick which agent answers there. Until you do, the default agent answers.

Changing people, the default agent or a space's agent takes effect immediately.

Step 6 — Say hello

1. Open Google Chat.
2. Click New chat and type your app's name; it appears under Apps. (It won't appear under Find apps, which lists only published apps.)
3. Send a message. The agent posts a short "thinking" note, then replaces it with its answer.

If the agents' machine was asleep, the first reply can take up to about a minute while it wakes.

Troubleshooting

Click Test in Google Chat — shared bot first. It reports whether each agent's Google Chat adapter is running, when the last message was delivered, and why the last one wasn't, if it wasn't.

"… is not on the People list" Add that person's email under People and save routing.

"… has no agent and there is no default agent" Pick a Default agent, or assign an agent to that space, and save routing.

"Google signed this request as …" Compare the address in the message with the service account email under Connection settings in Google Chat API → Configuration. If they match, paste it into Add-on service account email and click Save connection. If they do not match, the request came from a Chat app that is not yours: leave the field alone.

"Google sent audience …, expected …." The URL in Google's Connection settings doesn't match your workspace's endpoint URL, or the authentication audience isn't set to HTTP endpoint URL. Copy the URL from settings again and check both.

The app doesn't appear in Google Chat. Check the Chat app's Visibility includes you, and search by its exact name from New chat.

"No home channel is set for Google_Chat" The agent hasn't got a home channel yet (where it delivers scheduled results). The first direct message someone sends it becomes its home, so the notice stops after that first conversation. To choose a different home, send /sethome in the chat you want.

You can't add it to a space. Make sure Join spaces and group conversations is ticked and saved in the Chat app configuration. Changes can take a few minutes to apply.

Rotating the key. Create a new key for the service account in Google Cloud, paste it into Service account key and click Save connection. If the agents can't start with the new key, the save fails and they keep using the old one. Once the save succeeds, delete the old key in Google Cloud.

An agent with its own Chat app (advanced)

An agent that needs its own name in Google Chat, or must be kept separate from the others, can have its own Chat app: open the agent's Google Chat card and choose Own Chat app, then follow the same Google Cloud steps for a second app, using the endpoint URL shown on that card. That agent then leaves the shared bot, and only the people in its own Allowed user emails get replies. Disconnecting its own app puts it back on the shared bot.

Disconnect

Disconnect removes the key and Google Chat settings from every agent. Your People and space assignments are kept, so connecting again restores them.