REST APIGET

Opinie w skrzynce

Wyświetl opinie o swoich lokalizacjach w Google Business Profile według oceny i stanu odpowiedzi, dodaj lub zastąp odpowiedź, usuń ją i oznaczaj opinie jako przeczytane.

GEThttps://post.adaptlypost.com/post/api/v1/inbox/reviews

Zwraca opinie o lokalizacjach w Google Business Profile, od najnowszych. Odpowiedź: { reviews, total, hasMore, nextCursor }.

Klucz API (token Bearer)
Uprawnienie:inbox.readRole i uprawnienia

Każda rola ma inbox.read, więc skrzynkę może odczytać każdy ważny klucz.

Parametry zapytania

ParametrTypOpis
accountIdsstring[]Tylko te konta, według id z GET /social-accounts. Klucz można powtórzyć lub rozdzielić wartości przecinkami. Do 50
platformsPlatformType[]Tylko te platformy. Klucz można powtórzyć lub rozdzielić wartości przecinkami
statusesInboxStatus[]Tylko elementy w tych stanach: UNREAD, READ lub DONE. Klucz można powtórzyć lub rozdzielić wartości przecinkami
sincestring (ISO 8601)Tylko elementy utworzone na platformie w tym momencie lub później
searchstringWyszukiwany tekst
ratingsnumber[]Tylko opinie z tymi ocenami, od 1 do 5 gwiazdek. Klucz można powtórzyć lub rozdzielić wartości przecinkami
repliedbooleantrue dla opinii z odpowiedzią, false dla opinii bez odpowiedzi
limitnumberElementy na stronę, od 1 do 100. Domyślnie 25
cursorstringnextCursor poprzedniej strony. Na ostatniej stronie nextCursor ma wartość null

Około 10 minut, nie w czasie rzeczywistym

AdaptlyPost odczytuje każde połączone konto co 10 minut i zapisuje znalezione dane. Listy korzystają z tej kopii, więc nowy komentarz, wzmianka, wiadomość lub opinia pojawia się w ciągu około 10 minut. POST /api/v1/inbox/refresh zleca odczyt od razu. Zdarzenia webhooków pochodzą z tych samych odczytów.

Kanały wymagające ponownego połączenia

Każdy kanał jest dostępny przez API. Gdy połączeniu brakuje uprawnienia platformy do kanału lub działania, także takiego, które platforma nadal weryfikuje dla AdaptlyPost, GET /api/v1/inbox/summary pokazuje kanał jako RECONNECT_REQUIRED, a każdy zapis w nim zwraca 403 inbox_reconnect_required. Tak samo jest przy wygasłym tokenie. Należy poprosić użytkownika o ponowne połączenie konta w AdaptlyPost; ponawianie nie pomoże.

Pola opinii

PoleOpis
idId opinii. Używane w poniższych endpointach
accountIdKonto, do którego należy element: jego id z GET /social-accounts
platformZawsze GOOGLE_BUSINESS
accountNameWyświetlana nazwa tego konta
platformReviewIdId opinii w Google
reviewername, avatarUrl i isAnonymous. Google ukrywa nazwy anonimowych autorów
ratingGwiazdki, od 1 do 5
textTekst opinii. Może być pusty, ponieważ sama ocena też jest opinią
replyOdpowiedź lokalizacji jako { text, updatedAt } lub null
createdAtMoment napisania opinii
updatedAtMoment ostatniej zmiany przez autora
statusUNREAD, READ lub DONE. Nowa opinia ma status UNREAD lub DONE, jeśli ma już odpowiedź. Edytowana opinia wraca do UNREAD, chyba że ma odpowiedź
repliedAtMoment ostatniej odpowiedzi konta lub null
maxReplyLengthMaksymalna długość odpowiedzi akceptowana przez Google, w bajtach UTF-8: 4096
capabilitiescanReply: false, gdy konto wymaga ponownego połączenia

Odpowiedź na opinię

Google pozwala na jedną odpowiedź na opinię. Wysłanie odpowiedzi zastępuje istniejącą, niezależnie od tego, czy napisano ją w AdaptlyPost, czy w Google.

PUThttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Dodaje odpowiedź do opinii lub ją zastępuje i zwraca 200 z opinią.

Klucz API (token Bearer)
Uprawnienie:inbox.replyRole i uprawnienia

Zapisy wymagają inbox.reply (Administrator i Edytor) oraz aktywnego planu AdaptlyPost. Bez planu zwracają 403 subscription_required.

Parametry treści żądania

ParametrTypOpis
textWYMAGANEstringOdpowiedź, do 4096 bajtów UTF-8
DELETEhttps://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/reply

Usuwa odpowiedź lokalizacji i zwraca 200 z opinią.

Klucz API (token Bearer)
Uprawnienie:inbox.replyRole i uprawnienia

Oznaczanie jako przeczytane lub załatwione

POSThttps://post.adaptlypost.com/post/api/v1/inbox/reviews/status

Ustawia status maksymalnie 100 opinii i zwraca { reviews, unreadCount }.

Klucz API (token Bearer)
Uprawnienie:inbox.replyRole i uprawnienia

Parametry treści żądania

ParametrTypOpis
idsWYMAGANEstring[]Od 1 do 100 id z listy
statusWYMAGANEInboxStatusUNREAD, READ lub DONE

Odmowy

Odrzucone wywołanie zwraca { statusCode, error, code, message }. Logikę należy opierać na code. message opisuje odmowę słownie.

KodStatusKiedy i co zrobić
inbox_item_not_found404Id nie istnieje lub należy do innego obszaru roboczego. Należy przerwać
inbox_action_unsupported400Platforma lub ten element nie pozwala na ukrycie, usunięcie lub polubienie. Możliwości opisuje capabilities. Należy przerwać
inbox_reconnect_required403Połączeniu brakuje uprawnienia do tego kanału lub działania, także będącego w trakcie weryfikacji platformy, albo token wygasł. Należy poprosić użytkownika o ponowne połączenie konta w AdaptlyPost. Nie należy ponawiać
inbox_reply_invalid400Tekst jest pusty lub przekracza limit. Komunikat podaje limit. Należy poprawić tekst
inbox_messaging_window_closed400Facebook lub Instagram: minęło 24-godzinne okno na odpowiedź. Należy przerwać
inbox_rate_limited429Platforma ograniczyła liczbę zapytań AdaptlyPost. Należy ponowić po pewnym czasie
inbox_platform_error503Błąd platformy. Należy ponowić później
permission_denied403Rola klucza nie ma inbox.read ani inbox.reply. Nie należy ponawiać
subscription_required403Zapis bez aktywnego planu AdaptlyPost. Nie należy ponawiać
Lista niskich ocen bez odpowiedzi
curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/reviews?ratings=1,2&replied=false' \
  --header 'Authorization: Bearer <api-key>'
Odpowiedź na opinię
curl --request PUT \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Sorry about the wait, Piotr. We have added a second barista on weekends." }'
Usunięcie odpowiedzi
curl --request DELETE \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>'
Oznaczenie opinii jako przeczytanej
curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/status \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["rvw_0c93b4d1"], "status": "READ" }'
200
{
  "reviews": [
    {
      "id": "rvw_0c93b4d1",
      "accountId": "conn_gbp_001",
      "platform": "GOOGLE_BUSINESS",
      "accountName": "AdaptlyPost Kraków",
      "platformReviewId": "AbFvOqm4x2...",
      "reviewer": {
        "name": "Piotr K.",
        "avatarUrl": null,
        "isAnonymous": false
      },
      "rating": 2,
      "text": "Good coffee, but a 20 minute wait on Saturday.",
      "reply": null,
      "createdAt": "2026-11-07T12:30:00.000Z",
      "updatedAt": "2026-11-07T12:30:00.000Z",
      "status": "UNREAD",
      "repliedAt": null,
      "maxReplyLength": 4096,
      "capabilities": { "canReply": true }
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextCursor": null
}