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

CampoTipoObligatorioDescripción
external_referencestringSíEl id del post en tu sistema (hasta 100 caracteres). Evita publicar el mismo post dos veces en la misma cuenta.
formatstringSíFormato del post. En Instagram: feed, reels o story. En Facebook: feed, reels o story.
captionstringNoLeyenda. En Instagram, hasta 2200 caracteres, 30 hashtags y 20 menciones. Los stories no llevan leyenda.
mediaarraySíLista de medios, en orden. Cada ítem tiene type y url.
media.typestringSíTipo de medio: image, video o document (documento solo en LinkedIn).
media.urlstringSíURL https:// pública que la red puede descargar (hasta 2048 caracteres).
media.alt_textstringNoTexto alternativo del medio, hasta 1000 caracteres.
media.user_tagsarrayNoSolo 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.

Relacionadas

Ver todo lo que puedes hacer con Posts

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.