Como Usar a API Graph do Instagram em 2026

TL;DR

A API de Gráficos do Instagram permite que desenvolvedores gerenciem contas de Negócios e Criadores do Instagram programaticamente. Ela utiliza a autenticação OAuth 2.0 do Facebook Login, endpoints baseados em GraphQL para publicação de conteúdo, insights, comentários e mensagens, com limites de taxa de 200 chamadas por hora por aplicativo. Este guia abrange a configuração de autenticação, publicação de conteúdo, recuperação de insights, gerenciamento de comentários e estratégias de integração de produção.

Introdução

O Instagram tem mais de 2 bilhões de usuários ativos mensais, com mais de 200 milhões de empresas utilizando contas comerciais do Instagram. Para desenvolvedores que criam ferramentas de gerenciamento de mídias sociais, plataformas de análise ou integrações de e-commerce, a integração com a API de Gráficos do Instagram é essencial para alcançar essa audiência massiva.

Aqui está a realidade: gerentes de mídias sociais que cuidam de mais de 10 contas perdem de 20 a 30 horas semanais em postagens manuais, respostas a comentários e compilação de análises. Uma integração sólida com a API do Instagram automatiza a publicação de conteúdo, moderação de comentários, análise de sentimento e relatórios de desempenho.

Este guia detalha todo o processo de integração da API de Gráficos do Instagram. Você aprenderá a autenticação do Facebook Login, publicação de conteúdo, insights de mídia, gerenciamento de comentários, integração de webhooks e estratégias de implantação em produção. Ao final, você terá uma integração do Instagram pronta para produção.

O Que É a API de Gráficos do Instagram?

A API de Gráficos do Instagram fornece acesso programático a contas de Negócios e Criadores do Instagram através da API de Gráficos do Facebook. A API gerencia:

• Publicação de conteúdo (fotos, vídeos, Reels, carrosséis)
• Insights e análises de mídia
• Gerenciamento de comentários e menções
• Mensagens diretas (via API de Gráficos do Instagram + Plataforma Messenger)
• Rastreamento de hashtags e menções
• Gerenciamento de Stories
• Tags de compras e produtos

Principais Recursos

Requisitos da Conta

Visão Geral da Arquitetura da API

O Instagram usa a estrutura da API de Gráficos do Facebook:

https://graph.facebook.com/v18.0/

Versões da API Comparadas

O Facebook lança novas versões trimestralmente. Sempre mire na versão estável mais recente.

Primeiros Passos: Configuração de Autenticação

Passo 1: Criar Conta de Desenvolvedor do Facebook

Antes de acessar a API:

1. Visite o Portal de Desenvolvedores do Facebook
2. Faça login com sua conta do Facebook
3. Crie um Aplicativo do Facebook (tipo: Negócios)
4. Adicione o produto Instagram Graph API

Passo 2: Vincular Conta Comercial do Instagram

Conecte o Instagram à Página do Facebook:

1. Vá para Configurações da Página do Facebook > Instagram
2. Clique em Conectar Conta
3. Faça login no Instagram e autorize
4. Confirme que a conta comercial do Instagram está vinculada

Observação: Contas pessoais do Instagram não podem usar a API de Gráficos. Converta para uma conta Comercial ou de Criador de Conteúdo nas Configurações do Instagram.

Passo 3: Obter Tokens de Acesso

Gerar Token de Acesso do Usuário:

const FB_APP_ID = process.env.FB_APP_ID;
const FB_APP_SECRET = process.env.FB_APP_SECRET;
const FB_REDIRECT_URI = process.env.FB_REDIRECT_URI;

// Build authorization URL
const getAuthUrl = (state) => {
  const params = new URLSearchParams({
    client_id: FB_APP_ID,
    redirect_uri: FB_REDIRECT_URI,
    scope: 'instagram_basic,instagram_content_publish,instagram_manage_comments,instagram_manage_insights,pages_read_engagement',
    state: state
  });

  return `https://www.facebook.com/v18.0/dialog/oauth?${params.toString()}`;
};

Permissões Necessárias

Passo 4: Trocar Token por um Token de Longa Duração

Tokens de curta duração expiram em 1 hora. Troque por um token de longa duração (60 dias):

const exchangeForLongLivedToken = async (shortLivedToken) => {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/oauth/access_token?` +
    `grant_type=fb_exchange_token&` +
    `client_id=${FB_APP_ID}&` +
    `client_secret=${FB_APP_SECRET}&` +
    `fb_exchange_token=${shortLivedToken}`
  );

  const data = await response.json();
  return data;
};

// Uso
const longLivedToken = await exchangeForLongLivedToken(shortLivedToken);
console.log(`Token expira: ${new Date(longLivedToken.expires_at * 1000)}`);

Passo 5: Obter ID da Conta Comercial do Instagram

Recupere a conta do Instagram conectada:

const getInstagramAccountId = async (pageId, accessToken) => {
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${pageId}?fields=instagram_business_account&access_token=${accessToken}`
  );

  const data = await response.json();
  return data.instagram_business_account.id;
};

// Uso
const igAccountId = await getInstagramAccountId('12345678', accessToken);
console.log(`ID da Conta do Instagram: ${igAccountId}`);

Passo 6: Fazer Chamadas Autenticadas da API

Crie um cliente de API reutilizável:

const IG_BASE_URL = 'https://graph.facebook.com/v18.0';

const instagramRequest = async (endpoint, params = {}) => {
  const url = new URL(`${IG_BASE_URL}${endpoint}`);
  url.searchParams.append('access_token', process.env.INSTAGRAM_ACCESS_TOKEN);

  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.append(key, value);
  });

  const response = await fetch(url.toString());

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Erro da API do Instagram: ${error.error.message}`);
  }

  return response.json();
};

// Uso
const account = await instagramRequest(`/me`);
console.log(`Conta do Instagram: ${account.username}`);

Publicação de Conteúdo

Publicando uma Foto

Publique uma foto no Instagram:

const publishPhoto = async (igAccountId, photoData) => {
  // Passo 1: Criar contêiner de mídia
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    image_url: photoData.imageUrl,
    caption: photoData.caption,
    location_id: photoData.locationId, // Opcional
    is_carousel_item: 'false'
  });

  const creationId = containerResponse.id;

  // Passo 2: Publicar a mídia
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// Uso
const post = await publishPhoto({
  igAccountId: '17841400000000000',
  imageUrl: 'https://example.com/image.jpg',
  caption: 'Animados para anunciar nosso novo produto! 🚀 #lançamento #inovação',
  locationId: '123456789' // Opcional
});

console.log(`ID da mídia publicada: ${post.id}`);

Publicando um Vídeo

Publique um vídeo no Instagram:

const publishVideo = async (igAccountId, videoData) => {
  // Passo 1: Criar contêiner de mídia
  const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    video_url: videoData.videoUrl,
    cover_url: videoData.coverUrl, // Miniatura opcional
    caption: videoData.caption,
    media_type: 'REELS', // ou 'VIDEO' para o feed
    share_to_feed: 'true' // Para Reels
  });

  const creationId = containerResponse.id;

  // Aguarde o processamento do vídeo (sondar até o status ser EXPIRED ou FINISHED)
  await waitForVideoProcessing(creationId);

  // Passo 2: Publicar a mídia
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

const waitForVideoProcessing = async (creationId, maxAttempts = 30) => {
  for (let i = 0; i < maxAttempts; i++) {
    const status = await instagramRequest(`/${creationId}`);

    if (status.status_code === 'FINISHED') {
      return true;
    } else if (status.status_code === 'EXPIRED') {
      throw new Error('Processamento de vídeo expirou');
    }

    await new Promise(resolve => setTimeout(resolve, 2000));
  }

  throw new Error('Tempo limite de processamento de vídeo');
};

Publicando um Carrossel (Múltiplas Imagens/Vídeos)

Publique múltiplos itens de mídia em uma única postagem:

const publishCarousel = async (igAccountId, carouselData) => {
  const children = [];

  // Passo 1: Criar cada item do carrossel
  for (const item of carouselData.items) {
    const containerResponse = await instagramRequest(`/${igAccountId}/media`, {
      method: 'POST',
      [item.type === 'video' ? 'video_url' : 'image_url']: item.url,
      caption: item.caption || '',
      is_carousel_item: 'true'
    });

    children.push(containerResponse.id);
  }

  // Passo 2: Criar contêiner de carrossel com filhos
  const carouselContainerResponse = await instagramRequest(`/${igAccountId}/media`, {
    method: 'POST',
    media_type: 'CAROUSEL',
    children: children.join(','),
    caption: carouselData.caption
  });

  const creationId = carouselContainerResponse.id;

  // Passo 3: Publicar o carrossel
  const publishResponse = await instagramRequest(`/${igAccountId}/media_publish`, {
    method: 'POST',
    creation_id: creationId
  });

  return publishResponse;
};

// Uso
const carousel = await publishCarousel('17841400000000000', {
  caption: 'Vitrine de produtos 2026',
  items: [
    { type: 'image', url: 'https://example.com/img1.jpg', caption: 'Produto 1' },
    { type: 'image', url: 'https://example.com/img2.jpg', caption: 'Produto 2' },
    { type: 'video', url: 'https://example.com/vid1.mp4', caption: 'Demonstração' }
  ]
});

Tipos de Mídia

Recuperando Mídia e Insights

Obtendo Mídia do Usuário

Recupere mídias publicadas:

const getUserMedia = async (igAccountId, limit = 25) => {
  const response = await instagramRequest(`/${igAccountId}/media`, {
    fields: 'id,caption,media_type,media_url,permalink,timestamp,like_count,comments_count',
    limit: limit.toString()
  });

  return response;
};

// Uso
const media = await getUserMedia('17841400000000000');
media.data.forEach(item => {
  console.log(`${item.media_type}: ${item.caption}`);
  console.log(`Curtidas: ${item.like_count}, Comentários: ${item.comments_count}`);
  console.log(`URL: ${item.permalink}`);
});

Obtendo Insights de Mídia

Recupere análises para mídias específicas:

const getMediaInsights = async (mediaId) => {
  const response = await instagramRequest(`/${mediaId}/insights`, {
    fields: 'impressions,reach,engagement,saved,video_views,profile_visits,follows'
  });

  return response;
};

// Uso
const insights = await getMediaInsights('17890000000000000');
insights.data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

Métricas de Insights Disponíveis

Obtendo Insights da Conta

Recupere análises agregadas da conta:

const getAccountInsights = async (igAccountId, metricNames, since = null, until = null) => {
  const params = {
    metric: metricNames.join(','),
    period: 'day'
  };

  if (since) params.since = since;
  if (until) params.until = until;

  const response = await instagramRequest(`/${igAccountId}/insights`, params);

  return response;
};

// Uso - Obter métricas dos últimos 30 dias
const accountInsights = await getAccountInsights(
  '17841400000000000',
  ['impressions', 'reach', 'profile_views', 'email_contacts', 'website_clicks'],
  '2026-02-23',
  '2026-03-25'
);

accountInsights.data.forEach(metric => {
  console.log(`${metric.name}:`);
  metric.values.forEach(value => {
    console.log(`  ${value.end_time}: ${value.value}`);
  });
});

Métricas Nível de Conta

Gerenciamento de Comentários

Obtendo Comentários

Recupere comentários em mídias:

const getMediaComments = async (mediaId, limit = 50) => {
  const response = await instagramRequest(`/${mediaId}/comments`, {
    fields: 'id,text,timestamp,username,hidden',
    limit: limit.toString()
  });

  return response;
};

// Uso
const comments = await getMediaComments('17890000000000000');
comments.data.forEach(comment => {
  console.log(`@${comment.username}: ${comment.text}`);
  console.log(`Oculto: ${comment.hidden}`);
});

Respondendo a Comentários

Publique uma resposta a um comentário:

const replyToComment = async (mediaId, commentId, replyText) => {
  const response = await instagramRequest(`/${mediaId}/comments`, {
    method: 'POST',
    response_to: commentId,
    message: replyText
  });

  return response;
};

// Uso
const reply = await replyToComment(
  '17890000000000000',
  '17900000000000000',
  'Obrigado pelo seu interesse! Verifique sua DM para mais detalhes.'
);
console.log(`Resposta publicada: ${reply.id}`);

Ocultando Comentários

Oculte comentários inapropriados:

const hideComment = async (commentId) => {
  const response = await instagramRequest(`/${commentId}`, {
    method: 'POST',
    hide: 'true'
  });

  return response;
};

// Uso
await hideComment('17900000000000000');
console.log('Comentário oculto');

Excluindo Comentários

Remova spam ou comentários inapropriados:

const deleteComment = async (commentId) => {
  await instagramRequest(`/${commentId}`, {
    method: 'DELETE'
  });

  console.log('Comentário excluído');
};

Webhooks

Configurando Webhooks

Configure webhooks para notificações em tempo real:

const subscribeToWebhooks = async (appId, pageId, accessToken) => {
  // Subscribe to Instagram events
  const response = await fetch(
    `https://graph.facebook.com/v18.0/${appId}/subscriptions`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        object: 'instagram',
        callback_url: 'https://myapp.com/webhooks/instagram',
        verify_token: process.env.WEBHOOK_VERIFY_TOKEN,
        access_token: accessToken,
        fields: ['comments', 'mentions', 'message_reactions']
      })
    }
  );

  return response.json();
};

Gerenciando Webhooks

const express = require('express');
const app = express();

// Verificar assinatura do webhook
app.get('/webhooks/instagram', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    console.log('Webhook verificado');
    res.status(200).send(challenge);
  } else {
    res.status(403).send('Verificação falhou');
  }
});

// Lidar com eventos de webhook
app.post('/webhooks/instagram', express.json(), async (req, res) => {
  const body = req.body;

  if (body.object !== 'instagram') {
    return res.status(404).send('Não encontrado');
  }

  for (const entry of body.entry) {
    const igId = entry.id;
    const changes = entry.changes;

    for (const change of changes) {
      switch (change.field) {
        case 'comments':
          await handleNewComment(change.value);
          break;
        case 'mentions':
          await handleMention(change.value);
          break;
        case 'message_reactions':
          await handleReaction(change.value);
          break;
      }
    }
  }

  res.status(200).send('OK');
});

async function handleNewComment(data) {
  console.log(`Novo comentário na mídia ${data.media_id}`);
  console.log(`De: ${data.from_id}`);
  console.log(`Texto: ${data.text}`);

  // Responder automaticamente ou moderar
  if (isSpam(data.text)) {
    await hideComment(data.id);
  }
}

Campos de Webhook

Limite de Taxa

Compreendendo os Limites de Taxa

A API de Gráficos do Instagram impõe:

• 200 chamadas por hora por aplicativo (compartilhadas entre todos os usuários)
• Descoberta de Negócios: 200 chamadas por hora por usuário
• Publicação de Conteúdo: Limitado por tipo de ação

Exceder os limites resulta em HTTP 400 com subcódigo de erro 613.

Melhores Práticas para Limite de Taxa

1. Armazene em cache as respostas - Não recupere dados inalterados
2. Agrupe requisições - Use a expansão de campo para reduzir chamadas
3. Use webhooks - Atualizações em tempo real em vez de sondagem
4. Implemente um mecanismo de espera exponencial (backoff) - Espera exponencial em erros 429

const makeRateLimitedRequest = async (endpoint, params = {}, maxRetries = 3) => {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await instagramRequest(endpoint, params);
      return response;
    } catch (error) {
      if (error.message.includes('429') && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Limite de taxa atingido. Tentando novamente em ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
};

Solução de Problemas Comuns

Problema: Token OAuth Expirado

Sintomas: Recebendo erros de “token de acesso OAuth inválido”.

Soluções:

1. Implemente a atualização do token antes do vencimento de 60 dias
2. Armazene a data de validade do token e alerte antes da expiração
3. Reautentique o usuário se o token expirar

Problema: Falha na Publicação de Mídia

Sintomas: A publicação retorna erro.

Soluções:

1. Verifique se a URL da imagem é publicamente acessível (sem necessidade de autenticação)
2. Verifique o formato da imagem (JPEG, PNG) e o tamanho (<8MB)
3. Certifique-se de que o vídeo esteja no formato MP4, <1GB, <90 segundos
4. Aguarde o processamento do vídeo antes de publicar

Problema: Insights Não Disponíveis

Sintomas: A API de Insights retorna dados vazios.

Soluções:

1. Verifique se a conta é Comercial ou de Criador (não Pessoal)
2. Aguarde 24-48 horas para que os insights sejam preenchidos
3. Verifique se a conta tem atividade suficiente

Lista de Verificação para Implantação em Produção

Antes de entrar em produção:

• [ ] Converta todas as contas de teste para Comercial/Criador
• [ ] Implemente OAuth 2.0 com tokens de longa duração
• [ ] Armazene tokens de forma segura com criptografia
• [ ] Implemente a atualização automática de tokens
• [ ] Configure endpoints de webhook com HTTPS
• [ ] Adicione limite de taxa e fila de requisições
• [ ] Implemente tratamento de erros abrangente
• [ ] Adicione logging para todas as chamadas da API
• [ ] Crie fluxos de trabalho para moderação de conteúdo
• [ ] Teste com múltiplos tipos de conta

Casos de Uso no Mundo Real

Ferramenta de Agendamento de Mídias Sociais

Uma plataforma de marketing automatiza postagens:

• Desafio: Postagem manual em mais de 50 contas de clientes
• Solução: Publicação agendada via API do Instagram
• Resultado: 80% de economia de tempo, cronograma de postagens consistente

Implementação chave:

• Calendário de conteúdo com agendamento por arrastar e soltar
• Publicação automática de fotos, vídeos, carrosséis
• Sugestões de hashtag baseadas no conteúdo

Automação de Atendimento ao Cliente

Uma marca de e-commerce automatiza respostas a comentários:

• Desafio: Resposta lenta a consultas de clientes
• Solução: Resposta automática a perguntas comuns via webhook
• Resultado: Tempo médio de resposta de 5 minutos, 90% de satisfação

Implementação chave:

• Detecção de palavras-chave (preço, disponibilidade, envio)
• Resposta automática com links de produtos
• Encaminhar consultas complexas para agentes humanos

Conclusão

A API de Gráficos do Instagram oferece acesso abrangente aos recursos de contas de Negócios e Criadores do Instagram. Principais pontos:

• Autenticação Facebook Login OAuth 2.0 com tokens de 60 dias
• A publicação de conteúdo suporta fotos, vídeos, Reels e carrosséis
• A API de Insights fornece dados de engajamento, alcance e demográficos
• Webhooks permitem monitoramento em tempo real de comentários e menções
• O limite de taxa de 200 chamadas/hora por aplicativo requer gerenciamento cuidadoso
• Apidog otimiza o teste de API e a colaboração em equipe

Seção de Perguntas Frequentes (FAQ)

Como obtenho acesso à API do Instagram?

Crie uma conta de Desenvolvedor do Facebook, crie um aplicativo de Negócios, adicione o produto Instagram Graph API e autentique via Facebook Login com as permissões necessárias.

Posso postar no Instagram automaticamente?

Sim, use a API de Publicação de Conteúdo para publicar fotos, vídeos, Reels e carrosséis em contas de Negócios e Criadores.

Quais tipos de contas do Instagram suportam a API?

Apenas contas de Negócios e Criadores têm acesso total à API. Contas pessoais têm acesso limitado ou nenhum acesso à API.

Como obtenho comentários do Instagram?

Use o endpoint de Comentários (/{media-id}/comments) para buscar comentários em mídias específicas. Webhooks fornecem notificações em tempo real.

Quais são os limites de taxa do Instagram?

A API de Gráficos do Instagram permite 200 chamadas por hora por aplicativo. Alguns endpoints têm limites adicionais por usuário.

Posso publicar Stories via API?

Sim, Stories podem ser publicados usando o mesmo fluxo de publicação de conteúdo que as postagens do feed.

Como acesso os Insights do Instagram?

Solicite a permissão instagram_manage_insights durante o OAuth. Use o endpoint de Insights para buscar métricas para mídia e conta.

Posso responder a comentários automaticamente?

Sim, use a API de Comentários para postar respostas. Muitas marcas usam isso para respostas automatizadas de atendimento ao cliente.