Publish a reply on Google

What the operation does

POST /v1/reviews/{reviewId}/reply publishes a reply to a review on the location's Google profile, through the same path as a publication made in the app, then returns the answered review. It is in beta.

Publishing goes through the Google Business Profile connection that the location authorized in Ma Belle Note. Ma Belle Note is not affiliated with Google, and this feature is not part of any partnership with Google. The Google API disclosure page describes how we use that connection. No other action on Google, such as editing the profile, photos or posts, is possible through the API.

Three conditions

1. The replies:publish scope on the key, shown in the app as “Publish replies on Google”.
2. The location's authorization. It is off by default and can only be turned on in the app, location by location: Settings › Integration, API & webhooks, Google publishing tab. Only owners and admins can grant or withdraw it. It is timestamped, and withdrawing it applies from the next call. The apiReplyPublishing.enabled field of GET /v1/establishments shows its state.
3. The Idempotency-Key header, required: a replayed call never publishes twice. Without it, the API answers 400 invalid_request.

The scope alone is not enough: a key holding replies:publish receives 403 google_publishing_not_authorized for any location that has not given its authorization.

Publish a reply

curl https://api.mabellenote.com/v1/reviews/jd7f3k2m9x8w1q4z6c5v3b2n1m0l9k8j/reply \
  -H "Authorization: Bearer $MBN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-jd7f3k2m9x8w1q4z6c5v3b2n1m0l9k8j" \
  -d '{ "content": "Hello Jean, thank you for your feedback. We have talked it over with the evening team." }'

The response is the review (Review), with its reply in reply. The publication also produces a review.reply_published event with the api origin, delivered to your webhooks.

The same checks as the app

• Sensitive reply: when the review or the reply is deemed sensitive, publishing is refused with 422 unprocessable until acknowledgedSensitivity is true. Have a person read the reply before confirming.
• Pace of writes to Google: the writes to Google of a location are limited, whatever their channel. Beyond that, the API answers 429 rate_limited with Retry-After.
• Review already answered: a review that already has a reply published by Ma Belle Note answers 409 conflict.
• Traceability: every publication stays visible in the app, like any reply.

When publishing is switched off

Publishing through the API can be suspended for every account, without affecting the rest of the API. It then answers 503 google_publishing_disabled, and nothing is published. Reads, drafts and webhooks keep working.

Plan for this case in your integration: drop the reply as a draft with PUT /v1/reviews/{reviewId}/reply-draft (replies:write scope), so that it is published from the app, or try again later with the same Idempotency-Key.

Errors to handle

The errors guide describes the common format of these responses.