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
| 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. |
| media | array | Sim | Lista de mídias, em ordem. Cada item tem type e url. |
| instagram.collaborators | array | Não | Até 5 usuários convidados como colaboradores, sem @. Vale em feed, reels e story. |
| 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
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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
