Wiadomości w skrzynce
Czytaj rozmowy w wiadomościach prywatnych na Facebooku, Instagramie, Bluesky i Mastodonie, wysyłaj odpowiedzi zgodnie z zasadami każdej platformy i oznaczaj rozmowy jako załatwione.
https://post.adaptlypost.com/post/api/v1/inbox/conversationsZwraca rozmowy w wiadomościach bezpośrednich, zaczynając od tej z najnowszą wiadomością. Odpowiedź: { conversations, 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 |
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 rozmowy
| Pole | Opis |
|---|---|
id | Id rozmowy. Używane w poniższych endpointach |
accountId | Konto, do którego należy element: jego id z GET /social-accounts |
platform | Platforma jako PlatformType |
accountName | Wyświetlana nazwa tego konta |
participant | Druga osoba: id, name, username i avatarUrl |
lastMessageText | Tekst najnowszej wiadomości |
lastMessageAt | Moment wysłania najnowszej wiadomości |
lastMessageIsOwn | True, gdy najnowszą wiadomość wysłało to konto |
status | UNREAD, READ lub DONE. Rozmowa staje się UNREAD, gdy druga osoba napisze i nikt od tego czasu nie odpowiedział, więc odpowiedź wysłana z aplikacji platformy pozostawia ją przeczytaną |
repliedAt | Moment ostatniej odpowiedzi konta lub null |
replyWindowEndsAt | Facebook i Instagram: moment zamknięcia 24-godzinnego okna na odpowiedź, liczony od ostatniej wiadomości odczytanej przez AdaptlyPost. null na innych platformach |
maxMessageLength | Maksymalna długość wiadomości akceptowana przez platformę w tej rozmowie |
capabilities | canReply: false po zamknięciu okna na odpowiedź lub gdy platforma nie pozwala kontu wysyłać wiadomości |
Odczyt rozmowy
https://post.adaptlypost.com/post/api/v1/inbox/conversations/:idZwraca { conversation, messages }: rozmowę i odczytane z niej przez AdaptlyPost wiadomości. Nieznane id zwraca 404 inbox_item_not_found. Każda wiadomość ma następujące pola:
| Pole | Opis |
|---|---|
id | Id wiadomości |
isOwn | True, gdy wysłało ją to konto |
text | Tekst wiadomości |
hasAttachments | True, gdy wiadomość zawiera obrazy lub pliki. API zwraca tylko tekst |
createdAt | Moment wysłania |
Wysłanie wiadomości
https://post.adaptlypost.com/post/api/v1/inbox/conversations/:id/messagesWysyła wiadomość z konta w rozmowie i zwraca 201 { conversation, message }.
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 | Wiadomość, do maxMessageLength danej rozmowy |
24-godzinne okno na Facebooku i Instagramie
Facebook i Instagram pozwalają firmie odpowiedzieć tylko w ciągu 24 godzin od ostatniej wiadomości danej osoby. Po replyWindowEndsAt wiadomość i tak trafia na platformę, ponieważ osoba mogła napisać od ostatniego odczytu; gdy platforma ją odrzuci, wywołanie zwraca 400 inbox_messaging_window_closed. Wiadomości na Bluesky wymagają hasła aplikacji z dostępem do wiadomości bezpośrednich.Oznaczanie jako przeczytane lub załatwione
https://post.adaptlypost.com/post/api/v1/inbox/conversations/statusUstawia status maksymalnie 100 rozmów i zwraca { conversations, 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/conversations?statuses=UNREAD' \
--header 'Authorization: Bearer <api-key>'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"
}
]
}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." }'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" }'{
"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
}