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.
https://post.adaptlypost.com/post/api/v1/inbox/reviewsZwraca opinie o lokalizacjach w Google Business Profile, od najnowszych. Odpowiedź: { reviews, total, hasMore, nextCursor }.
Każda rola ma inbox.read, więc skrzynkę może odczytać każdy ważny klucz.
Parametry zapytania
| Parametr | Typ | Opis |
|---|---|---|
accountIds | string[] | Tylko te konta, według id z GET /social-accounts. Klucz można powtórzyć lub rozdzielić wartości przecinkami. Do 50 |
platforms | PlatformType[] | Tylko te platformy. Klucz można powtórzyć lub rozdzielić wartości przecinkami |
statuses | InboxStatus[] | Tylko elementy w tych stanach: UNREAD, READ lub DONE. Klucz można powtórzyć lub rozdzielić wartości przecinkami |
since | string (ISO 8601) | Tylko elementy utworzone na platformie w tym momencie lub później |
search | string | Wyszukiwany tekst |
ratings | number[] | Tylko opinie z tymi ocenami, od 1 do 5 gwiazdek. Klucz można powtórzyć lub rozdzielić wartości przecinkami |
replied | boolean | true dla opinii z odpowiedzią, false dla opinii bez odpowiedzi |
limit | number | Elementy na stronę, od 1 do 100. Domyślnie 25 |
cursor | string | nextCursor 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
| Pole | Opis |
|---|---|
id | Id opinii. Używane w poniższych endpointach |
accountId | Konto, do którego należy element: jego id z GET /social-accounts |
platform | Zawsze GOOGLE_BUSINESS |
accountName | Wyświetlana nazwa tego konta |
platformReviewId | Id opinii w Google |
reviewer | name, avatarUrl i isAnonymous. Google ukrywa nazwy anonimowych autorów |
rating | Gwiazdki, od 1 do 5 |
text | Tekst opinii. Może być pusty, ponieważ sama ocena też jest opinią |
reply | Odpowiedź lokalizacji jako { text, updatedAt } lub null |
createdAt | Moment napisania opinii |
updatedAt | Moment ostatniej zmiany przez autora |
status | UNREAD, READ lub DONE. Nowa opinia ma status UNREAD lub DONE, jeśli ma już odpowiedź. Edytowana opinia wraca do UNREAD, chyba że ma odpowiedź |
repliedAt | Moment ostatniej odpowiedzi konta lub null |
maxReplyLength | Maksymalna długość odpowiedzi akceptowana przez Google, w bajtach UTF-8: 4096 |
capabilities | canReply: 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.
https://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/replyDodaje odpowiedź do opinii lub ją zastępuje i zwraca 200 z opinią.
Zapisy wymagają inbox.reply (Administrator i Edytor) oraz aktywnego planu AdaptlyPost. Bez planu zwracają 403 subscription_required.
Parametry treści żądania
| Parametr | Typ | Opis |
|---|---|---|
textWYMAGANE | string | Odpowiedź, do 4096 bajtów UTF-8 |
https://post.adaptlypost.com/post/api/v1/inbox/reviews/:id/replyUsuwa odpowiedź lokalizacji i zwraca 200 z opinią.
Oznaczanie jako przeczytane lub załatwione
https://post.adaptlypost.com/post/api/v1/inbox/reviews/statusUstawia status maksymalnie 100 opinii i zwraca { reviews, unreadCount }.
Parametry treści żądania
| Parametr | Typ | Opis |
|---|---|---|
idsWYMAGANE | string[] | Od 1 do 100 id z listy |
statusWYMAGANE | InboxStatus | UNREAD, READ lub DONE |
Odmowy
Odrzucone wywołanie zwraca { statusCode, error, code, message }. Logikę należy opierać na code. message opisuje odmowę słownie.
| Kod | Status | Kiedy i co zrobić |
|---|---|---|
inbox_item_not_found | 404 | Id nie istnieje lub należy do innego obszaru roboczego. Należy przerwać |
inbox_action_unsupported | 400 | Platforma lub ten element nie pozwala na ukrycie, usunięcie lub polubienie. Możliwości opisuje capabilities. Należy przerwać |
inbox_reconnect_required | 403 | Połą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_invalid | 400 | Tekst jest pusty lub przekracza limit. Komunikat podaje limit. Należy poprawić tekst |
inbox_messaging_window_closed | 400 | Facebook lub Instagram: minęło 24-godzinne okno na odpowiedź. Należy przerwać |
inbox_rate_limited | 429 | Platforma ograniczyła liczbę zapytań AdaptlyPost. Należy ponowić po pewnym czasie |
inbox_platform_error | 503 | Błąd platformy. Należy ponowić później |
permission_denied | 403 | Rola klucza nie ma inbox.read ani inbox.reply. Nie należy ponawiać |
subscription_required | 403 | Zapis bez aktywnego planu AdaptlyPost. Nie należy ponawiać |
curl --request GET \
--url 'https://post.adaptlypost.com/post/api/v1/inbox/reviews?ratings=1,2&replied=false' \
--header 'Authorization: Bearer <api-key>'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." }'curl --request DELETE \
--url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
--header 'Authorization: Bearer <api-key>'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" }'{
"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
}