Inbox — Reviews

Manage Google Business Profile (GMB) reviews from the VoxBurst inbox. These endpoints let you list reviews with filtering and pagination, reply to reviews via the Google Business API, and mark reviews as read.

Review endpoints are scoped to the authenticated workspace. Only reviews from GMB accounts connected to the workspace are returned.

Base URL


https://api.voxburst.io/v1/inbox/reviews

List Reviews

GET /v1/inbox/reviews

Returns a paginated list of Google Business Profile reviews for the workspace. Each call triggers a lazy sync of new reviews from the GMB API (debounced per 5 minutes per account). Sync failures are logged and do not block the response — previously synced reviews are always returned.

Auth: Bearer token, workspace-scoped

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number (min 1)
`limit`	integer	`20`	Results per page (1–100)
`accountId`	string	—	Filter by a specific connected GMB account ID
`locationPath`	string	—	Filter by GMB location resource path (e.g. `accounts/123/locations/456`)
`rating`	integer	—	Filter by star rating (1–5)
`unreadOnly`	boolean	—	When `true`, returns only reviews where `read` is `false`
`unrepliedOnly`	boolean	—	When `true`, returns only reviews where `replied` is `false`


curl "https://api.voxburst.io/v1/inbox/reviews?limit=20&unrepliedOnly=true" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "data": [
    {
      "id": "rvw_example456",
      "workspaceId": "wsp_example123",
      "accountId": "acc_example789",
      "platformReviewId": "accounts/123456789/locations/987654321/reviews/AbCdEfGhIj",
      "reviewerName": "Jane Smith",
      "reviewerAvatarUrl": "https://lh3.googleusercontent.com/example",
      "rating": 5,
      "content": "Excellent service — the team was responsive and professional.",
      "locationPath": "accounts/123456789/locations/987654321",
      "locationName": "Acme Corp - Main St",
      "platformCreatedAt": "2026-06-22T10:00:00Z",
      "createdAt": "2026-06-22T10:00:05Z",
      "read": false,
      "replied": false,
      "repliedAt": null,
      "replyContent": null,
      "account": {
        "id": "acc_example789",
        "username": "acmecorp@gmail.com",
        "displayName": "Acme Corp",
        "platform": "GOOGLE_BUSINESS"
      }
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
}

Response Fields — Review Object

Field	Type	Description
`id`	string	VoxBurst review record ID
`workspaceId`	string	Workspace this review belongs to
`accountId`	string	ID of the connected GMB account
`platformReviewId`	string	GMB API resource name for this review
`reviewerName`	string	Display name of the reviewer
`reviewerAvatarUrl`	string \| null	URL of the reviewer’s profile photo, or `null` if unavailable
`rating`	integer	Star rating (1–5)
`content`	string \| null	Review text, or `null` if the reviewer left only a star rating
`locationPath`	string	GMB location resource path this review belongs to
`locationName`	string \| null	Display name of the business location, or `null` if not synced
`platformCreatedAt`	string	ISO 8601 timestamp when the review was posted on Google
`createdAt`	string	ISO 8601 timestamp when VoxBurst synced this review
`read`	boolean	Whether the review has been marked as read
`replied`	boolean	Whether a reply has been posted to this review
`repliedAt`	string \| null	ISO 8601 timestamp when the reply was posted, or `null`
`replyContent`	string \| null	Text of the reply that was posted, or `null`
`account`	object	Summary of the connected GMB account
`account.id`	string	Account ID
`account.username`	string	Google account username
`account.displayName`	string	Display name
`account.platform`	string	Always `"GOOGLE_BUSINESS"`

Response Fields — Meta Object

Field	Type	Description
`total`	integer	Total matching reviews across all pages
`page`	integer	Current page number
`limit`	integer	Results per page
`hasMore`	boolean	Whether additional pages exist

Get Review Stats

GET /v1/inbox/reviews/stats

Returns aggregate unread and unreplied review counts for the workspace.

Auth: Bearer token, workspace-scoped


curl "https://api.voxburst.io/v1/inbox/reviews/stats" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "unreadCount": 3,
  "unrepliedCount": 7,
  "totalCount": 12
}

Field	Type	Description
`unreadCount`	integer	Reviews where `read` is `false`
`unrepliedCount`	integer	Reviews where `replied` is `false`
`totalCount`	integer	Total reviews synced for this workspace

List Review Locations

GET /v1/inbox/reviews/locations

Returns distinct location paths from synced reviews. Use this to populate location filter dropdowns.

Auth: Bearer token, workspace-scoped


curl "https://api.voxburst.io/v1/inbox/reviews/locations" \
  -H "Authorization: Bearer eyJexample..."

Response (200)


{
  "locations": [
    {
      "locationPath": "accounts/123456789/locations/987654321",
      "locationName": "Acme Corp - Main St"
    },
    {
      "locationPath": "accounts/123456789/locations/111222333",
      "locationName": "Acme Corp - Oak Ave"
    }
  ]
}

Field	Type	Description
`locations`	object[]	Distinct locations with synced reviews
`locations[].locationPath`	string	GMB location resource path — use as `locationPath` filter on `GET /v1/inbox/reviews`
`locations[].locationName`	string	Display name of the business location

Reply to a Review

POST /v1/inbox/reviews/:id/reply

Posts a reply to a Google Business Profile review via the GMB API. On success, sets replied: true, repliedAt, replyContent, and read: true on the review record.

Auth: Bearer token, workspace-scoped

Path Parameters

Parameter	Description
`id`	VoxBurst review record ID (from the `id` field in the review object)

Request Body

Field	Type	Required	Description
`comment`	string	Yes	Reply text (1–4,096 characters)


curl -X POST "https://api.voxburst.io/v1/inbox/reviews/rvw_example456/reply" \
  -H "Authorization: Bearer eyJexample..." \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Thank you for the kind words! We look forward to seeing you again."
  }'

Response (200)

Returns the updated review object. The replied, repliedAt, replyContent, and read fields reflect the new state.


{
  "data": {
    "id": "rvw_example456",
    "workspaceId": "wsp_example123",
    "accountId": "acc_example789",
    "platformReviewId": "accounts/123456789/locations/987654321/reviews/AbCdEfGhIj",
    "reviewerName": "Jane Smith",
    "reviewerAvatarUrl": "https://lh3.googleusercontent.com/example",
    "rating": 5,
    "content": "Excellent service — the team was responsive and professional.",
    "locationPath": "accounts/123456789/locations/987654321",
    "locationName": "Acme Corp - Main St",
    "platformCreatedAt": "2026-06-22T10:00:00Z",
    "createdAt": "2026-06-22T10:00:05Z",
    "read": true,
    "replied": true,
    "repliedAt": "2026-06-27T14:30:00Z",
    "replyContent": "Thank you for the kind words! We look forward to seeing you again.",
    "account": {
      "id": "acc_example789",
      "username": "acmecorp@gmail.com",
      "displayName": "Acme Corp",
      "platform": "GOOGLE_BUSINESS"
    }
  }
}

Error Codes

HTTP	Code	Description
404	`NOT_FOUND`	Review not found or does not belong to this workspace
400	`VALIDATION_ERROR`	`comment` is empty or exceeds 4,096 characters
400	`VALIDATION_ERROR`	Associated GMB account token is missing or expired — prompt the user to reconnect the account

Mark Review as Read

PATCH /v1/inbox/reviews/:id/read

Marks a review as read. No request body is required.

Auth: Bearer token, workspace-scoped

Path Parameters

Parameter	Description
`id`	VoxBurst review record ID


curl -X PATCH "https://api.voxburst.io/v1/inbox/reviews/rvw_example456/read" \
  -H "Authorization: Bearer eyJexample..."

Response (200)

Returns the updated review object with read: true.


{
  "data": {
    "id": "rvw_example456",
    "read": true,
    "..."
  }
}

Error Codes

HTTP	Code	Description
404	`NOT_FOUND`	Review not found or does not belong to this workspace