📷 Instagram & Threads (Meta)

A Graph API do Instagram não publica em conta pessoal. Para postar via API você precisa de uma conta Business (ou Creator em casos pontuais, mas o caminho seguro é Business) vinculada a uma Facebook Page. Sem esses dois requisitos, nenhum endpoint de publicação responde — sempre 400 Bad Request.

Conversão é gratuita e leva minutos no app do Instagram. O ponto crítico é o vínculo com a Page: a permissão de publicação flui da Page → Instagram, não direto na conta IG.

# Passo a passo no app do Instagram
# 1. Configurações → Conta → Mudar para conta profissional
# 2. Escolher categoria (ex: "Software", "Mídia")
# 3. Selecionar "Empresa" (NÃO "Criador de conteúdo")
# 4. Vincular Facebook Page existente OU criar uma nova

# Verificar via Graph API que o vínculo existe
curl -G "https://graph.facebook.com/v21.0/me/accounts" \
  -d "access_token=USER_TOKEN" \
  -d "fields=id,name,instagram_business_account"
# {
#   "data": [{
#     "id": "1234567890",
#     "name": "Minha Page",
#     "instagram_business_account": { "id": "17841405822304914" }
#   }]
# }

Conceitos-chave

Toda chamada à Graph API exige um Meta App registrado em developers.facebook.com. Para Instagram + Threads, o tipo correto é Business — não escolha "Consumer", as permissões necessárias nem aparecem lá.

Após criar o app, adicione os produtos: Instagram Graph API, Facebook Login for Business e, se for usar Threads, Threads API. Cada um tem suas próprias permissões e cada permissão sensível passa por App Review antes de funcionar para usuários que não sejam Admin/Dev/Tester do app.

# Roteiro de criação do app
# 1. developers.facebook.com → Meus Apps → Criar App
# 2. Tipo: "Business" (NÃO Consumer, NÃO Gaming)
# 3. Nome do app: ex. "Postiz Self-Hosted"
# 4. E-mail de contato + Business Account
# 5. Adicionar produtos:
#    - Instagram Graph API
#    - Facebook Login for Business
#    - Threads API (se aplicável)

# Os identificadores ficam em Configurações → Básico
# App ID:     1234567890123456
# App Secret: nunca-exponha-isso-no-front

# Modo do app: Development (só Admin/Dev/Tester usa)
#               → Live (após App Review aprovado)

Conceitos-chave

A Meta separa cada capacidade em uma permission scope distinta. Para um caso de uso típico de agendamento (publicar feed, ler insights, gerenciar a Page), você vai pedir 5 a 7 escopos — e cada um precisa de justificativa própria no App Review.

# Escopos OAuth para Instagram Business
# Mínimo viável para publicar feed:
pages_show_list                    # listar Pages do usuário
pages_read_engagement              # ler dados da Page
pages_manage_posts                 # publicar na Page
instagram_basic                    # ler perfil/posts IG
instagram_content_publish          # PUBLICAR no IG via API

# Insights / métricas (opcional mas comum):
instagram_manage_insights

# URL de autorização (Facebook Login for Business)
https://www.facebook.com/v21.0/dialog/oauth
  ?client_id=APP_ID
  &redirect_uri=https://seu-host/oauth/callback
  &scope=pages_show_list,pages_read_engagement,pages_manage_posts,
         instagram_basic,instagram_content_publish
  &response_type=code

# Troca code → long-lived token (server-side, usa App Secret)
curl -G "https://graph.facebook.com/v21.0/oauth/access_token" \
  -d "client_id=APP_ID" \
  -d "client_secret=APP_SECRET" \
  -d "redirect_uri=https://seu-host/oauth/callback" \
  -d "code=CODE_RECEBIDO"

Conceitos-chave

Diferente de quase todas as outras APIs, o Instagram não publica em uma chamada só. O fluxo é: (1) criar um media container com a mídia + caption → (2) aguardar processamento → (3) chamar media_publish com o ID do container. Pular o passo 2 em vídeos é o erro mais comum.

# STEP 1 — Criar container (imagem)
curl -X POST "https://graph.facebook.com/v21.0/{IG_BUSINESS_ID}/media" \
  -d "image_url=https://cdn.exemplo.com/foto.jpg" \
  -d "caption=Lançamento de hoje! #produto" \
  -d "access_token=PAGE_TOKEN"
# { "id": "17889455560051234" }   ← container_id

# STEP 2 — (Para VÍDEO/REEL) checar status até FINISHED
curl -G "https://graph.facebook.com/v21.0/17889455560051234" \
  -d "fields=status_code" \
  -d "access_token=PAGE_TOKEN"
# { "status_code": "IN_PROGRESS" }   ← aguardar
# { "status_code": "FINISHED" }      ← pronto para publicar
# { "status_code": "ERROR" }         ← falhou (ver status)

# STEP 3 — Publicar
curl -X POST "https://graph.facebook.com/v21.0/{IG_BUSINESS_ID}/media_publish" \
  -d "creation_id=17889455560051234" \
  -d "access_token=PAGE_TOKEN"
# { "id": "17912345678901234" }   ← ID do post publicado

Para carrossel, repita o STEP 1 para cada slide (com is_carousel_item=true), depois crie um container-pai do tipo CAROUSEL referenciando os filhos e só então faça o media_publish.

Conceitos-chave

Threads herda a infraestrutura do Instagram: mesmo Meta App, mesmo fluxo OAuth, mesmo modelo 2-step. A diferença é o host da API — graph.threads.net — e o conjunto de permissões próprias começando com threads_.

# Escopos Threads
threads_basic              # ler perfil
threads_content_publish    # publicar threads
threads_manage_replies     # responder
threads_read_replies       # ler respostas
threads_manage_insights    # métricas

# STEP 1 — Criar container Threads
curl -X POST "https://graph.threads.net/v1.0/{THREADS_USER_ID}/threads" \
  -d "media_type=TEXT" \
  -d "text=Primeira thread via API 🧵" \
  -d "access_token=THREADS_TOKEN"
# { "id": "1234567890" }

# STEP 2 — Publicar
curl -X POST "https://graph.threads.net/v1.0/{THREADS_USER_ID}/threads_publish" \
  -d "creation_id=1234567890" \
  -d "access_token=THREADS_TOKEN"
# { "id": "9876543210" }

# Encadear reply na mesma thread
curl -X POST "https://graph.threads.net/v1.0/{THREADS_USER_ID}/threads" \
  -d "media_type=TEXT" \
  -d "text=Segunda parte do thread..." \
  -d "reply_to_id=9876543210" \
  -d "access_token=THREADS_TOKEN"

Conceitos-chave

O App Review da Meta é o gargalo. Em média leva 4 a 6 semanas entre submissão e Advanced Access. Boa parte das rejeições é por screencast ruim ou justificativa genérica — e cada rejeição reseta o relógio.

⏱️ Timeline realista do App Review

🎥 Anatomia de um screencast aprovado

# Checklist do screencast (1 vídeo por permissão)
# Duração: 1-3 minutos por permissão

[00:00-00:10]  Tela inicial do produto + login do usuário
[00:10-00:30]  Clique em "Conectar Instagram" → tela OAuth da Meta
[00:30-00:50]  Mostrar EXATAMENTE quais permissões são pedidas
[00:50-01:30]  Demonstrar o USO REAL da permissão
                (ex: publicar um post de teste se for content_publish)
[01:30-02:00]  Mostrar o resultado (post no feed do IG)
[02:00-02:30]  Narração explicando POR QUE o usuário se beneficia

# Pontos críticos
- Áudio com narração em INGLÊS (review é global)
- Resolução mínima 720p
- Mostrar a UI do SEU app, não terminal/Postman
- Cada permissão = vídeo separado

Conceitos-chave