Inbox

When you finish this page you can list the reviews of a Google Business Profile (googlebusiness) location, reply to one and read reviews across several locations in one request. You need a connected Google Business Profile account (accountId). Reviews are the only inbox surface on this platform: Google exposes no DMs, and posts have no comments.

Step 1: list reviews

Call GET /v1/inbox/reviews?platform=googlebusiness (List reviews). Filter with accountId, minRating, maxRating and hasReply, and page with cursor. Each review's id is Google's full resource name, so it also encodes the location.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: reviews } = await zernio.reviews.listInboxReviews({
  query: { platform: 'googlebusiness', accountId: '66b2e19d8c3f5a7e9d0b1c2d', hasReply: false }
});

console.log(reviews.data);

Response (200):

{
  "status": "success",
  "data": [
    {
      "id": "accounts/123456789/locations/12345678901234567890/reviews/AIe9_BGx1234567890",
      "platform": "googlebusiness",
      "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
      "locationId": "12345678901234567890",
      "locationName": "Joe's Pizza Downtown",
      "reviewer": { "id": null, "name": "John Smith", "profileImage": "https://lh3.googleusercontent.com/a/..." },
      "rating": 5,
      "text": "Great service and friendly staff. Highly recommend.",
      "created": "2026-08-15T10:30:00Z",
      "hasReply": false,
      "hasPhotos": false,
      "photoCount": 0,
      "photos": [],
      "reply": null,
      "reviewUrl": null
    }
  ],
  "pagination": { "hasMore": false, "nextCursor": null }
}

Step 2: reply to a review

Call POST /v1/inbox/reviews/{reviewId}/reply with accountId and message (Reply to review); reviewId is the review's id from Step 1, URL-encoded because it contains slashes. Google keeps one owner reply per review, so a second call overwrites the first, including a reply someone typed by hand in the Business Profile UI; read the review before retrying. Send an Idempotency-Key header to make a retry after a timeout safe. Review replies never count as outbound messages.

const { data: replied } = await zernio.reviews.replyToInboxReview({
  path: { reviewId: 'accounts/123456789/locations/12345678901234567890/reviews/AIe9_BGx1234567890' },
  body: {
    accountId: '66b2e19d8c3f5a7e9d0b1c2d',
    message: 'Thank you, John. See you again soon.'
  }
});

console.log(replied.reply.created);

Response (200):

{
  "status": "success",
  "reply": {
    "id": "AIe9_BGx1234567890",
    "text": "Thank you, John. See you again soon.",
    "created": "2026-08-16T08:00:00Z"
  },
  "platform": "googlebusiness"
}

DELETE /v1/inbox/reviews/{reviewId}/reply removes the reply and leaves the review in place. New and edited reviews arrive on the review.new and review.updated webhooks.

Step 3: read reviews across locations

Call POST /v1/accounts/{accountId}/gmb-reviews/batch with up to 50 locationNames (Batch get reviews). Each name is accounts/{googleAccountId}/locations/{locationId}, built from the accountId and id values of List locations. The response is a flat locationReviews array where each item carries the location name it belongs to plus the review; Google orders it newest first, so stop paging once you cross your date window. Aggregate averageRating and totalReviewCount are not returned here; Get reviews has them for one location.

const { data: batch } = await zernio.gmbreviews.batchGetGoogleBusinessReviews({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' },
  body: {
    locationNames: [
      'accounts/123456789/locations/12345678901234567890',
      'accounts/123456789/locations/22345678901234567890'
    ],
    pageSize: 50
  }
});

for (const item of batch.locationReviews) {
  console.log(item.name, item.review.starRating, item.review.comment);
}

Response (200):

{
  "success": true,
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "locationReviews": [
    {
      "name": "accounts/123456789/locations/22345678901234567890",
      "review": {
        "reviewId": "AIe9_BGx0987654321",
        "name": "accounts/123456789/locations/22345678901234567890/reviews/AIe9_BGx0987654321",
        "starRating": "FOUR",
        "comment": "Good experience overall.",
        "reviewer": { "displayName": "Anonymous", "isAnonymous": true },
        "createTime": "2026-08-10T14:20:00Z",
        "updateTime": "2026-08-10T14:20:00Z",
        "reviewReply": null
      }
    }
  ],
  "nextPageToken": "CiAKHAoUMTIzNDU2Nzg5"
}

If it fails

A 401 with code token_invalid on any reviews endpoint means Google revoked or expired the account's token:

{
  "error": "Access token invalid. Please reconnect your Google Business Profile account.",
  "code": "token_invalid"
}

Reconnect the account through GET /v1/connect/googlebusiness, then retry. An empty data array for a location that shows reviews on Google is a different problem: the location is not verified or not yet matched to its Maps place, which verification reports as hasVoiceOfMerchant: false. Error handling covers the envelope.

Related

• List reviews and Reply to review: the inbox API.
• Get reviews: one location with averageRating and totalReviewCount.
• Inbox webhooks: the review.new and review.updated payloads.
• Multi-Location Posting: where the location names come from.