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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| external_reference | string | Sim | O id do post no seu sistema (até 100 caracteres). Impede publicar o mesmo post duas vezes na mesma conta. |
| format | string | Sim | Formato do post. No Instagram: feed, reels ou story. No Facebook: feed, reels ou story. |
| caption | string | Não | Legenda. No Instagram, até 2200 caracteres, 30 hashtags e 20 menções. Stories não levam legenda. |
| media | array | Sim | Lista de mídias, em ordem. Cada item tem type e url. |
| media.type | string | Sim | Tipo da mídia: image, video ou document (documento só no LinkedIn). |
| media.url | string | Sim | URL https:// pública que a rede consegue baixar (até 2048 caracteres). |
| media.alt_text | string | Não | Texto alternativo da mídia, até 1000 caracteres. |
| media.user_tags | array | Não | Só 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
