# Google Chat

Source: https://docs.stacksync.com/ai-agents/genie-interfaces/google-chat

Connect a genie to Google Chat and talk to it in direct messages or by @mentioning it in a space.

The genie answers through a **Chat app that you own**, created in your organization's Google Cloud project. Setup has two halves: a **Google Cloud admin** creates the Chat app and its service account key, and a **Stacksync workspace admin** connects it to your genie.

<Callout type="info">
  Your Google Cloud project must belong to the same Google Workspace organization as the people who will talk to the genie. A Chat app that isn't published to the Marketplace is only available inside its own organization.
</Callout>

### 1. Enable the Google Chat API (Google Cloud admin)

In the [Google Cloud console](https://console.cloud.google.com/), pick the project that will hold the Chat app, open **APIs & Services** → **Library**, search for **Google Chat API** and click **Enable**.

### 2. Create a service account and its key

Open **IAM & Admin** → **Service Accounts** → **Create service account**. Name it, for example `stacksync-genie`, click **Create and continue**, skip the optional roles and click **Done**.

Open the new service account → **Keys** → **Add key** → **Create new key** → **JSON** → **Create**. A JSON key file downloads.

<Callout type="warn">
  The key file is a credential. Paste it only into the Stacksync connection form in the next step, and delete the file from your computer afterwards.
</Callout>

### 3. Create the Google Chat connection

In Stacksync: **Connections** → **Create new connection** → **Google Chat**. Paste the full contents of the JSON key file into **App credentials JSON** and finish the steps.

### 4. Attach the connection to your genie

Open your genie → **Interfaces** → **Add** → **Google Chat** → select the connection.

The dialog shows the **HTTP endpoint URL** for this connection, in the form `https://genies.stacksync.com/v1/google-chat/?connection=<connection id>`. Copy it with the copy button; you need it in the next step. Leave the dialog open.

### 5. Configure the Chat app (Google Cloud admin)

Back in the Google Cloud console, open **APIs & Services** → **Google Chat API** → **Configuration** and set:

| Setting                                   | Value                                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Build this Chat app as a Workspace add-on | Leave it **checked** (the default), the setup Stacksync supports. Unchecking it can't be undone. |
| App name                                  | `Genie`                                                                                          |
| Avatar URL                                | `https://i.imgur.com/8LJQlIh.png`                                                                |
| Description                               | A short description, for example `Stacksync AI assistant`                                        |
| Interactive features                      | On                                                                                               |
| Join spaces and group conversations       | On                                                                                               |
| Connection settings                       | **HTTP endpoint URL**, then **Use a common HTTP endpoint URL for all triggers**                  |
| HTTP endpoint URL                         | The URL you copied in step 4                                                                     |
| Visibility                                | The people or groups in your organization who may use the genie                                  |
| Log errors to Cloud Logging               | On                                                                                               |

Click **Save**.

<Callout type="info">
  Editing this page needs the **Chat Apps Owner** role (`chat.bots.update`) on the project. If the page says you don't have permission, ask your Google Cloud admin to grant it or to fill in the page.
</Callout>

Then return to the Stacksync dialog, tick **I have updated the HTTP endpoint URL in Google Cloud** and click **Save**.

### 6. Set access rights

If the people in your Visibility list don't all have Stacksync accounts, open the genie's **Access rights** tab and set **Who can use the Genie** to **Public (authentication not required)**. Otherwise the genie only answers Stacksync workspace members.

### 7. Talk to it

* **In a direct message:** open [Google Chat](https://chat.google.com/), click **New chat**, search for **Genie** (or the app name you chose) and send it a message. No mention needed.
* **In a space:** type `@Genie` (or the app name you chose), select it from the results and add your question. The first time, Chat offers **Add to space**; click it. You can also add the app from the space name → **Apps & integrations** → **Add apps**.

The genie replies in the same thread. A newly saved Chat app can take a few minutes to appear in search.

<Callout type="info">
  One Chat app sends its messages to one HTTP endpoint URL, so it serves one Google Chat connection. To give another genie or workspace its own Google Chat presence, create a separate Chat app with its own service account.
</Callout>

## Troubleshooting

| Symptom                                                              | Check                                                                                                                                                 |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| The app doesn't appear in Chat search                                | Are you listed under **Visibility**? Is your account in the same Google Workspace organization as the Cloud project? Wait a few minutes after saving. |
| The app says it is not responding                                    | Is the **HTTP endpoint URL** in the Chat app configuration exactly the URL shown in Stacksync, including `?connection=`?                              |
| "I couldn't find a Genie currently available to handle this request" | **Access rights**: you are not a recognized user of the genie. Set the genie to Public, or check that the genie is **Active**.                        |
| People in a space see the app but can't message it                   | They are not in the Chat app's **Visibility** list.                                                                                                   |
| You can't create a key for the service account                       | An organization policy blocks service account key creation. Ask your Google Cloud admin.                                                              |