Aller au contenu

Inbox

Le côté Instagram d’un canal, géré à la main : ses publications et les commentaires dessous (lire, répondre, masquer, supprimer), et les messages privés (les conversations, et l’envoi d’un message). Ce qui répond tout seul, un template posé sur une publication, est décrit dans Automatisations. Ces routes n’existent pas dans upstream et ne concernent qu’Instagram, sauf les commentaires en direct : ceux d’une publication Threads (ses réponses) se lisent et se modèrent par les trois mêmes routes, voir Commentaires en direct.

GET /inbox/media/{integrationId} publications récentes
GET /inbox/stories/{integrationId} stories en ligne en ce moment
GET /inbox/comments/{integrationId}/{mediaId} commentaires en direct d’une publication
POST /inbox/comments/{commentId}/reply répondre publiquement
POST /inbox/comments/{integrationId}/{commentId}/hide masquer ou réafficher
DELETE /inbox/comments/{integrationId}/{commentId} supprimer
GET /inbox/{integrationId} lister les conversations
GET /inbox/{integrationId}/{conversationId} en lire une
POST /inbox/{integrationId}/send envoyer un message
POST /inbox/{integrationId}/poll relire l’Inbox maintenant
POST /inbox/{integrationId}/subscribe-webhook inscrire le compte au webhook de Meta

GET /inbox/media/{integrationId} liste les publications récentes. Leur id est ce qu’une pose enregistre comme mediaId. GET /inbox/stories/{integrationId} liste les stories en ligne en ce moment : la seule fenêtre où un template peut être posé sur une story.

GET /inbox/comments/{integrationId}/{mediaId} lit les commentaires d’une publication.

POST /inbox/comments/{commentId}/reply répond publiquement (201) :

{ "integrationId": "instagram-123", "message": "Envoyé, check tes DM 📬" }

message fait de 1 à 2 200 caractères, la limite d’Instagram pour un commentaire ; Threads refuse au-delà de 500.

POST /inbox/comments/{integrationId}/{commentId}/hide masque un commentaire ({ "hide": true }) ou le réaffiche ({ "hide": false }). Un commentaire masqué reste visible de son seul auteur ; la liste des commentaires en direct le marque hidden: true. DELETE /inbox/comments/{integrationId}/{commentId} le supprime sur Instagram, définitivement. Les deux répondent { "success": true } (201 pour le masquage, 200 pour la suppression).

Sur Threads, les commentaires sont les réponses à la publication, à tous les niveaux (mediaId est le releaseId de la publication) : le nom d’utilisateur est dans username, au premier niveau. Seule une réponse de premier niveau qui n’est pas la vôtre peut être masquée, et aucune ne peut être supprimée : l’API de Threads ne laisse aucune application supprimer la réponse de quelqu’un d’autre, donc DELETE répond 400 (threads does not let an app delete a comment: hide it instead).

GET /inbox/{integrationId}?box=needs_reply&limit=25

Les conversations sont lues dans la copie qu’UseNadia garde de l’Inbox (chaque message reçu ou envoyé, tenue à jour par le webhook de Meta et un rattrapage horaire), pas chez Instagram au moment de l’appel : la liste est complète, sans plafond.

Paramètre Description
box La boîte : needs_reply (par défaut, quelqu’un attend une réponse), conversations (tout sauf le full auto), auto (seule une automatisation a parlé), thanks (ce qui attend est un merci ou un emoji), organic (les personnes à qui aucune automatisation n’a jamais écrit), read (marquées lues) ou all
limit De 1 à 200, 25 par défaut ; toute valeur illisible retombe sur 25
after Le cursor de la dernière conversation de la page précédente. Absent : la première page

La réponse reste un tableau. Chaque conversation porte id (à passer à Lire une conversation), conversationId (l’ID d’Instagram, null tant qu’Instagram n’a pas nommé le fil), personId (le recipientId d’un envoi), participants, messages.data (le dernier message, pour un aperçu), inbox (la boîte et l’échéance de la fenêtre de 24 heures) et cursor. Moins de lignes que limit : c’était la dernière page.

Les conversations reviennent triées par [boîte, dernier message de la personne], ce qui empêche un message automatique de faire descendre une vraie question dans la liste. Les boîtes sont les nôtres : Instagram n’expose pas par l’API ses propres dossiers Principal / Général / Demandes.

GET /inbox/{integrationId}/{conversationId}?limit=50

conversationId est l’id rendu par la liste : l’ID de conversation d’Instagram, ou celui de la personne tant qu’Instagram n’a pas encore nommé le fil. Renvoie le fil, lu dans la même copie : les messages, les pièces jointes, les modèles à boutons envoyés par les parcours, et les réponses aux stories. Les plus récents d’abord, limit à la fois (de 1 à 200, 50 par défaut) ; messages.paging.before est là quand il en reste de plus anciens, à repasser en before.

Un message qui en cite un autre porte reply_to.mid, l’id du message cité. Instagram ne le dit qu’à l’arrivée du message : seuls les messages reçus en direct et les vôtres le portent, jamais un message repris par le rattrapage.

POST /inbox/{integrationId}/send

Champ Type Obligatoire Description
recipientId string Oui L’ID de la personne propre à Instagram (IGSID)
text string Oui De 1 à 1 000 caractères
linkUrl string Non URL absolue. Envoyée sous forme de bouton
linkButtonText string Non ≤ 20, la limite d’Instagram
replyTo string Non L’id d’un message du fil, à vous ou à la personne : le message le cite, comme « Répondre » dans Instagram
{
"recipientId": "17841400000000000",
"text": "Le voilà 👇🏻",
"linkUrl": "https://example.com/guide-malte",
"linkButtonText": "Le guide Malte"
}

POST /inbox/{integrationId}/poll lit maintenant les 25 conversations les plus récentes et transmet tout message qu’un webhook manqué aurait livré aux automatisations qui attendent cette personne (un bouton touché, un e-mail saisi). Le rattrapage horaire tient l’Inbox à jour mais ne fait pas avancer les automatisations : le webhook est le chemin normal, ceci est le rattrapage.

Il répond :

{ "conversations": 25, "handled": 1 }

conversations indique combien de conversations ont été lues chez Meta, handled combien de messages entrants ont atteint une automatisation en attente.

POST /inbox/{integrationId}/subscribe-webhook inscrit le compte aux livraisons du webhook de Meta pour les commentaires et les messages. C’est ce webhook qui fait qu’une automatisation se déclenche en quelques secondes ; sans lui, rien ne se déclenche tant qu’on ne relit pas à la main. UseNadia le fait lui-même quand un canal se connecte, quand un template est posé et à chaque redémarrage.