REST APIGET

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.

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

Zwraca rozmowy w wiadomościach bezpośrednich, zaczynając od tej z najnowszą wiadomością. Odpowiedź: { conversations, total, hasMore, nextCursor }.

Klucz API (token Bearer)
Uprawnienie:inbox.readRole i uprawnienia

Każda rola ma inbox.read, więc skrzynkę może odczytać każdy ważny klucz.

Parametry zapytania

ParametrTypOpis
accountIdsstring[]Tylko te konta, według id z GET /social-accounts. Klucz można powtórzyć lub rozdzielić wartości przecinkami. Do 50
platformsPlatformType[]Tylko te platformy. Klucz można powtórzyć lub rozdzielić wartości przecinkami
statusesInboxStatus[]Tylko elementy w tych stanach: UNREAD, READ lub DONE. Klucz można powtórzyć lub rozdzielić wartości przecinkami
sincestring (ISO 8601)Tylko elementy utworzone na platformie w tym momencie lub później
searchstringWyszukiwany tekst
limitnumberElementy na stronę, od 1 do 100. Domyślnie 25
cursorstringnextCursor 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

PoleOpis
idId rozmowy. Używane w poniższych endpointach
accountIdKonto, do którego należy element: jego id z GET /social-accounts
platformPlatforma jako PlatformType
accountNameWyświetlana nazwa tego konta
participantDruga osoba: id, name, username i avatarUrl
lastMessageTextTekst najnowszej wiadomości
lastMessageAtMoment wysłania najnowszej wiadomości
lastMessageIsOwnTrue, gdy najnowszą wiadomość wysłało to konto
statusUNREAD, 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ą
repliedAtMoment ostatniej odpowiedzi konta lub null
replyWindowEndsAtFacebook i Instagram: moment zamknięcia 24-godzinnego okna na odpowiedź, liczony od ostatniej wiadomości odczytanej przez AdaptlyPost. null na innych platformach
maxMessageLengthMaksymalna długość wiadomości akceptowana przez platformę w tej rozmowie
capabilitiescanReply: false po zamknięciu okna na odpowiedź lub gdy platforma nie pozwala kontu wysyłać wiadomości

Odczyt rozmowy

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

Zwraca { 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:

Klucz API (token Bearer)
Uprawnienie:inbox.readRole i uprawnienia
PoleOpis
idId wiadomości
isOwnTrue, gdy wysłało ją to konto
textTekst wiadomości
hasAttachmentsTrue, gdy wiadomość zawiera obrazy lub pliki. API zwraca tylko tekst
createdAtMoment wysłania

Wysłanie wiadomości

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

Wysyła wiadomość z konta w rozmowie i zwraca 201 { conversation, message }.

Klucz API (token Bearer)
Uprawnienie:inbox.replyRole i uprawnienia

Zapisy wymagają inbox.reply (Administrator i Edytor) oraz aktywnego planu AdaptlyPost. Bez planu zwracają 403 subscription_required.

Parametry treści żądania

ParametrTypOpis
textWYMAGANEstringWiadomość, 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

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

Ustawia status maksymalnie 100 rozmów i zwraca { conversations, unreadCount }.

Klucz API (token Bearer)
Uprawnienie:inbox.replyRole i uprawnienia

Parametry treści żądania

ParametrTypOpis
idsWYMAGANEstring[]Od 1 do 100 id z listy
statusWYMAGANEInboxStatusUNREAD, READ lub DONE

Odmowy

Odrzucone wywołanie zwraca { statusCode, error, code, message }. Logikę należy opierać na code. message opisuje odmowę słownie.

KodStatusKiedy i co zrobić
inbox_item_not_found404Id nie istnieje lub należy do innego obszaru roboczego. Należy przerwać
inbox_action_unsupported400Platforma lub ten element nie pozwala na ukrycie, usunięcie lub polubienie. Możliwości opisuje capabilities. Należy przerwać
inbox_reconnect_required403Połą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_invalid400Tekst jest pusty lub przekracza limit. Komunikat podaje limit. Należy poprawić tekst
inbox_messaging_window_closed400Facebook lub Instagram: minęło 24-godzinne okno na odpowiedź. Należy przerwać
inbox_rate_limited429Platforma ograniczyła liczbę zapytań AdaptlyPost. Należy ponowić po pewnym czasie
inbox_platform_error503Błąd platformy. Należy ponowić później
permission_denied403Rola klucza nie ma inbox.read ani inbox.reply. Nie należy ponawiać
subscription_required403Zapis bez aktywnego planu AdaptlyPost. Nie należy ponawiać
Lista nieprzeczytanych rozmów
curl --request GET \
  --url 'https://post.adaptlypost.com/post/api/v1/inbox/conversations?statuses=UNREAD' \
  --header 'Authorization: Bearer <api-key>'
Odczyt rozmowy
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"
    }
  ]
}
Wysłanie wiadomości
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." }'
Oznaczenie rozmowy jako załatwionej
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
}