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
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| external_reference | string | Oui | L'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. |
| format | string | Oui | Format du post. Sur Instagram : feed, reels ou story. Sur Facebook : feed, reels ou story. |
| caption | string | Non | Légende. Sur Instagram, jusqu'à 2200 caractères, 30 hashtags et 20 mentions. Les stories n'ont pas de légende. |
| media | array | Oui | Liste des médias, dans l'ordre. Chaque élément a type et url. |
| media.type | string | Oui | Type de média : image, video ou document (document : LinkedIn uniquement). |
| media.url | string | Oui | URL https:// publique que le réseau peut télécharger (2048 caractères max). |
| media.alt_text | string | Non | Texte alternatif du média, 1000 caractères max. |
| media.user_tags | array | Non | Instagram 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.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
