Posts

Publier un carrousel sur Instagram via l'API

Avec format feed et plusieurs médias, Connect publie un carrousel sur le compte Instagram que votre client a connecté. Pas d'app review Meta ni de gestion de tokens : un seul appel, identique pour tous les comptes connectés.

L'appel

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "post-4410",
  "format": "feed",
  "caption": "Nova coleção no ar #verao",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/1.jpg",
      "alt_text": "Vestido azul",
      "user_tags": [
        {
          "username": "marca_parceira",
          "x": 0.5,
          "y": 0.4
        }
      ]
    },
    {
      "type": "video",
      "url": "https://cdn.example.com/2.mp4"
    },
    {
      "type": "image",
      "url": "https://cdn.example.com/3.jpg"
    }
  ]
}

Ce que vous pouvez faire

  • Publier un carrousel de 2 à 10 images et vidéos, dans l'ordre de media.
  • Mélanger images et vidéos dans le même carrousel.
  • Identifier des utilisateurs sur chaque média avec media[].user_tags, avec la position x et y sur les images.
  • Envoyer un texte alternatif pour chaque média avec alt_text.
  • Ajouter des collaborateurs, un premier commentaire et un lieu dans le bloc instagram.

Règles et limites

  • Feed accepte 1 image ou un carrousel de 2 à 10 images et vidéos. Une vidéo seule n'est pas du feed : utilisez reels.
  • La légende va jusqu'à 2200 caractères, avec au plus 30 hashtags et 20 mentions.
  • Chaque média accepte jusqu'à 20 user_tags. Sur une image, x et y (de 0 à 1) vont ensemble ou pas du tout ; sur une vidéo, sans x ni y.
  • Un carrousel d'un compte connecté via Instagram Login n'accepte pas user_tags.
  • La réponse est 202 : le post est enregistré et publié en arrière-plan. Suivez-le avec GET /posts/{uuid}.
  • external_reference est obligatoire et évite de publier deux fois le même post (409). L'en-tête Idempotency-Key rend les nouvelles tentatives sûres.

Champs principaux

ChampTypeObligatoireDescription
external_referencestringOuiL'id du post dans votre système (100 caractères max). Empêche de publier deux fois le même post sur le même compte.
formatstringOuiFormat du post. Sur Instagram : feed, reels ou story. Sur Facebook : feed, reels ou story.
captionstringNonLégende. Sur Instagram, jusqu'à 2200 caractères, 30 hashtags et 20 mentions. Les stories n'ont pas de légende.
mediaarrayOuiListe des médias, dans l'ordre. Chaque élément a type et url.
media.typestringOuiType de média : image, video ou document (document : LinkedIn uniquement).
media.urlstringOuiURL https:// publique que le réseau peut télécharger (2048 caractères max).
media.alt_textstringNonTexte alternatif du média, 1000 caractères max.
media.user_tagsarrayNonInstagram uniquement. Identifications d'utilisateurs (username, x et y), 20 max par média. Sur une image, x et y de 0 à 1 vont ensemble.

Pour qui

  • Planificateur social dans votre SaaS

    L'utilisateur compose le carrousel dans votre éditeur et votre backend le publie avec un POST /posts sur le compte Instagram qu'il a connecté.

  • Lancements e-commerce

    Générez un carrousel à partir des photos du catalogue et identifiez la marque partenaire sur chaque image au lancement.

  • Agent IA de contenu

    Un agent crée les images et la légende et publie le carrousel seul, en utilisant external_reference pour ne jamais dupliquer.

Fonctionne avec

  • Instagram Business
  • Instagram

Questions fréquentes

Combien d'images dans un carrousel ?

De 2 à 10 médias, images et vidéos, au format feed. Une seule image est aussi du feed ; une vidéo seule doit passer en reels.

Faut-il l'app review de Meta ?

Non. Le client connecte le compte une fois et vous publiez via Connect, en n'envoyant que le Bearer du merchant et le x-customer-token.

Comment savoir que le carrousel est publié ?

POST /posts répond 202 et la publication tourne en arrière-plan. Consultez GET /posts/{uuid} : le status passe par created, publishing, published ou failed, et en cas d'échec publishing.error contient code et message.

Voir aussi

Voir tout ce que vous pouvez faire avec Posts

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.