REST APIGET

Messages de la boîte de réception

Lisez les conversations de messages privés sur Facebook, Instagram, Bluesky et Mastodon, envoyez des réponses selon les règles de chaque plateforme et marquez les conversations comme traitées.

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

Renvoie les conversations de messages privés, celle qui a le dernier message en premier. Répond { conversations, total, hasMore, nextCursor }.

Clé API (jeton Bearer)

Permission:inbox.readRôles et permissions

Tous les rôles détiennent inbox.read, donc toute clé valide peut lire la boîte de réception.

Paramètres de requête

Paramètre	Taper	Description
`accountIds`	`string[]`	Uniquement ces comptes, par l'id de GET /social-accounts. Répétez la clé ou séparez les valeurs par des virgules. Jusqu'à 50
`platforms`	`PlatformType[]`	Uniquement ces plateformes. Répétez la clé ou séparez les valeurs par des virgules
`statuses`	`InboxStatus[]`	Uniquement les éléments dans ces états : UNREAD, READ ou DONE. Répétez la clé ou séparez les valeurs par des virgules
`since`	`string (ISO 8601)`	Uniquement les éléments créés sur la plateforme à partir de cette date et heure
`search`	`string`	Texte à rechercher
`limit`	`number`	Éléments par page, de 1 à 100. 25 par défaut
`cursor`	`string`	Le nextCursor de la page précédente. nextCursor vaut null sur la dernière page

Environ 10 minutes, pas en temps réel

AdaptlyPost lit chaque compte connecté toutes les 10 minutes et garde ce qu'il trouve. Les listes répondent à partir de cette copie, donc un nouveau commentaire, une mention, un message ou un avis apparaît en environ 10 minutes. POST /api/v1/inbox/refresh demande une lecture immédiate. Les événements de webhook viennent des mêmes lectures.

Canaux qui demandent une reconnexion

Tous les canaux sont ouverts à l'API. Quand une connexion n'a pas la permission de la plateforme pour un canal ou une action, y compris les permissions que la plateforme examine encore pour AdaptlyPost, GET /api/v1/inbox/summary affiche le canal en RECONNECT_REQUIRED et chaque écriture sur ce canal répond 403 inbox_reconnect_required. Un jeton expiré répond de la même façon. Demandez à l'utilisateur de reconnecter le compte dans AdaptlyPost ; réessayer ne sert à rien.

Champs d'une conversation

Champ	Description
`id`	Id de la conversation. Utilisez-le avec les endpoints ci-dessous
`accountId`	Le compte auquel appartient l'élément : son id de GET /social-accounts
`platform`	La plateforme, en PlatformType
`accountName`	Nom affiché de ce compte
`participant`	L'autre personne : id, name, username et avatarUrl
`lastMessageText`	Texte du dernier message
`lastMessageAt`	Date d'envoi du dernier message
`lastMessageIsOwn`	true quand votre compte a envoyé le dernier message
`status`	UNREAD, READ ou DONE. Une conversation passe en UNREAD quand l'autre personne écrit et que personne n'a répondu depuis, donc une réponse envoyée depuis l'application de la plateforme la laisse lue
`repliedAt`	Date de la dernière réponse de votre compte, ou null
`replyWindowEndsAt`	Facebook et Instagram : date de fermeture de la fenêtre de réponse de 24 heures, comptée à partir du dernier message lu par AdaptlyPost. null sur les autres plateformes
`maxMessageLength`	Le message le plus long que la plateforme accepte dans cette conversation
`capabilities`	canReply : false une fois la fenêtre de réponse fermée, ou quand la plateforme ne permet pas au compte d'envoyer

Lire une conversation

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

Renvoie { conversation, messages } : la conversation et les messages qu'AdaptlyPost en a lus. Un id inconnu répond 404 inbox_item_not_found. Chaque message a ces champs :

Clé API (jeton Bearer)

Permission:inbox.readRôles et permissions

Champ	Description
`id`	Id du message
`isOwn`	true quand votre compte l'a envoyé
`text`	Le texte du message
`hasAttachments`	true quand le message contient des images ou des fichiers. L'API renvoie uniquement le texte
`createdAt`	Date d'envoi

Envoyer un message

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

Envoie un message du compte dans la conversation et répond 201 { conversation, message }.

Clé API (jeton Bearer)

Permission:inbox.replyRôles et permissions

Les écritures exigent inbox.reply (Administrateur et Éditeur) et un abonnement AdaptlyPost actif. Sans abonnement, elles répondent 403 subscription_required.

Paramètres du corps

Paramètre	Taper	Description
`text`REQUIS	`string`	Le message, jusqu'à maxMessageLength de la conversation

La fenêtre de 24 heures sur Facebook et Instagram

Facebook et Instagram ne laissent une entreprise répondre que dans les 24 heures suivant le dernier message de la personne. L'envoi part quand même vers la plateforme après replyWindowEndsAt, car la personne a peut-être écrit depuis la dernière lecture ; quand la plateforme le refuse, l'appel répond 400 inbox_messaging_window_closed. Les messages Bluesky exigent un mot de passe d'application avec accès aux messages privés.

Marquer comme lu ou traité

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

Définit le statut de 100 conversations au plus et répond { conversations, unreadCount }.

Clé API (jeton Bearer)

Permission:inbox.replyRôles et permissions

Paramètres du corps

Paramètre	Taper	Description
`ids`REQUIS	`string[]`	De 1 à 100 ids issus de la liste
`status`REQUIS	`InboxStatus`	UNREAD, READ ou DONE

Refus

Un appel refusé répond { statusCode, error, code, message }. Basez-vous sur code. message explique le refus en clair.

Code	Statut	Quand, et que faire
`inbox_item_not_found`	404	L'id n'existe pas ou appartient à un autre espace de travail. Arrêtez
`inbox_action_unsupported`	400	La plateforme, ou cet élément, ne permet pas ce masquage, cette suppression ou ce j'aime. capabilities indique ce qui s'applique. Arrêtez
`inbox_reconnect_required`	403	La connexion n'a pas la permission pour ce canal ou cette action, y compris une permission encore en examen par la plateforme, ou son jeton a expiré. Demandez à l'utilisateur de reconnecter le compte dans AdaptlyPost. Ne réessayez pas
`inbox_reply_invalid`	400	Le texte est vide ou dépasse la limite. Le message indique la limite. Corrigez le texte
`inbox_messaging_window_closed`	400	Facebook ou Instagram : la fenêtre de réponse de 24 heures est passée. Arrêtez
`inbox_rate_limited`	429	La plateforme a limité le débit d'AdaptlyPost. Réessayez plus tard
`inbox_platform_error`	503	La plateforme a échoué. Réessayez plus tard
`permission_denied`	403	Le rôle de la clé n'a pas inbox.read ou inbox.reply. Ne réessayez pas
`subscription_required`	403	Une écriture sans abonnement AdaptlyPost actif. Ne réessayez pas

Lister les conversations non lues

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

Lire une conversation

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

Envoyer un message

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

Marquer une conversation comme traitée

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
}