REST APIGET

Messaggi della inbox

Leggi le conversazioni di messaggi diretti su Facebook, Instagram, Bluesky e Mastodon, invia risposte entro le regole di ogni piattaforma e segna le conversazioni come completate.

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

Restituisce le conversazioni di messaggi diretti, prima quella con il messaggio più recente. Risponde { conversations, 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 conversazione

Campo	Descrizione
`id`	ID della conversazione. 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
`participant`	L'altra persona: id, name, username e avatarUrl
`lastMessageText`	Testo del messaggio più recente
`lastMessageAt`	Quando è stato inviato il messaggio più recente
`lastMessageIsOwn`	True quando il messaggio più recente l'ha inviato il tuo account
`status`	UNREAD, READ o DONE. Una conversazione diventa UNREAD quando l'altra persona scrive e nessuno ha risposto da allora, quindi una risposta inviata dall'app della piattaforma la lascia letta
`repliedAt`	Quando il tuo account ha risposto l'ultima volta, oppure null
`replyWindowEndsAt`	Facebook e Instagram: quando si chiude la finestra di 24 ore per rispondere, contata dall'ultimo messaggio letto da AdaptlyPost. null sulle altre piattaforme
`maxMessageLength`	Il messaggio più lungo che la piattaforma accetta in questa conversazione
`capabilities`	canReply: false quando la finestra per rispondere si è chiusa o la piattaforma non permette all'account di inviare

Leggi una conversazione

GEThttps://post.adaptlypost.com/post/api/v1/inbox/conversations/:id

Restituisce { conversation, messages }: la conversazione e i messaggi che AdaptlyPost ne ha letto. Un id sconosciuto risponde 404 inbox_item_not_found. Ogni messaggio ha questi campi:

Chiave API (Bearer token)

Permesso:inbox.readRuoli e permessi

Campo	Descrizione
`id`	ID del messaggio
`isOwn`	True quando l'ha inviato il tuo account
`text`	Il testo del messaggio
`hasAttachments`	True quando il messaggio contiene immagini o file. L'API restituisce solo il testo
`createdAt`	Quando è stato inviato

Invia un messaggio

POSThttps://post.adaptlypost.com/post/api/v1/inbox/conversations/:id/messages

Invia un messaggio dall'account nella conversazione e risponde 201 { conversation, message }.

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`	Il messaggio, fino al maxMessageLength della conversazione

La finestra di 24 ore su Facebook e Instagram

Facebook e Instagram permettono a un'azienda di rispondere solo entro 24 ore dall'ultimo messaggio della persona. L'invio arriva comunque alla piattaforma dopo replyWindowEndsAt, perché la persona potrebbe aver scritto dopo l'ultima lettura; quando la piattaforma lo rifiuta, la chiamata risponde 400 inbox_messaging_window_closed. I messaggi di Bluesky richiedono una password per app con accesso ai messaggi diretti.

Segna come letto o completato

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

Imposta lo stato di un massimo di 100 conversazioni e risponde { conversations, 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 conversazioni non lette

curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/conversations?statuses=UNREAD' \
  --header 'Authorization: Bearer <api-key>'

Leggi una conversazione

curl --request GET \
  --url https://post.adaptlypost.com/post/api/v1/inbox/conversations/cnv_5d0e7a19 \
  --header 'Authorization: Bearer <api-key>'

200
{
  "conversation": { "id": "cnv_5d0e7a19", "...": "..." },
  "messages": [
    {
      "id": "msg_a1f20c33",
      "isOwn": false,
      "text": "Hi, do you ship to Portugal?",
      "hasAttachments": false,
      "createdAt": "2026-11-08T08:55:02.000Z"
    }
  ]
}

Invia un messaggio

curl --request POST \
  --url https://post.adaptlypost.com/post/api/v1/inbox/conversations/cnv_5d0e7a19/messages \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{ "text": "Yes, delivery to Portugal takes 3 to 5 days." }'

Segna una conversazione come completata

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

200

{
  "conversations": [
    {
      "id": "cnv_5d0e7a19",
      "accountId": "conn_fb_page_001",
      "platform": "FACEBOOK",
      "accountName": "AdaptlyPost",
      "participant": {
        "id": "7230011122233344",
        "name": "João Silva",
        "username": null,
        "avatarUrl": null
      },
      "lastMessageText": "Hi, do you ship to Portugal?",
      "lastMessageAt": "2026-11-08T08:55:02.000Z",
      "lastMessageIsOwn": false,
      "status": "UNREAD",
      "repliedAt": null,
      "replyWindowEndsAt": "2026-11-09T08:55:02.000Z",
      "maxMessageLength": 2000,
      "capabilities": { "canReply": true }
    }
  ],
  "total": 2,
  "hasMore": false,
  "nextCursor": null
}