Posts

Adicionar colaboradores a posts do Instagram pela API

Com instagram.collaborators, o post sai com outras contas convidadas como colaboradoras. Funciona em feed, reels e story, pela mesma chamada POST /posts, sem app review.

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-5120",
  "format": "feed",
  "caption": "Parceria nova",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/parceria.jpg"
    }
  ],
  "instagram": {
    "collaborators": [
      "marca_parceira",
      "criador_oficial"
    ]
  }
}

O que dá para fazer

  • Convidar colaboradores em feed, reels e story.
  • Enviar os usernames sem @: o Connect remove o @ inicial e usa minúsculas.
  • Combinar com marcações de usuário em media[].user_tags nas mídias.
  • Usar as contas instagram e instagram_business.

Regras e limites

  • No máximo 5 colaboradores por post.
  • Cada username tem até 30 caracteres: letras, números, ponto e underscore, sem @.
  • No story, collaborators é a única opção do bloco instagram.
  • A resposta é 202: o post é publicado em segundo plano. Acompanhe pelo GET /posts/{uuid}.
  • external_reference é obrigatório e Idempotency-Key evita duplicar.

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.
mediaarraySimLista de mídias, em ordem. Cada item tem type e url.
instagram.collaboratorsarrayNãoAté 5 usuários convidados como colaboradores, sem @. Vale em feed, reels e story.
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

  • Posts de parceria

    Marcas e criadores publicam juntos: o SaaS envia o post pela conta da marca e convida o criador como colaborador.

  • Agências

    A agência publica pela conta do cliente e convida a conta da própria agência como colaboradora.

  • Agente de IA de influenciadores

    Um agente monta o post de campanha e convida automaticamente os perfis da lista de parceiros.

Funciona com

  • Instagram Business
  • Instagram

Perguntas frequentes

Quantos colaboradores posso convidar?

Até 5 por post, em feed, reels ou story.

Preciso enviar o @ no username?

Não. Envie sem @; se vier com @ inicial, ele é removido e o valor vai para minúsculas.

Colaborador é o mesmo que marcar um usuário?

Não. Colaboradores ficam no bloco instagram; marcações de usuário ficam em media[].user_tags.

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.