REST APIGET

Menzioni della inbox

Elenca i post e i commenti che menzionano i tuoi account su Facebook, Instagram, Threads, Bluesky e Mastodon, rispondi e segnali come letti.

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

Restituisce i post e i commenti che menzionano i tuoi account, dal più recente. Risponde { mentions, 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
`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 menzione

Campo	Descrizione
`id`	ID della menzione. Usalo con gli endpoint indicati sotto
`accountId`	L'account a cui appartiene l'elemento: il suo id di GET /social-accounts
`platform`	La piattaforma, come PlatformType
`accountName`	Nome visualizzato di quell'account
`platformMentionId`	L'id della piattaforma del post o commento che menziona l'account
`author`	Chi l'ha scritto: id (l'id utente della piattaforma), name, username e avatarUrl. id, username e avatarUrl possono essere null
`text`	Il testo che menziona l'account
`permalink`	Link pubblico sulla piattaforma, oppure null quando la piattaforma non ne fornisce uno
`thumbnailUrl`	Immagine del post, oppure null
`createdAt`	Quando è stato creato sulla piattaforma
`status`	UNREAD, READ o DONE. Solo AdaptlyPost conserva questo stato; la piattaforma non lo vede
`replied`	True quando il tuo account ha risposto tramite AdaptlyPost
`repliedAt`	Quando il tuo account ha risposto l'ultima volta, oppure null
`capabilities`	canReply: false quando la piattaforma non permette all'account di rispondere, come per le menzioni di Instagram
`replies`	Risposte inviate tramite AdaptlyPost, dalla più vecchia, ognuna con id, text, permalink e createdAt. Le risposte scritte nell'app della piattaforma non compaiono

Rispondi a una menzione

POSThttps://post.adaptlypost.com/post/api/v1/inbox/mentions/:id/reply

Risponde al post o commento che menziona l'account, da quell'account, e risponde 201 con la menzione. Su Mastodon la risposta mantiene la visibilità del post originale.

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. Segue il limite dei commenti della piattaforma: Threads 500, Bluesky 300, Mastodon 500 e Facebook 8000 caratteri

Segna come letto o completato

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

Imposta lo stato di un massimo di 100 menzioni e risponde { mentions, 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 le nuove menzioni

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/mentions?statuses=UNREAD&since=2026-11-01T00:00:00Z' \
  --header 'Authorization: Bearer <api-key>'

Rispondi a una menzione

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/mnt_41c7e0b2/reply \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Thanks for the shout-out!" }'

Segna una menzione come letta

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/mentions/status \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "ids": ["mnt_41c7e0b2"], "status": "READ" }'

200

{
  "mentions": [
    {
      "id": "mnt_41c7e0b2",
      "accountId": "conn_bsky_001",
      "platform": "BLUESKY",
      "accountName": "adaptlypost.com",
      "platformMentionId": "at://did:plc:4k2x.../app.bsky.feed.post/3lb2x7q",
      "author": {
        "id": "did:plc:7f3q2m",
        "name": "Marta Nowak",
        "username": "marta.bsky.social",
        "avatarUrl": null
      },
      "text": "Scheduling a month of posts with @adaptlypost.com took me 20 minutes",
      "permalink": "https://bsky.app/profile/marta.bsky.social/post/3lb2x7q",
      "thumbnailUrl": null,
      "createdAt": "2026-11-07T18:03:10.000Z",
      "status": "UNREAD",
      "replied": false,
      "repliedAt": null,
      "capabilities": { "canReply": true },
      "replies": []
    }
  ],
  "total": 3,
  "hasMore": false,
  "nextCursor": null
}