REST APIGET

Recensioni della inbox

Elenca le recensioni di Google Business Profile delle tue sedi per valutazione e stato della risposta, aggiungi o sostituisci la risposta, eliminala e segna le recensioni come lette.

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

Restituisce le recensioni di Google Business Profile delle tue sedi, dalla più recente. Risponde { reviews, total, hasMore, nextCursor }.

Chiave API (Bearer token)

Permesso:inbox.readRuoli e permessi

Ogni ruolo ha inbox.read, quindi qualsiasi chiave valida può leggere la inbox.

Parametri della query

Parametro	Tipo	Descrizione
`accountIds`	`string[]`	Solo questi account, tramite l'id di GET /social-accounts. Ripeti la chiave o separa i valori con virgole. Fino a 50
`platforms`	`PlatformType[]`	Solo queste piattaforme. Ripeti la chiave o separa i valori con virgole
`statuses`	`InboxStatus[]`	Solo elementi in questi stati: UNREAD, READ o DONE. Ripeti la chiave o separa i valori con virgole
`since`	`string (ISO 8601)`	Solo elementi creati sulla piattaforma in questa data e ora o dopo
`search`	`string`	Testo da cercare
`ratings`	`number[]`	Solo le recensioni con queste valutazioni in stelle, da 1 a 5. Ripeti la chiave o separa i valori con virgole
`replied`	`boolean`	true per le recensioni con una risposta, false per quelle senza
`limit`	`number`	Elementi per pagina, da 1 a 100. Predefinito 25
`cursor`	`string`	Il nextCursor della pagina precedente. nextCursor è null nell'ultima pagina

Circa 10 minuti, non in tempo reale

AdaptlyPost legge ogni account collegato ogni 10 minuti e conserva ciò che trova. Gli elenchi rispondono da quella copia, quindi un nuovo commento, menzione, messaggio o recensione compare entro circa 10 minuti. POST /api/v1/inbox/refresh chiede una lettura subito. Gli eventi webhook nascono dalle stesse letture.

Canali che richiedono di ricollegare l'account

Ogni canale è accessibile dall'API. Quando a un collegamento manca il permesso della piattaforma per un canale o un'azione, compresi i permessi che la piattaforma sta ancora esaminando per AdaptlyPost, GET /api/v1/inbox/summary mostra il canale come RECONNECT_REQUIRED e ogni scrittura su di esso risponde 403 inbox_reconnect_required. Un token scaduto risponde allo stesso modo. Chiedi all'utente di ricollegare l'account in AdaptlyPost; riprovare non serve.

Campi della recensione

Campo	Descrizione
`id`	ID della recensione. Usalo con gli endpoint indicati sotto
`accountId`	L'account a cui appartiene l'elemento: il suo id di GET /social-accounts
`platform`	Sempre GOOGLE_BUSINESS
`accountName`	Nome visualizzato di quell'account
`platformReviewId`	L'id di Google della recensione
`reviewer`	name, avatarUrl e isAnonymous. Google nasconde il nome di chi recensisce in forma anonima
`rating`	Stelle, da 1 a 5
`text`	Il testo della recensione. Può essere vuoto, perché anche una sola valutazione è una recensione
`reply`	La risposta della sede come { text, updatedAt }, oppure null
`createdAt`	Quando è stata scritta la recensione
`updatedAt`	Quando l'autore l'ha modificata l'ultima volta
`status`	UNREAD, READ o DONE. Una nuova recensione parte come UNREAD, oppure DONE quando ha già una risposta. Una recensione modificata torna UNREAD a meno che non abbia una risposta
`repliedAt`	Quando il tuo account ha risposto l'ultima volta, oppure null
`maxReplyLength`	La risposta più lunga che Google accetta, in byte UTF-8: 4096
`capabilities`	canReply: false quando l'account va ricollegato

Rispondi a una recensione

Google permette una sola risposta per recensione. Inviare una risposta sostituisce quella già presente, che sia stata scritta in AdaptlyPost o su Google.

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

Aggiunge la risposta alla recensione, o la sostituisce, e risponde 200 con la recensione.

Chiave API (Bearer token)

Permesso:inbox.replyRuoli e permessi

Le scritture richiedono inbox.reply (Amministratore ed Editor) e un piano AdaptlyPost attivo. Senza il piano rispondono 403 subscription_required.

Parametri del corpo

Parametro	Tipo	Descrizione
`text`OBBLIGATORIO	`string`	La risposta, fino a 4096 byte UTF-8

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

Rimuove la risposta della sede e risponde 200 con la recensione.

Chiave API (Bearer token)

Permesso:inbox.replyRuoli e permessi

Segna come letto o completato

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

Imposta lo stato di un massimo di 100 recensioni e risponde { reviews, unreadCount }.

Chiave API (Bearer token)

Permesso:inbox.replyRuoli e permessi

Parametri del corpo

Parametro	Tipo	Descrizione
`ids`OBBLIGATORIO	`string[]`	Da 1 a 100 id presi dall'elenco
`status`OBBLIGATORIO	`InboxStatus`	UNREAD, READ o DONE

Rifiuti

Una chiamata rifiutata risponde { statusCode, error, code, message }. Decidi in base a code. message spiega il rifiuto a parole.

Codice	Stato	Quando, e cosa fare
`inbox_item_not_found`	404	L'id non esiste o appartiene a un altro workspace. Fermati
`inbox_action_unsupported`	400	La piattaforma, o questo elemento, non permette di nascondere, eliminare o mettere mi piace. capabilities indica cosa vale. Fermati
`inbox_reconnect_required`	403	Al collegamento manca il permesso per questo canale o azione, anche se è ancora in revisione presso la piattaforma, oppure il suo token è scaduto. Chiedi all'utente di ricollegare l'account in AdaptlyPost. Non riprovare
`inbox_reply_invalid`	400	Il testo è vuoto o supera il limite. Il messaggio indica il limite. Correggi il testo
`inbox_messaging_window_closed`	400	Facebook o Instagram: la finestra di 24 ore per rispondere è chiusa. Fermati
`inbox_rate_limited`	429	La piattaforma ha limitato le richieste di AdaptlyPost. Riprova tra un po'
`inbox_platform_error`	503	La piattaforma ha avuto un errore. Riprova più tardi
`permission_denied`	403	Il ruolo della chiave non ha inbox.read o inbox.reply. Non riprovare
`subscription_required`	403	Una scrittura senza un piano AdaptlyPost attivo. Non riprovare

Elenca i voti bassi senza risposta

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/reviews?ratings=1,2&replied=false' \
  --header 'Authorization: Bearer <api-key>'

Rispondi a una recensione

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." }'

Elimina una risposta

curl --request DELETE \
  --url https://post.adaptlypost.com/post/api/v1/inbox/reviews/rvw_0c93b4d1/reply \
  --header 'Authorization: Bearer <api-key>'

Segna una recensione come letta

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
}