Respond to a Review via API

Post an owner reply to a review with the Synup API, read the push status back, and know which failures are worth a retry.

Em resumo

O que este guia realiza

Post an owner reply to a review and interpret whether the push to the platform succeeded, queued or failed.

APIs utilizadas

post/api/v1/reviews/replyResponder a uma avaliação
post/api/v1/reviews/notesAdicionar uma nota a uma avaliação

Referência

Reviews

Pré-requisitos

An API key with write access
The reviewId to reply to

Casos de uso típicos

Replying from your own review inbox
Sending an approved reply from a queue
Automating first-line replies with a human check

POST /api/v1/reviews/reply takes the review id and the reply text, posts the reply under the business's name, and pushes it to the platform the review came from. The response tells you what happened: pushed: true with status: posted when it went out now, pending when it is queued, and a retryable flag when it failed.

curl -X POST https://ai.synup.com/api/v1/reviews/reply \
  -H "Authorization: Bearer $SYNUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewId": "REVIEW_ID",
    "text": "Thank you for letting us know. I am sorry the wait was longer than it should have been. Please call us on 415 555 0142 and ask for Maria so we can make it right."
  }'

const API = "https://ai.synup.com/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.SYNUP_API_KEY}`,
  "Content-Type": "application/json",
};

async function reply(reviewId, text) {
  const res = await fetch(`${API}/reviews/reply`, {
    method: "POST",
    headers,
    body: JSON.stringify({ reviewId, text }),
  });
  if (res.status === 422) return { status: "not_respondable", error: (await res.json()).error };
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
  return (await res.json()).data; // { ok, pushed, status, externalReplyId, retryable }
}

import os
import requests

API = "https://ai.synup.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SYNUP_API_KEY']}", "Content-Type": "application/json"}

def reply(review_id, text):
    r = requests.post(f"{API}/reviews/reply", headers=HEADERS, timeout=30,
                      json={"reviewId": review_id, "text": text})
    if r.status_code == 422:
        return {"status": "not_respondable", "error": r.json()["error"]}
    r.raise_for_status()
    return r.json()["data"]

A 422 means the review cannot be replied to, almost always because it was removed from its source. A failed push with retryable: true deserves one retry after a pause; with retryable: false, stop and have someone check the platform connection.