Google reviews

Once a business is connected, you can read its Google reviews and write the owner’s public reply to each one. A reply is public and visible to everyone who reads the review on Google, so MauKirim treats it as the most careful write in the product.

Three ways to do it

Where	Read reviews	Reply
Dashboard (Services → Google Business → the business)	The reviews inbox	Reply box on each review
REST API	GET /gmb/locations/{id}/reviews (scope read or gmb)	PUT …/reviews/{reviewId}/reply (scope gmb)
MCP	list_gmb_reviews	reply_gmb_review and delete_gmb_review_reply, each with confirm: true

A key with read can read reviews; only a key with the gmb scope can reply or remove a reply.

Reading reviews

curl "https://app.maukirim.com/api/v1/gmb/locations/gml_…/reviews?unreplied=1&maxRating=2" \
  -H "Authorization: Bearer mk_live_…"

{
  "ok": true,
  "cached": false,
  "averageRating": 4.3,
  "totalReviewCount": 128,
  "nextPageToken": "CAESBgj…",
  "reviews": [
    {
      "id": "AbFvOqm…",
      "reviewer": "Sari",
      "rating": 1,
      "comment": "Slow service",
      "createdAt": "2026-10-01T09:12:00Z",
      "updatedAt": "2026-10-01T09:12:00Z",
      "reply": null
    }
  ]
}

• A page holds up to pageSize reviews (default 20, at most 50). Pass nextPageToken as pageToken to get the next page; a missing token means the last page.
• unreplied=1 keeps only the reviews with no reply yet, and maxRating=2 only the ones with 2 stars or fewer. The filters apply to the page that was fetched, so a page can come back with fewer reviews than pageSize, even none, while more pages exist. Keep following nextPageToken until it is null.
• Reviews come in the order Google lists them (most recently updated first).
• averageRating and totalReviewCount describe all of the business’s reviews, not the filtered page.

The one-minute cache

A page of reviews is kept for 60 seconds per business and page, and cached: true says the answer came from it. A cached read does not touch Google and does not use your Google budget, so polling an inbox is cheap. Your own reply or removal of a reply clears the cache for that business, so you always see your own change straight away. A review a customer posts or edits can therefore take up to a minute to show.

Replying

curl -X PUT "https://app.maukirim.com/api/v1/gmb/locations/gml_…/reviews/AbFvOqm…/reply" \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-AbFvOqm-1" \
  -d '{ "comment": "Thank you, and sorry for the wait. We have added a second barista at peak hours." }'

{
  "ok": true,
  "replayed": false,
  "reply": { "comment": "Thank you, and sorry for the wait. We have added a second barista at peak hours.", "updatedAt": "2026-10-14T03:00:00Z" }
}

• A reply is 1 to 4096 characters; leading and trailing spaces are trimmed.
• One review has one reply. Replying again replaces the previous reply.
• reviewId is the id returned by the list call.

Retrying safely

A reply is a public write, so send an Idempotency-Key (8 to 128 characters, letters, digits and _ . : -). The same key with the same reply is answered with the stored result — "replayed": true — and reaches Google once. The same key with a different reply is 409 gmb_idempotency_conflict: the same key is not the same write. A failed call releases the key, so after a 429 or a reconnect you retry with the same key. Keys are remembered for 24 hours. See Idempotency for the principle.

Removing a reply

curl -X DELETE "https://app.maukirim.com/api/v1/gmb/locations/gml_…/reviews/AbFvOqm…/reply" \
  -H "Authorization: Bearer mk_live_…"

{ "ok": true }

This removes only your reply; the review stays. Repeating it changes nothing more.

What to check before you publish

• Read the review and the text you are about to publish. A reply is attributed to the business.
• Do not include personal data about the reviewer or a customer’s order.
• Do not paste review text into a prompt that has the power to reply on its own: a review is text written by a stranger, and an assistant must treat it as data, never as instructions. MauKirim’s MCP tools require an explicit confirm: true for exactly this reason (see MCP).
• A reply that Google’s policies reject can be removed by Google; MauKirim does not see that decision.

Errors you will meet

HTTP	Code	When
400	invalid_input	Empty or over-long comment; a malformed review id or Idempotency-Key; a bad maxRating or pageSize
402	gmb_plan_required	The package does not include the connector
403	api_key_scope_denied	Replying needs gmb; reading needs read or gmb
403	gmb_forbidden	Google says the connected account has no right to reply on this business
404	gmb_location_not_found	Not your business, no such business, or it left Google (removed_upstream) — the same answer for all three
409	gmb_reconnect_required	The connection needs to be reconnected by its owner
409	gmb_location_disabled	The business or connection is switched off
409	gmb_idempotency_conflict	The key was used with a different reply
429	gmb_rate_limited	No budget right now; wait Retry-After seconds
502	gmb_upstream_error	Google failed or answered something unexpected — retry later

The complete list is on Errors.