REST APIGET

Posteingang: Nachrichten

Lesen Sie Unterhaltungen aus Direktnachrichten auf Facebook, Instagram, Bluesky und Mastodon, senden Sie Antworten im Rahmen der Regeln jeder Plattform und markieren Sie Unterhaltungen als erledigt.

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

Gibt Unterhaltungen aus Direktnachrichten zurück, die mit der neuesten Nachricht zuerst. Antwortet mit { conversations, total, hasMore, nextCursor }.

API-Schlüssel (Bearer-Token)

Berechtigung:inbox.readRollen und Berechtigungen

Jede Rolle hat inbox.read, daher kann jeder gültige Schlüssel den Posteingang lesen.

Abfrageparameter

Parameter	Typ	Beschreibung
`accountIds`	`string[]`	Nur diese Konten, mit der id aus GET /social-accounts. Schlüssel wiederholen oder Werte mit Kommas trennen. Bis zu 50
`platforms`	`PlatformType[]`	Nur diese Plattformen. Schlüssel wiederholen oder Werte mit Kommas trennen
`statuses`	`InboxStatus[]`	Nur Einträge in diesen Zuständen: UNREAD, READ oder DONE. Schlüssel wiederholen oder Werte mit Kommas trennen
`since`	`string (ISO 8601)`	Nur Einträge, die auf der Plattform zu oder nach diesem Zeitpunkt erstellt wurden
`search`	`string`	Suchtext
`limit`	`number`	Einträge pro Seite, 1 bis 100. Standard 25
`cursor`	`string`	Der nextCursor der vorherigen Seite. Auf der letzten Seite ist nextCursor null

Etwa 10 Minuten, nicht in Echtzeit

AdaptlyPost liest jedes verbundene Konto alle 10 Minuten und speichert, was es findet. Die Listen antworten aus dieser Kopie, daher erscheint ein neuer Kommentar, eine Erwähnung, Nachricht oder Bewertung innerhalb von etwa 10 Minuten. POST /api/v1/inbox/refresh fordert sofort einen Lesevorgang an. Webhook-Ereignisse stammen aus denselben Lesevorgängen.

Kanäle, die eine neue Verbindung brauchen

Jeder Kanal ist über die API erreichbar. Fehlt einer Verbindung die Plattform-Berechtigung für einen Kanal oder eine Aktion, auch eine, die die Plattform für AdaptlyPost noch prüft, zeigt GET /api/v1/inbox/summary den Kanal als RECONNECT_REQUIRED, und jeder Schreibzugriff darauf antwortet mit 403 inbox_reconnect_required. Ein abgelaufenes Token antwortet genauso. Bitten Sie die Person, das Konto in AdaptlyPost neu zu verbinden; ein erneuter Versuch hilft nicht.

Felder einer Unterhaltung

Feld	Beschreibung
`id`	Unterhaltungs-ID. Verwenden Sie sie mit den Endpunkten unten
`accountId`	Das Konto, zu dem der Eintrag gehört: seine id aus GET /social-accounts
`platform`	Die Plattform als PlatformType
`accountName`	Anzeigename dieses Kontos
`participant`	Die andere Person: id, name, username und avatarUrl
`lastMessageText`	Text der neuesten Nachricht
`lastMessageAt`	Wann die neueste Nachricht gesendet wurde
`lastMessageIsOwn`	True, wenn Ihr Konto die neueste Nachricht gesendet hat
`status`	UNREAD, READ oder DONE. Eine Unterhaltung wird UNREAD, wenn die andere Person schreibt und seitdem niemand geantwortet hat; eine Antwort aus der App der Plattform lässt sie also gelesen
`repliedAt`	Wann Ihr Konto zuletzt geantwortet hat, oder null
`replyWindowEndsAt`	Facebook und Instagram: wann das 24-Stunden-Antwortfenster schließt, gerechnet ab der letzten Nachricht, die AdaptlyPost gelesen hat. Auf anderen Plattformen null
`maxMessageLength`	Die längste Nachricht, die die Plattform in dieser Unterhaltung annimmt
`capabilities`	canReply: false, sobald das Antwortfenster geschlossen ist oder die Plattform das Konto nicht senden lässt

Eine Unterhaltung lesen

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

Gibt { conversation, messages } zurück: die Unterhaltung und die Nachrichten, die AdaptlyPost daraus gelesen hat. Eine unbekannte ID antwortet mit 404 inbox_item_not_found. Jede Nachricht hat diese Felder:

API-Schlüssel (Bearer-Token)

Berechtigung:inbox.readRollen und Berechtigungen

Feld	Beschreibung
`id`	Nachrichten-ID
`isOwn`	True, wenn Ihr Konto sie gesendet hat
`text`	Der Nachrichtentext
`hasAttachments`	True, wenn die Nachricht Bilder oder Dateien enthält. Die API gibt nur den Text zurück
`createdAt`	Wann sie gesendet wurde

Eine Nachricht senden

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

Sendet eine Nachricht des Kontos in der Unterhaltung und antwortet mit 201 { conversation, message }.

API-Schlüssel (Bearer-Token)

Berechtigung:inbox.replyRollen und Berechtigungen

Schreibzugriffe brauchen inbox.reply (Admin und Redakteur) und einen aktiven AdaptlyPost-Tarif. Ohne Tarif antworten sie mit 403 subscription_required.

Body-Parameter

Parameter	Typ	Beschreibung
`text`ERFORDERLICH	`string`	Die Nachricht, bis zu maxMessageLength der Unterhaltung

Das 24-Stunden-Fenster bei Facebook und Instagram

Facebook und Instagram lassen ein Unternehmen nur innerhalb von 24 Stunden nach der letzten Nachricht der Person antworten. Nach replyWindowEndsAt geht die Nachricht trotzdem an die Plattform, weil die Person seit dem letzten Lesevorgang geschrieben haben kann; lehnt die Plattform sie ab, antwortet der Aufruf mit 400 inbox_messaging_window_closed. Bluesky-Nachrichten brauchen ein App-Passwort mit Zugriff auf Direktnachrichten.

Als gelesen oder erledigt markieren

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

Setzt den Status von bis zu 100 Unterhaltungen und antwortet mit { conversations, unreadCount }.

API-Schlüssel (Bearer-Token)

Berechtigung:inbox.replyRollen und Berechtigungen

Body-Parameter

Parameter	Typ	Beschreibung
`ids`ERFORDERLICH	`string[]`	1 bis 100 IDs aus der Liste
`status`ERFORDERLICH	`InboxStatus`	UNREAD, READ oder DONE

Ablehnungen

Ein abgelehnter Aufruf antwortet mit { statusCode, error, code, message }. Werten Sie code aus. message erklärt die Ablehnung in Worten.

Code	Status	Wann, und was zu tun ist
`inbox_item_not_found`	404	Die ID existiert nicht oder gehört zu einem anderen Workspace. Abbrechen
`inbox_action_unsupported`	400	Die Plattform oder dieser Eintrag erlaubt dieses Ausblenden, Löschen oder Liken nicht. capabilities sagt, was möglich ist. Abbrechen
`inbox_reconnect_required`	403	Der Verbindung fehlt die Berechtigung für diesen Kanal oder diese Aktion, auch eine, die die Plattform noch prüft, oder ihr Token ist abgelaufen. Bitten Sie die Person, das Konto in AdaptlyPost neu zu verbinden. Nicht erneut versuchen
`inbox_reply_invalid`	400	Der Text ist leer oder zu lang. Die Meldung nennt das Limit. Text korrigieren
`inbox_messaging_window_closed`	400	Facebook oder Instagram: Das 24-Stunden-Antwortfenster ist abgelaufen. Abbrechen
`inbox_rate_limited`	429	Die Plattform hat AdaptlyPost gedrosselt. Nach einer Weile erneut versuchen
`inbox_platform_error`	503	Die Plattform ist fehlgeschlagen. Später erneut versuchen
`permission_denied`	403	Der Rolle des Schlüssels fehlt inbox.read oder inbox.reply. Nicht erneut versuchen
`subscription_required`	403	Ein Schreibzugriff ohne aktiven AdaptlyPost-Tarif. Nicht erneut versuchen

Ungelesene Unterhaltungen auflisten

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

Eine Unterhaltung lesen

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"
    }
  ]
}

Eine Nachricht senden

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

Eine Unterhaltung als erledigt markieren

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
}