# Publicações e insights do Instagram

> Publicar e agendar fotos, vídeos, carrosséis, Reels e Stories, e ler os insights da conta e dos posts.

Esta página vale para contas do Instagram já [conectadas](/connect/instagram/). Publicar exige a permissão `instagram_content_publish`; insights exigem `instagram_manage_insights`. Sem elas, a rota responde `403` [`instagram_scope_missing`](/errors#instagram_scope_missing) até você reconectar a conta.

## Publicar

A Meta não agenda publicações: o Messajo guarda o pedido e publica na hora marcada. No painel, use **Publicações → Nova publicação**; pela API, `POST /v1/publications`.

![Tela de nova publicação com conta, tipo, mídia, legenda com contadores e a escolha entre publicar agora e agendar](../../../assets/screenshots/publication-composer-pt-BR.png)

### Tipos

| `type` | Mídia | Observação |
|---|---|---|
| `photo` | 1 imagem | Post no feed |
| `video` | 1 vídeo | Vira Reels com `share_to_feed` sempre ligado (a Meta descontinuou vídeo comum no feed) |
| `reel` | 1 vídeo | Aceita capa (`cover`), `thumb_offset_ms`, `share_to_feed` e `audio_name` |
| `carousel` | 2 a 20 itens, imagem e/ou vídeo | Um contêiner por item e um para o carrossel |
| `story` | 1 imagem ou vídeo | Sem legenda visível |

Cada item vem por `media_id` (arquivo enviado em `POST /v1/media` com `purpose=publication`) ou por `url` pública. Também aceitam `alt_text`, `user_tags`, `collaborators` (até 3) e `location_id`.

### Limites

| Regra | Valor |
|---|---|
| Legenda | até 2.200 caracteres, 30 hashtags e 20 menções (`@`) |
| Imagem | **JPEG**, até 8 MiB. PNG e WebP enviados por `media_id` são convertidos para JPEG antes de publicar |
| Vídeo | MP4 ou MOV, até 300 MiB (Stories até 100 MiB) |
| Agendamento | de agora até 75 dias à frente |
| Cota da Meta | 100 publicações por conta em 24 h móveis (`GET /v1/connections/{id}/publishing-limit`) |

Fora dessas regras, a resposta é `422` [`validation_failed`](/errors#validation_failed) com o campo em `details`.

### URL pública

A Meta **baixa** a mídia pela URL: ela precisa ser acessível da internet. O `media_id` vira um link assinado do armazenamento S3 válido por 24 h.URL de rede privada é recusada com `422` [`media_url_not_public`](/errors#media_url_not_public).

### Agendamento e status

`scheduled_at` vazio (ou dentro do próximo minuto) publica agora; no futuro, a publicação fica **Agendada** e uma tarefa roda na hora certa, com uma varredura a cada minuto como rede de segurança. Enquanto está `scheduled` ou `queued`, dá para editar (`PATCH /v1/publications/{id}`) ou cancelar (`POST /v1/publications/{id}/cancel`); depois disso, [`publication_not_editable`](/errors#publication_not_editable).

| `status` | O que acontece |
|---|---|
| `scheduled` | Esperando a hora marcada |
| `queued` | Na fila para publicar. Com a cota da Meta cheia, tenta de novo a cada hora; passadas 24 h do horário, falha com [`publishing_limit_reached`](/errors#publishing_limit_reached) |
| `creating` | Criando os contêineres de mídia na Meta |
| `processing` | A Meta está processando a mídia. Mais de 30 min falha com [`container_timeout`](/errors#container_timeout) |
| `publishing` | Pedindo a publicação |
| `published` | Publicado, com `external_media_id` e `permalink` |
| `failed` | Falhou; o motivo vem em `error` (código do Messajo + código e status da Meta) |
| `canceled` | Cancelada por você |

Saem os eventos `publication.published` e `publication.failed` ([catálogo](/webhooks/events/#catálogo)).

### Nunca repete às cegas

Se a Meta não responde ao pedido de publicação (timeout, `5xx`), não dá para saber se o post saiu. O Messajo **não** publica de novo: consulta o status do contêiner na Meta. Se já foi publicado, marca `published` e procura o post; se o contêiner está pronto e não publicado, repete uma vez; se ainda processa, espera. Se publicou mas o post não foi encontrado, fica `published` sem `external_media_id`, e essa publicação não aceita `retry`. Uma publicação `failed` comum pode ser repetida com `POST /v1/publications/{id}/retry`, que cria contêineres novos.

## Insights

No painel, **Insights** mostra a conta escolhida em 7, 28 ou 90 dias: alcance, visualizações, contas engajadas, interações, seguidores ganhos e perdidos, a série diária e o público do mês. Abaixo, os posts com as métricas de cada um.

![Tela de insights com os cartões de alcance e engajamento, o gráfico diário e a tabela de posts](../../../assets/screenshots/insights-pt-BR.png)

| Rota `/v1` | O que devolve |
|---|---|
| `GET /connections/{id}/insights` | Métricas da conta: `reach`, `views`, `accounts_engaged`, `total_interactions`, `likes`, `comments`, `shares`, `saves`, `replies`, `reposts`, `follows_and_unfollows`, `profile_links_taps` (por dia) e `follower_demographics`, `engaged_audience_demographics` |
| `GET /connections/{id}/posts` · `/posts/{post_id}` | Posts da conta, com curtidas e comentários |
| `GET /connections/{id}/posts/{post_id}/insights` | Métricas do post, conforme o tipo (feed, Reels ou story) |

- **Atraso:** a Meta pode levar até 48 h para atualizar os números. O Messajo guarda cada consulta por 15 min.
- `impressions` foi descontinuada pela Meta e é recusada com `validation_failed`.
- Item de carrossel não tem insights próprios: `422` [`insights_not_available`](/errors#insights_not_available). Story com audiência abaixo de 5 pessoas também.
- **Stories:** a métrica de um story some 24 h depois de ele sair do ar e o webhook de insights de story está a confirmar no login unificado. Por isso o Messajo tira um retrato dos stories ativos de hora em hora; o insight de um story vencido vem desse retrato, com `source: "snapshot"` e o horário em `captured_at` (no painel, "capturado às …").
