Posts

Publicar carrossel no Instagram pela API

Com format feed e várias mídias, o Connect publica um carrossel na conta Instagram que o seu cliente conectou. Você não precisa passar pelo app review da Meta nem cuidar de tokens: é uma única chamada, a mesma para todas as contas conectadas.

A chamada

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"
    }
  ]
}

O que dá para fazer

  • Publicar um carrossel de 2 a 10 imagens e vídeos, na ordem em que vierem em media.
  • Misturar imagens e vídeos no mesmo carrossel.
  • Marcar usuários em cada mídia com media[].user_tags, com posição x e y nas imagens.
  • Enviar texto alternativo em cada mídia com alt_text.
  • Acrescentar colaboradores, primeiro comentário e local no bloco instagram.

Regras e limites

  • Feed aceita 1 imagem ou um carrossel de 2 a 10 imagens e vídeos. Um vídeo sozinho não é feed: use reels.
  • A legenda vai até 2200 caracteres, com no máximo 30 hashtags e 20 menções.
  • Cada mídia aceita até 20 user_tags. Em imagem, x e y (de 0 a 1) vão juntos ou nenhum; em vídeo, sem x e y.
  • Um carrossel de uma conta conectada pelo Instagram Login não aceita user_tags.
  • A resposta é 202: o post é gravado e publicado em segundo plano. Acompanhe pelo GET /posts/{uuid}.
  • external_reference é obrigatório e evita publicar o mesmo post duas vezes (409). O header Idempotency-Key repete a chamada com segurança.

Campos principais

CampoTipoObrigatórioDescrição
external_referencestringSimO id do post no seu sistema (até 100 caracteres). Impede publicar o mesmo post duas vezes na mesma conta.
formatstringSimFormato do post. No Instagram: feed, reels ou story. No Facebook: feed, reels ou story.
captionstringNãoLegenda. No Instagram, até 2200 caracteres, 30 hashtags e 20 menções. Stories não levam legenda.
mediaarraySimLista de mídias, em ordem. Cada item tem type e url.
media.typestringSimTipo da mídia: image, video ou document (documento só no LinkedIn).
media.urlstringSimURL https:// pública que a rede consegue baixar (até 2048 caracteres).
media.alt_textstringNãoTexto alternativo da mídia, até 1000 caracteres.
media.user_tagsarrayNãoSó Instagram. Marcações de usuário (username, x e y), até 20 por mídia. Em imagem, x e y de 0 a 1 vão juntos.

Para quem

  • Agendador social dentro do seu SaaS

    O usuário monta o carrossel no seu editor e o seu backend publica com um POST /posts na conta Instagram que ele conectou.

  • Lançamentos de e-commerce

    Gere um carrossel com as fotos do catálogo e marque a marca parceira em cada imagem no momento do lançamento.

  • Agente de IA de conteúdo

    Um agente cria as imagens e a legenda e publica o carrossel sozinho, usando external_reference para nunca duplicar.

Funciona com

  • Instagram Business
  • Instagram

Perguntas frequentes

Quantas imagens cabem em um carrossel?

De 2 a 10 mídias, entre imagens e vídeos, no formato feed. Uma única imagem também é feed; um vídeo sozinho deve ir como reels.

Preciso do app review da Meta?

Não. O cliente conecta a conta uma vez e você publica pelo Connect, enviando só o Bearer do merchant e o x-customer-token.

Como sei que o carrossel foi publicado?

O POST /posts responde 202 e a publicação roda em segundo plano. Consulte GET /posts/{uuid}: o status passa por created, publishing, published ou failed, e em caso de falha publishing.error traz code e message.

Relacionadas

Ver tudo que dá para fazer em Posts

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.