> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Maps reviews

> Connect your Google Business Profile so every new Google Maps review of your locations opens a session your AI or team can answer. Use when setting up location review replies.

Every new Google Maps review of a location you connect opens a session in the inbox. Your AI or
your team answers it there, and the answer is published on Google Maps as the business's one public
reply to that review.

The connection runs through an OAuth client in your own Google Cloud project, signed in with a
Google account that manages your business profiles.

## Before you start

* You need permission to manage channel settings in OpenCX to connect or change the connection.
* You need a Google account that owns or manages the business profiles of your locations.
* Google reviews every request for Business Profile API access, which can take a few days. Request
  it first.

## Set up your Google Cloud project

1. In [Google Cloud](https://console.cloud.google.com/), create a project, or pick an existing one.
2. [Request Business Profile API access](https://developers.google.com/my-business/content/prereqs)
   for that project. Wait for Google to approve it.
3. Once approved, enable these three APIs in the project: **My Business Account Management API**,
   **My Business Business Information API** and **Google My Business API**.
4. Set up the **OAuth consent screen** for the project.
5. Under [Credentials](https://console.cloud.google.com/apis/credentials), create an **OAuth client
   ID** of type **Web application**. Leave this tab open: the next section gives you the redirect
   URI to add to it.

## Connect in OpenCX

In OpenCX, go to **Channels → Location reviews** and choose **Connect** on the **Google Maps** card.
The connection takes three steps.

1. **Connect your Google Business Profile client.** Copy the **Authorized redirect URI** and add it
   to the OAuth client's authorized redirect URIs in Google Cloud. Paste the client's **Client ID**
   and **Client secret**, then choose **Save and continue**.
2. **Sign in with Google.** Choose **Sign in with Google** and sign in, in the window that opens,
   with the account that manages your business profiles. Allow pop-ups for OpenCX if the window does
   not open. When the window says **Connected**, close it: the dialog moves on to choosing locations.
   If signing in fails, the dialog shows why once the window closes.
3. **Choose locations.** Tick the locations whose reviews should open sessions. Each one starts with
   its name on Google; edit it to the name your team knows the branch by. That name shows on the
   location's sessions. **Collect reviews from** is optional: reviews submitted before that date
   never open sessions. Choose **Save**.

If you close the dialog partway, **Finish connecting** on the card picks up at the step you left.

## What happens after you connect

* OpenCX checks for new reviews every few minutes, and each check looks at reviews from the last two
  days. When you first connect, those two days are collected; a large backlog arrives over the next
  few checks rather than all at once. Reviews submitted while the connection is paused or signed out
  for longer than two days are not collected.
* Reviews that already have a reply from the business on Google Maps are skipped. If a review in the
  inbox gets answered on Google Maps directly, its session shows the reply published there once
  OpenCX sees it: on the next check while the review is under two days old, otherwise when someone
  tries to reply from OpenCX.
* A review with stars but no written feedback still opens a session, so you can thank the reviewer.
* The session's side panel shows a **Google Maps review** card with the rating, the location, the
  reviewer's name, when it was submitted and whether it is still awaiting its reply. Anonymous
  reviewers show no name.
* The reviewer's contact carries the review in custom data, so a workflow can route or tag by it:

| Field | Example |
| - | - |
| **location\_review\_source** | `Google Maps` |
| **location\_review\_location** | The location's name in OpenCX |
| **location\_review\_rating** | `2 out of 5 stars` |
| **location\_review\_id** | The review's identifier on Google |

The card on **Channels → Location reviews** lists the connected locations and when OpenCX last
checked for reviews.

## Replying

A review takes exactly one public reply from the business, up to 1,000 characters. The composer
counts characters against that limit, and once the reply is published the composer locks: Google
Maps shows one reply per review, so there is nothing to follow up with. Internal comments still
work.

Every reply shows publicly under the review on Google Maps, so write it for everyone reading your
reviews, not only the reviewer.

If Google refuses a reply, the review card says why and the session stays answerable. If OpenCX
cannot tell whether Google published the reply, the card shows **Not confirmed** and the review
locks, so it is never answered twice. Check the review on Google Maps, and if the reply is missing,
answer it there.

If the AI's reply cannot be published, the session is handed to your team.

## Let the AI reply

What the AI does with a new review follows the **Location Reviews** row in
[AI Autopilot settings](https://docs.open.cx/safety/autopilot-settings.md#turn-the-ai-on-or-off-for-a-channel). The **AI
replies** card on the channel page shows the current mode and links straight to that row.

* **Autopilot on:** the AI writes and publishes the reply itself.
* **Assist mode on:** the AI drafts a reply in the session for a teammate to review and send.
  Assist mode wins when both are on, and it is on by default for Location Reviews, so new reviews
  get drafts until you turn it off.
* **Both off:** your team writes every reply.

Set the tone, how to apologise and what never to promise in
[AI instructions](https://docs.open.cx/ai-instructions/overview.md). The AI sees each review's rating and location, so
your instructions can say how to answer by location or by rating.

## Pause, switch, or disconnect

* **Pause:** turn off **Open sessions for new reviews** on the card. No new sessions open, and reviews
  already in the inbox stay answerable.
* **Change locations:** choose **Manage connection**, then tick or untick locations and rename them.
  Renaming a location changes only the reviews that arrive after it.
* **Switch Google account:** choose **Manage connection**, then **Sign in again**.
* **Change the OAuth client:** choose **Manage connection**, then **Sign in again**, then **Change
  OAuth client**. A new client pauses collection; signing in with it and saving the locations in the
  same dialog turns it back on. If you close the dialog after signing in, turn on **Open sessions for
  new reviews** once the locations are saved.
* **Disconnect:** deletes the stored credentials and the Google sign-in. New reviews stop opening
  sessions, and reviews already in the inbox can no longer be replied to.

## Troubleshooting

| Symptom | Fix |
| - | - |
| The card shows **Sign-in needed** | Choose **Finish connecting** and sign in with Google again. |
| **Could not list your locations** | Sign in with an account that owns or manages the business profiles, and check that the three APIs are enabled in the project. |
| **Sign-in did not finish** after the window closes | Read the reason under it. Signing in must finish in the same browser window that started it, with the account that manages your business profiles. |
| Google shows `redirect_uri_mismatch` during sign-in | Add the **Authorized redirect URI** from step 1 to the OAuth client exactly as shown, then sign in again. |
| No new sessions | Check the card shows **Connected**, not **Paused**, and that the location is ticked under **Manage connection**. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.