Posts
Publicar stories no Instagram pela API
Com format story, o Connect publica a mídia como story na conta Instagram conectada pelo seu cliente. É a mesma chamada POST /posts dos outros formatos, para qualquer conta conectada.
A chamada
POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>
{
"external_reference": "story-77",
"format": "story",
"media": [
{
"type": "image",
"url": "https://cdn.example.com/story.jpg"
}
],
"instagram": {
"collaborators": [
"marca_parceira"
]
}
}O que dá para fazer
- Publicar um story a partir de uma URL https:// pública de imagem ou vídeo.
- Convidar colaboradores com instagram.collaborators.
- Marcar usuários na mídia com media[].user_tags.
- Usar a conta por customer_integration ou por integration_slug e source_name.
Regras e limites
- Stories não aceitam legenda: não envie caption.
- No bloco instagram, o story aceita apenas collaborators, até 5, sem @.
- Até 10 mídias por chamada, cada uma vira um story, publicadas em ordem. Todos os arquivos são verificados pela rede antes do primeiro sair, então um arquivo com problema não deixa a sequência pela metade.
- A resposta é 202: a publicação roda em segundo plano. Acompanhe pelo GET /posts/{uuid}.
- external_reference é obrigatório e Idempotency-Key evita duplicar a chamada.
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. |
| 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). |
| instagram.collaborators | array | Não | Até 5 usuários convidados como colaboradores, sem @. Vale em feed, reels e story. |
Para quem
Avisos e promoções
O seu SaaS publica um story de oferta relâmpago na conta do cliente no horário em que o usuário clicar em publicar.
Ferramenta de eventos
Gere um story com a arte do evento para cada participante e publique na conta de cada um.
Agente de IA
Um agente transforma uma notícia da marca em imagem vertical e publica como story automaticamente.
Funciona com
Instagram Business
Instagram
Perguntas frequentes
Posso colocar legenda em um story?
Não. Stories não carregam legenda; o texto deve estar na própria imagem ou vídeo.
Quais opções do bloco instagram valem no story?
Só collaborators. As demais opções são de feed e reels.
Funciona em contas instagram e instagram_business?
Sim, as duas conexões aceitam format story.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
