Posts
Publicar un carrusel en Instagram con la API
Con format feed y varios medios, Connect publica un carrusel en la cuenta de Instagram que tu cliente conectó. No necesitas pasar por el app review de Meta ni manejar tokens: es una sola llamada, igual para todas las cuentas conectadas.
La llamada
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"
}
]
}Qué puedes hacer
- Publicar un carrusel de 2 a 10 imágenes y videos, en el orden en que vengan en media.
- Mezclar imágenes y videos en el mismo carrusel.
- Etiquetar usuarios en cada medio con media[].user_tags, con posición x e y en las imágenes.
- Enviar texto alternativo en cada medio con alt_text.
- Añadir colaboradores, primer comentario y ubicación en el bloque instagram.
Reglas y límites
- Feed acepta 1 imagen o un carrusel de 2 a 10 imágenes y videos. Un video solo no es feed: usa reels.
- La leyenda llega hasta 2200 caracteres, con máximo 30 hashtags y 20 menciones.
- Cada medio acepta hasta 20 user_tags. En imagen, x e y (de 0 a 1) van juntos o ninguno; en video, sin x e y.
- Un carrusel de una cuenta conectada por Instagram Login no acepta user_tags.
- La respuesta es 202: el post se guarda y se publica en segundo plano. Síguelo con GET /posts/{uuid}.
- external_reference es obligatorio y evita publicar el mismo post dos veces (409). El header Idempotency-Key hace seguros los reintentos.
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| external_reference | string | Sí | El id del post en tu sistema (hasta 100 caracteres). Evita publicar el mismo post dos veces en la misma cuenta. |
| format | string | Sí | Formato del post. En Instagram: feed, reels o story. En Facebook: feed, reels o story. |
| caption | string | No | Leyenda. En Instagram, hasta 2200 caracteres, 30 hashtags y 20 menciones. Los stories no llevan leyenda. |
| media | array | Sí | Lista de medios, en orden. Cada ítem tiene type y url. |
| media.type | string | Sí | Tipo de medio: image, video o document (documento solo en LinkedIn). |
| media.url | string | Sí | URL https:// pública que la red puede descargar (hasta 2048 caracteres). |
| media.alt_text | string | No | Texto alternativo del medio, hasta 1000 caracteres. |
| media.user_tags | array | No | Solo Instagram. Etiquetas de usuario (username, x e y), hasta 20 por medio. En imagen, x e y de 0 a 1 van juntos. |
Para quién
Programador social dentro de tu SaaS
El usuario arma el carrusel en tu editor y tu backend lo publica con un POST /posts en la cuenta de Instagram que conectó.
Lanzamientos de e-commerce
Genera un carrusel con las fotos del catálogo y etiqueta a la marca aliada en cada imagen al lanzar.
Agente de IA de contenido
Un agente crea las imágenes y la leyenda y publica el carrusel solo, usando external_reference para no duplicar nunca.
Funciona con
Instagram Business
Instagram
Preguntas frecuentes
¿Cuántas imágenes caben en un carrusel?
De 2 a 10 medios, entre imágenes y videos, en el formato feed. Una sola imagen también es feed; un video solo debe ir como reels.
¿Necesito el app review de Meta?
No. El cliente conecta la cuenta una vez y tú publicas por Connect, enviando solo el Bearer del merchant y el x-customer-token.
¿Cómo sé que el carrusel se publicó?
POST /posts responde 202 y la publicación corre en segundo plano. Consulta GET /posts/{uuid}: el status pasa por created, publishing, published o failed, y si falla publishing.error trae code y message.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
