Instagram

Visão geral

Instagram é uma plataforma de mídia social para compartilhamento de fotos, vídeos e stories. A integração no SquadOS suporta exclusivamente contas Business e Creator — contas pessoais não são compatíveis. Com ela, seus agentes podem publicar posts, responder comentários, enviar mensagens diretas e consultar métricas de engajamento via Instagram Graph API.

• Documentação na Composio: docs.composio.dev/toolkits/instagram

Autenticação

Esta ferramenta utiliza OAuth 2.0 (OAUTH2) para conectar.

Você vai precisar autorizar o acesso à sua conta Instagram Business ou Creator via OAuth gerenciado pela Composio.

Campo	Obrigatório	Descrição
OAuth 2.0	Sim	Autorização de acesso à conta Instagram Business ou Creator via fluxo OAuth gerenciado pela Composio.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por Instagram.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde autoriza o acesso (OAuth) à sua conta Instagram Business ou Creator.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Criar container de carrossel

INSTAGRAM_CREATE_CAROUSEL_CONTAINER

Cria um rascunho de post carrossel com múltiplas imagens/vídeos antes de publicar. O Instagram exige que carrosséis tenham entre 2 e 10 itens de mídia. Os creation_ids dos containers expiram em menos de 24 horas, portanto publique logo após a criação.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
caption	string	Não	Legenda do post carrossel (máximo 2.200 caracteres). Máximo de 30 hashtags.
children	array	Não	Lista de creation_ids filhos (itens de imagem/vídeo). O total de itens do carrossel em todas as fontes deve estar entre 2 e 10. Todos os containers filhos devem estar em status FINISHED antes do uso; itens pendentes ou com falha bloqueiam a criação do carrossel. A ordem dos IDs determina a sequência dos slides.
ig_user_id	string	Sim	ID da conta Instagram Business. Deve ser uma conta Business ou Creator; contas pessoais são rejeitadas.
child_image_urls	array	Não	Lista de URLs de imagens a incluir como filhos do carrossel. As imagens devem atender aos requisitos do Instagram: formato JPEG, proporção entre 4:5 (0,8) e 1,91:1, largura entre 320–1440px, tamanho máximo 8 MB. As URLs devem ser acessíveis publicamente pelos servidores do Instagram. O total de itens deve estar entre 2 e 10. Devem ser URLs HTTPS diretas (não páginas HTML, redirecionamentos ou links genéricos do Google Drive).
child_video_urls	array	Não	Lista de URLs de vídeos a incluir como filhos do carrossel. Os vídeos devem atender aos requisitos do Instagram: formato MP4 ou MOV, proporção entre 4:5 (0,8) e 1,91:1, duração de 3–60 segundos, tamanho máximo 4 GB. As URLs devem ser acessíveis publicamente pelos servidores do Instagram. O total de itens deve estar entre 2 e 10.
child_image_files	array	Não	Lista de arquivos de imagem locais a incluir como filhos do carrossel. Mesmos requisitos de formato que child_image_urls. O total de itens deve estar entre 2 e 10.
child_video_files	array	Não	Lista de arquivos de vídeo locais a incluir como filhos do carrossel. Mesmos requisitos de formato que child_video_urls. O total de itens deve estar entre 2 e 10.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar container de mídia (Descontinuada)

INSTAGRAM_CREATE_MEDIA_CONTAINER

DESCONTINUADA: Use INSTAGRAM_POST_IG_USER_MEDIA em vez disso. Cria um container de rascunho de mídia para fotos/vídeos/reels antes de publicar. Apenas contas Business/Creator — contas pessoais não são suportadas. Retorna um ID de container (data.id ou data.creation_id) usado como creation_id para publicação. Os containers expiram em ~24 horas — recrie containers obsoletos em vez de reutilizar IDs antigos. Antes de publicar via INSTAGRAM_CREATE_POST, chame INSTAGRAM_GET_POST_STATUS e aguarde o status FINISHED — publicar antes de FINISHED dispara o erro 9007. Cada creation_id é de uso único; se a criação falhar (status_code=‘ERROR’), corrija os parâmetros de mídia e recrie via esta ferramenta em vez de tentar publicar novamente com o ID com falha.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
caption	string	Não	Texto da legenda do post. Máximo de 2.200 caracteres. Limite de hashtags: 30 por post. Limite de menções: 20 @menções máximo.
cover_url	string	Não	URL da imagem de capa para vídeos. Para vídeos de feed (content_type=‘video’), se image_url não for fornecida, ela será usada como miniatura obrigatória. Para reels, é opcional.
image_url	string	Não	URL pública da imagem. Deve ser um link direto para o arquivo de imagem bruto — sem redirecionamentos, autenticação ou wrappers HTML. Deve ser acessível publicamente pelos crawlers da Meta. Formatos suportados: JPG, PNG (WebP não suportado). Máx. 8 MB, mín. 320px de largura, proporção 4:5 a 1,91:1. Para vídeos de feed (content_type=‘video’), este parâmetro é obrigatório como miniatura.
video_url	string	Não	URL pública do vídeo. Deve ser um link direto para o arquivo de vídeo bruto — sem redirecionamentos, autenticação ou wrappers HTML. Deve ser acessível publicamente pelos crawlers da Meta. Formatos suportados: MP4, MOV. Máx. 100 MB para vídeos de feed, máx. 1 GB para IGTV, mín. 3 segundos de duração.
ig_user_id	string	Não	ID da conta Instagram Business (string numérica como ‘17841400008460056’). Opcional — padrão para o usuário autenticado atual. Não passe IDs de conexão Composio (iniciados com ‘ca_’) ou outros identificadores de autenticação.
media_type	string	Não	Substituição explícita do tipo de mídia (IMAGE, REELS ou CAROUSEL). Se não fornecido, o tipo é inferido automaticamente: IMAGE para image_url, REELS para video_url. O tipo VIDEO foi descontinuado em 9 de novembro de 2023 e será convertido automaticamente para REELS.
content_type	string (“photo” | “video” | “reel” | “carousel_item”)	Não	O que você deseja postar: ‘photo’, ‘video’, ‘reel’ ou ‘carousel_item’ (para rascunhos de carrossel).
is_carousel_item	boolean	Não	Parâmetro legado para marcar a mídia como item de carrossel. Prefira usar content_type='carousel_item'. Ao criar itens de carrossel, forneça image_url ou video_url.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Criar post (Descontinuada)

INSTAGRAM_CREATE_POST

DESCONTINUADA: Use INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH em vez disso. Publica um container de mídia rascunhado no Instagram (etapa final de publicação). Os posts ficam imediatamente visíveis ao público após o sucesso — confirme a intenção antes de chamar. Requer conta Business ou Creator com escopos de publicação; escopos ausentes retornam o código de erro do Graph 10. Após criar um container de mídia, o Instagram pode precisar de tempo para processar a mídia antes de publicar. Se chamado cedo demais, o código de erro 9007 é retornado. Esta ação faz novas tentativas automaticamente com backoff exponencial (até ~44 segundos no total). Para vídeos grandes, use INSTAGRAM_GET_POST_STATUS para aguardar status_code=‘FINISHED’ antes de chamar; para carrosséis, todos os containers filhos devem atingir individualmente o status FINISHED primeiro.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_user_id	string	Sim	ID da conta Instagram Business. Deve ser uma string numérica (ex.: ‘25162441193410545’). Contas pessoais e IDs mal configurados são rejeitados.
creation_id	string	Sim	O ID do container de mídia retornado no campo ‘id’ de INSTAGRAM_CREATE_MEDIA_CONTAINER ou INSTAGRAM_CREATE_CAROUSEL_CONTAINER. Normalmente uma string numérica longa como ‘17895695668004550’. Não use strings de data e hora — essas são campos não relacionados nas respostas do Instagram. Os containers expiram após ~24 horas; recrie via INSTAGRAM_CREATE_MEDIA_CONTAINER se obsoleto.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir comentário

INSTAGRAM_DELETE_COMMENT

Exclui um comentário em uma mídia do Instagram. Use quando precisar remover um comentário criado pela sua conta Instagram Business ou Creator. Nota: você só pode excluir comentários criados pela sua conta — não é possível excluir comentários de outros usuários, exceto se estiverem em sua própria mídia.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_comment_id	string	Sim	O identificador único do comentário do Instagram a ser excluído. Deve ser um comentário criado pela sua conta Instagram Business ou Creator.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Excluir perfil do Messenger

INSTAGRAM_DELETE_MESSENGER_PROFILE

Exclui configurações do perfil do Messenger de uma conta Instagram. Use quando precisar remover ice breakers, menu persistente, mensagens de saudação ou outras configurações de mensagens do perfil do Messenger.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	array	Sim	Array de propriedades do perfil do Messenger a serem excluídas. Valores válidos: ice_breakers, persistent_menu, get_started, greeting, account_linking_url, whitelisted_domains. Apenas os campos especificados serão removidos do perfil do Messenger.
ig_user_id	string	Sim	ID da conta Instagram Business cujas configurações do perfil do Messenger serão excluídas.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter conversa

INSTAGRAM_GET_CONVERSATION

Obtém detalhes sobre uma conversa de DM específica do Instagram (participantes, etc.). Requer uma conta Business ou Creator com permissões de mensagens do Instagram; contas pessoais retornarão erros de permissão. Mensagens recém-enviadas/recebidas podem levar alguns segundos para aparecer nos resultados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
conversation_id	string	Sim	O identificador único do thread de conversa do Instagram. O thread já deve existir; DMs de primeiro contato não podem ser iniciados via API — uma primeira mensagem manual deve ser enviada antes que um conversation_id esteja disponível. Normalmente uma string codificada em base64 obtida das ações list_conversations ou list_all_conversations. Não deve estar vazio ou conter apenas espaços em branco.
graph_api_version	string	Não	A versão da Graph API a ser utilizada (ex.: ‘v21.0’). Padrão: ‘v21.0’.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter respostas de comentário do IG

INSTAGRAM_GET_IG_COMMENT_REPLIES

Obtém respostas a um comentário específico do Instagram. Retorna uma lista de respostas com detalhes como texto, nome de usuário, timestamp e contagem de curtidas. Use quando precisar recuperar comentários filhos (respostas) de um comentário pai específico.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação avançada — obter respostas após este cursor.
limit	integer	Não	Número de respostas a retornar por página (máx. 100).
before	string	Não	Cursor para paginação retroativa — obter respostas antes deste cursor.
fields	string	Não	Lista de campos separados por vírgula a retornar. Campos disponíveis: id, text, username, timestamp, like_count, hidden, from, media, parent_id, replies, legacy_instagram_comment_id.
ig_comment_id	string	Sim	ID do comentário do Instagram para obter as respostas.
graph_api_version	string	Não	Versão da Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter mídia do Instagram

INSTAGRAM_GET_IG_MEDIA

Obtém um objeto de mídia publicado do Instagram (foto, vídeo, story, reel ou carrossel). Use quando precisar recuperar informações detalhadas sobre um post específico do Instagram, incluindo métricas de engajamento, legenda, URLs de mídia e metadados. NOTA: Esta ação é apenas para mídia publicada. Para IDs de container não publicados (de INSTAGRAM_CREATE_MEDIA_CONTAINER), use INSTAGRAM_GET_POST_STATUS para verificar o status.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Lista de campos separados por vírgula a retornar. Padrão inclui campos úteis como id, caption, media_type, media_url, permalink, timestamp, like_count, comments_count e media_product_type. Para campos aninhados, use a sintaxe ‘children{media_url,media_type}’. Campos NÃO suportados (causarão erros): tagged_users, user_tags, location, filter_name, latitude, longitude, text. Use ‘caption’ em vez de ‘text’ para a legenda. Métricas de insights devem ser obtidas via INSTAGRAM_GET_IG_MEDIA_INSIGHTS.
ig_media_id	string	Sim	O ID numérico do objeto de mídia do Instagram da Graph API (ex.: ‘17858625294504375’). Deve ser uma string numérica, NÃO um shortcode alfanumérico de URLs do instagram.com/p/. Obtenha IDs numéricos via INSTAGRAM_GET_IG_USER_MEDIA ou endpoints similares. Para IDs de container não publicados, use INSTAGRAM_GET_POST_STATUS.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter filhos de mídia do IG

INSTAGRAM_GET_IG_MEDIA_CHILDREN

Obtém objetos de mídia (imagens/vídeos) que são filhos de um post carrossel/álbum do Instagram. Use quando precisar recuperar itens de mídia individuais de um post em carrossel. Nota: mídias filhas de carrossel não suportam consultas de insights — para análises, consulte métricas no nível do carrossel pai.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Lista de campos separados por vírgula a retornar para cada item de mídia filho. Campos disponíveis: id, caption, media_type, media_url, username, timestamp, permalink, thumbnail_url, ig_id, owner, shortcode, is_comment_enabled, comments_count, like_count.
ig_media_id	string	Sim	O ID de um post de mídia CAROUSEL_ALBUM (não um ID de usuário). Deve ser o ID de mídia de um post carrossel/álbum, tipicamente obtido chamando a ação ‘Get IG User Media’ e filtrando por media_type=‘CAROUSEL_ALBUM’. IDs de mídia são strings numéricas (17 dígitos) que identificam posts específicos do Instagram, distintas de IDs de usuário/conta.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter comentários de mídia do IG

INSTAGRAM_GET_IG_MEDIA_COMMENTS

Recupera comentários em um objeto de mídia do Instagram. Use quando precisar buscar comentários de um post, foto, vídeo ou carrossel específico do Instagram pertencente à conta Business/Creator conectada. Suporta paginação baseada em cursor para navegar por grandes listas de comentários. Um array data vazio na resposta indica que o post não tem comentários e não é um erro. Buscar em muitos objetos de mídia em massa pode disparar limites de taxa da API.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação avançada. Use o valor do cursor do campo paging.cursors.after da resposta anterior.
limit	integer	Não	Número de comentários a retornar por página (normalmente 50–100).
before	string	Não	Cursor para paginação retroativa. Use o valor do cursor do campo paging.cursors.before da resposta anterior.
fields	string	Não	Lista de campos separados por vírgula a recuperar para cada comentário. Campos disponíveis: id, text, username, timestamp, like_count, replies, from, hidden, media, parent_id, user.
ig_media_id	string	Sim	O ID do objeto de mídia do Instagram (post/foto/vídeo/álbum) do qual recuperar comentários. Deve ser um ID de mídia, não um ID de usuário. IDs de mídia podem ser obtidos de endpoints como GET /ig-user-id/media. A mídia deve pertencer à conta Business/Creator conectada.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter insights de mídia do IG

INSTAGRAM_GET_IG_MEDIA_INSIGHTS

Obtém insights e métricas de objetos de mídia do Instagram (fotos, vídeos, reels, álbuns carrossel). Use quando precisar recuperar dados de desempenho como visualizações, alcance, curtidas, comentários, salvamentos e compartilhamentos de mídias específicas. Nota: dados de insights estão disponíveis apenas para mídias publicadas nos últimos 2 anos, e a conta deve ter pelo menos 1.000 seguidores. Requer conta Business ou Creator; perfis pessoais do Instagram não são suportados.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
metric	array	Sim	Lista de métricas a recuperar. Deve ser fornecida como array de strings, ex.: [‘reach’, ‘saved’, ‘likes’]. MÉTRICAS COMUNS: views, reach, saved, likes, comments, shares, total_interactions. MÉTRICAS DE REELS: ig_reels_video_view_total_time, ig_reels_avg_watch_time, reels_skip_rate, facebook_views, crossposted_views. MÉTRICAS DE STORIES: replies, navigation, follows, profile_visits. MÉTRICAS DESCONTINUADAS (serão filtradas): ‘impressions’, ‘plays’, ‘video_views’ (use ‘views’), ‘taps_forward’, ‘taps_back’, ‘exits’ (use ‘navigation’). NOMES INVÁLIDOS: ‘clicks’ e ‘engagement’ não são métricas válidas.
period	string	Não	O período de tempo para agregação de métricas. Para insights de mídia, ‘lifetime’ é o padrão e tipicamente a única opção disponível.
ig_media_id	string	Sim	O ID do objeto de mídia do Instagram (foto, vídeo, reel, álbum carrossel) para o qual recuperar insights.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter limite de publicação de conteúdo do usuário IG

INSTAGRAM_GET_IG_USER_CONTENT_PUBLISHING_LIMIT

Obtém o uso atual de publicação de conteúdo de uma conta Instagram Business. Use para monitorar o uso da cota antes de publicar; exceder o limite diário bloqueia novos posts até a cota ser redefinida. IMPORTANTE: Este endpoint requer um ID de usuário IG (Instagram Business Account ID), NÃO um IGSID (Instagram Scoped ID). Polls excessivos deste endpoint podem disparar o erro da Graph 613 (limite de taxa); espaçe as chamadas por alguns segundos.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Lista de campos separados por vírgula a retornar. Campos disponíveis: quota_usage, config. Padrão: ‘quota_usage,config’.
ig_user_id	string	Não	ID de usuário IG (IG User ID) da conta Instagram Business. Deve ser um ID de usuário IG válido, NÃO um IGSID (usado para mensagens). Padrão: ‘me’ para o usuário atual.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter mídia ao vivo do usuário IG

INSTAGRAM_GET_IG_USER_LIVE_MEDIA

Obtém objetos de mídia ao vivo durante uma transmissão ativa do Instagram. Retorna o ID da mídia do vídeo ao vivo e metadados quando uma transmissão ao vivo está em andamento em uma conta Instagram Business ou Creator. Use para monitorar transmissões ao vivo ativas e acessar dados de engajamento em tempo real.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Lista de campos separados por vírgula a retornar para o objeto de mídia ao vivo. Campos disponíveis: id, media_type, media_url, timestamp, permalink. Padrão: todos os campos disponíveis.
ig_user_id	string	Não	ID da conta Instagram Business ou Creator (opcional, padrão: ‘me’ para o usuário atual). Deve ser uma conta com uma transmissão ao vivo ativa.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter mídia do usuário IG

INSTAGRAM_GET_IG_USER_MEDIA

Obtém a coleção de mídia de um usuário do Instagram (posts, fotos, vídeos, reels, carrosséis). Use quando precisar recuperar todas as mídias publicadas por uma conta Instagram Business ou Creator com suporte a paginação e filtragem por período.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação avançada — recuperar mídias após este cursor. O valor vem de paging.cursors.after na resposta; parar na primeira página omite silenciosamente posts mais antigos.
limit	integer	Não	Número de itens de mídia a retornar por página (padrão: 25, máx.: 100).
since	integer	Não	Timestamp Unix — filtrar resultados para mídias criadas após este momento. Se tanto ‘since’ quanto ‘until’ forem fornecidos, ‘since’ deve ser menor que ‘until’.
until	integer	Não	Timestamp Unix — filtrar resultados para mídias criadas antes deste momento. Se tanto ‘since’ quanto ‘until’ forem fornecidos, ‘since’ deve ser menor que ‘until’.
before	string	Não	Cursor para paginação retroativa — recuperar mídias antes deste cursor.
fields	string	Não	Lista de campos separados por vírgula a retornar. Campos disponíveis: id, caption, media_type, media_url, permalink, thumbnail_url, timestamp, username, comments_count, like_count, ig_id, is_comment_enabled, owner, shortcode, media_product_type, video_title, children{media_url,media_type,thumbnail_url}. Reels aparecem como media_type=VIDEO e media_product_type=REELS.
ig_user_id	string	Sim	ID da conta Instagram Business ou Creator. Use ‘me’ para o usuário autenticado, ou forneça o ID numérico da Graph API do Instagram (tipicamente 17 dígitos). Se você fornecer um ID de Página do Facebook, ele será convertido automaticamente para o ID da conta Instagram Business.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada (ex.: ‘v21.0’).
auto_resolve_fb_page_id	boolean	Não	Se verdadeiro e o ig_user_id fornecido falhar, tenta automaticamente resolvê-lo como um ID de Página do Facebook recuperando o campo instagram_business_account.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter stories do usuário IG

INSTAGRAM_GET_IG_USER_STORIES

Obtém objetos de mídia de story ativos para uma conta Instagram Business ou Creator. Os stories são recuperados via o endpoint /stories. Retorna stories que estão ativos no momento dentro da janela de 24 horas. Use para recuperar conteúdo de story, metadados e métricas de engajamento para monitoramento ou análise.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação para obter a próxima página de resultados. Use o cursor ‘after’ do objeto de paginação da resposta anterior.
limit	integer	Não	Número de stories a retornar por página para paginação. Se não especificado, retorna todos os stories ativos.
before	string	Não	Cursor para paginação para obter a página anterior de resultados. Use o cursor ‘before’ do objeto de paginação da resposta anterior.
fields	string	Não	Lista de campos separados por vírgula a retornar para cada story. Campos disponíveis: id, caption, comments_count, ig_id, is_comment_enabled, like_count, media_type, media_url, owner, permalink, shortcode, thumbnail_url, timestamp, username. Se não especificado, o padrão é id, media_type, media_url, permalink e timestamp.
ig_user_id	string	Não	ID da conta Instagram Business ou Creator (opcional, padrão: ‘me’ para o usuário atual). Deve ser uma conta com stories ativos dentro da janela de 24 horas. Deve ser um ID numérico; nomes de usuário não são aceitos.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter marcações do usuário IG

INSTAGRAM_GET_IG_USER_TAGS

Obtém mídias do Instagram nas quais o usuário foi marcado por outros usuários. Use quando precisar recuperar todas as mídias nas quais uma conta Instagram Business ou Creator foi marcada, incluindo marcações em legendas, comentários ou na própria mídia.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação avançada — recuperar mídias após este cursor.
limit	integer	Não	Número de itens de mídia marcados a retornar por página (padrão: 25, máx.: 100).
before	string	Não	Cursor para paginação retroativa — recuperar mídias antes deste cursor.
fields	string	Não	Lista de campos separados por vírgula a retornar. Campos disponíveis: id, caption, comments_count, ig_id, is_comment_enabled, like_count, media_product_type, media_type, media_url, owner, permalink, shortcode, thumbnail_url, timestamp, username, video_title. Se não especificado, o padrão inclui campos comumente usados.
ig_user_id	string	Sim	ID da conta Instagram Business ou Creator. Use ‘me’ para a conta do usuário autenticado.
graph_api_version	string	Não	Versão da Instagram Graph API (ex.: ‘v21.0’). Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter perfil do Messenger

INSTAGRAM_GET_MESSENGER_PROFILE

Obtém as configurações do perfil do Messenger de uma conta Instagram. Retorna ice breakers e outras configurações de mensagens. Use quando precisar recuperar configurações de mensagens, perguntas de ice breaker ou configuração do Messenger de uma conta Instagram Business.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
fields	string	Não	Lista de campos separados por vírgula do perfil do Messenger a recuperar. Opções disponíveis: ice_breakers, greeting, persistent_menu, get_started, account_linking_url, whitelisted_domains. Se não fornecido, todos os campos disponíveis serão retornados.
ig_user_id	string	Sim	O ID de usuário do Instagram para o qual recuperar as configurações do perfil do Messenger.
graph_api_version	string	Não	A versão da Graph API a ser utilizada (ex.: ‘v21.0’). Padrão: ‘v21.0’.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter conversas da página

INSTAGRAM_GET_PAGE_CONVERSATIONS

Obtém conversas do Instagram para uma Página conectada a uma conta Instagram Business. Use o parâmetro platform=instagram para filtrar apenas conversas do Instagram.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação para obter a próxima página de resultados.
limit	integer	Não	Número máximo de conversas a retornar por página.
page_id	string	Sim	ID de usuário do Instagram ou ID de página para obter conversas. Este é o ID da conta Instagram Business que pode ser obtido do endpoint /me.
platform	string	Não	Plataforma para filtrar conversas. Defina como ‘instagram’ para obter apenas conversas do Instagram.
graph_api_version	string	Não	A versão da Graph API a ser utilizada (ex.: ‘v21.0’). Padrão: ‘v21.0’.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter comentários do post (Descontinuada)

INSTAGRAM_GET_POST_COMMENTS

DESCONTINUADA: Use INSTAGRAM_GET_IG_MEDIA_COMMENTS em vez disso. Obtém comentários de um post do Instagram. Requer conta Instagram Business ou Creator. Retorna array data vazio (não é um erro) quando não há comentários. Os dados de resposta estão aninhados em data.data; desencapsule antes de processar. Os timestamps são strings ISO 8601 com fuso horário; use comparação baseada em UTC.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação — obter comentários após este cursor. O valor vem de paging.cursors.after na resposta.
limit	integer	Não	Número de comentários a retornar (máx. 100).
ig_post_id	string	Sim	ID do post do Instagram.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter insights do post (Descontinuada)

INSTAGRAM_GET_POST_INSIGHTS

DESCONTINUADA: Use INSTAGRAM_GET_IG_MEDIA_INSIGHTS em vez disso. Obtém insights/análises de posts do Instagram (impressões, alcance, engajamento, etc.). Requer conta Business ou Creator; contas pessoais não podem acessar insights. As métricas podem estar indisponíveis por alguns minutos após a publicação; verifique se o status do post é FINISHED antes de chamar.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
metric	array	Não	Métricas a recuperar para a mídia. Se não fornecido e metric_preset não estiver definido, usa o preset auto_safe. As métricas permitidas variam por media_product_type: IMAGE/CAROUSEL: reach, likes, comments, saved, shares. VIDEO: reach, plays, likes, comments, saved, shares. REELS: reach, likes, comments, saved, shares, total_interactions, ig_reels_video_view_total_time, ig_reels_avg_watch_time, views, reels_skip_rate. Stories: reach, replies, taps_forward, taps_back, exits. Nota: ‘engagement’ e ‘impressions’ NÃO são métricas válidas isoladas.
ig_post_id	string	Sim	ID numérico de mídia do Instagram da Graph API (ex.: ‘17895695668004196’). Deve ser o ID numérico, NÃO o shortcode de URLs do Instagram. Use INSTAGRAM_GET_IG_USER_MEDIA para obter IDs de mídia numéricos válidos.
metric_preset	string (“auto_safe” | “image_basic” | “video_basic” | “reel_basic” | “carousel_basic”)	Não	Conjuntos de métricas predefinidos para diferentes tipos de mídia, para evitar erros da API.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter status do post (Descontinuada)

INSTAGRAM_GET_POST_STATUS

DESCONTINUADA: Use GetIgMedia em vez disso. Verifica o status de processamento de um container de post em rascunho. Faça polling até status_code=‘FINISHED’ antes de chamar INSTAGRAM_CREATE_POST; publicar antes disso dispara OAuthException 9007 (HTTP 400). Se status_code=‘ERROR’ ou permanecer não-terminal após ~30 tentativas, o container falhou permanentemente — crie um novo container. Faça polling a cada 3–5 segundos com backoff exponencial para evitar o erro 613/código 4/HTTP 429. Para carrosséis, todos os containers filhos devem atingir FINISHED antes de publicar o pai.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
creation_id	string	Sim	O ID do container de mídia retornado da ação INSTAGRAM_CREATE_MEDIA_CONTAINER. É uma string numérica (ex.: ‘17843131380645284’) que identifica unicamente o container de mídia. Use este ID para verificar o status de publicação do container antes de chamar o endpoint de publicação. Proveniente do campo data.id (não data.creation_id) na resposta de INSTAGRAM_CREATE_MEDIA_CONTAINER. Os containers expiram após ~24 horas; não reutilize um creation_id expirado.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter informações do usuário

INSTAGRAM_GET_USER_INFO

Obtém informações da conta Instagram Business, incluindo detalhes do perfil e estatísticas. IMPORTANTE: Funciona apenas para contas Business/Creator que você gerencia pelo Facebook Business Manager. Não é possível consultar contas públicas arbitrárias do Instagram. Use “me” para consultar sua própria conta autenticada. NOTA: followers_count e follows_count estão disponíveis APENAS ao consultar seu próprio perfil com ig_user_id=“me” — esses campos retornam nulo para IDs de usuário específicos devido a limitações da Instagram Graph API.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_user_id	string	Não	ID da conta Instagram Business. IMPORTANTE: Você só pode consultar contas Business/Creator que gerencia pelo Facebook Business Manager. Use “me” para consultar sua própria conta autenticada. Se não fornecido, o padrão é “me”.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter insights do usuário

INSTAGRAM_GET_USER_INSIGHTS

Obtém insights e análises no nível da conta do Instagram (visualizações de perfil, alcance, contagem de seguidores, etc.). Requer conta Business ou Creator; contas pessoais não são suportadas. Os timestamps retornados estão em UTC. metric_type (time_series ou total_value): quando definido como total_value, a API retorna um objeto total_value em vez de values. breakdown: aplicável apenas quando metric_type=total_value e apenas para métricas suportadas. timeframe: obrigatório para métricas relacionadas a dados demográficos e sobrescreve since/until para essas métricas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
since	integer	Não	Início do intervalo de tempo (inclusivo) como timestamp Unix (segundos). Também aceita strings de data (YYYY-MM-DD ou formato ISO 8601) que serão convertidas para timestamps.
until	integer	Não	Fim do intervalo de tempo (inclusivo) como timestamp Unix (segundos). Também aceita strings de data (YYYY-MM-DD ou formato ISO 8601) que serão convertidas para timestamps.
metric	array	Não	Métricas a recuperar para a conta de usuário. Métricas principais: reach, follower_count, online_followers. Métricas de engajamento: accounts_engaged, total_interactions, likes, comments, shares, saves, replies. Métricas de atividade: follows_and_unfollows, profile_links_taps, views. Métricas demográficas (requerem o parâmetro timeframe): engaged_audience_demographics, reached_audience_demographics, follower_demographics. DESCONTINUADAS (janeiro de 2025, Graph API v21+): impressions, email_contacts, phone_call_clicks, text_message_clicks, get_directions_clicks, profile_views e website_clicks não são mais suportados.
period	string (“day” | “week” | “days_28” | “lifetime”)	Não	Valores de período válidos para agregação de insights de usuário do Instagram. Disponíveis: day (diário), week (semanal), days_28 (28 dias), lifetime (para métricas de audiência).
breakdown	string	Não	Breakdown a usar quando metric_type=total_value. Valores permitidos: contact_button_type, follow_type, media_product_type, age, city, country, gender.
timeframe	string (“this_month” | “this_week”)	Não	Valores de timeframe válidos para insights demográficos de usuário do Instagram. Obrigatório para métricas engaged_audience_demographics e reached_audience_demographics. Sobrescreve os parâmetros since/until quando especificado. Apenas this_week e this_month são atualmente suportados.
ig_user_id	string	Não	ID da conta Instagram Business — deve ser um ID numérico (ex.: ‘17841400008460056’). IDs de API de conteúdo com prefixo ‘ca_’ não são suportados. Opcional, padrão: usuário atual.
metric_type	string	Não	Tipo de agregação para resultados. Valores permitidos: time_series, total_value.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter mídia do usuário (Descontinuada)

INSTAGRAM_GET_USER_MEDIA

DESCONTINUADA: Use INSTAGRAM_GET_IG_USER_MEDIA em vez disso. Obtém mídias do usuário do Instagram (posts, fotos, vídeos). Funciona apenas para contas Business ou Creator conectadas; contas pessoais não retornam dados. Os dados de resposta estão aninhados em data.data; desencapsule antes de processar. Os itens misturam imagens, vídeos, carrosséis e reels — filtre por media_type e media_product_type. Use media_url para download de arquivo, permalink para links de compartilhamento. Os campos caption e like_count podem ser nulos. Os timestamps são ISO 8601 em UTC. HTTP 429 com cabeçalho Retry-After indica limitação de taxa.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação — obter mídias após este cursor. Use paging.cursors.after da resposta para paginar; defina um limite superior (ex.: ~300 posts) para evitar loops ilimitados.
limit	integer	Não	Número de itens de mídia a retornar (máx. 100). Uma única chamada pode não retornar todas as mídias; pagine via after para resultados completos.
ig_user_id	string	Não	ID numérico da conta Instagram Business (NÃO nome de usuário). Deve ser um ID numérico como ‘17841405793187218’. Omita ou deixe vazio para obter as mídias do usuário autenticado atual. Para encontrar o ID numérico de uma conta, use a ação INSTAGRAM_GET_USER_INFO.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar todas as conversas

INSTAGRAM_LIST_ALL_CONVERSATIONS

Lista todas as conversas de DM do Instagram para o usuário autenticado. Requer conta Business/Creator com permissões de mensagens; contas pessoais retornam resultados vazios. As conversas da resposta estão aninhadas em data.data — acessar o data de nível superior como lista final retorna zero itens. Uma lista data vazia é um resultado válido (não é erro), significando que não há conversas no escopo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação. Obtenha em paging.cursors.after na resposta; a ausência de paging.cursors.after ou paging.next sinaliza fim dos resultados.
limit	integer	Não	Número máximo de conversas a retornar.
ig_user_id	string	Não	ID da conta Instagram Business (opcional para /me/conversations).
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar todas as mensagens

INSTAGRAM_LIST_ALL_MESSAGES

Lista todas as mensagens de uma conversa de DM específica do Instagram. Requer conta Business ou Creator com permissões de mensagens; contas pessoais retornam resultados vazios. Os dados de resposta estão duplamente aninhados em data.data; mensagens somente com anexos podem ter campos de texto vazios.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
after	string	Não	Cursor para paginação. Passe paging.cursors.after da resposta anterior para buscar a próxima página. Pare quando paging.cursors.after ou paging.next estiver ausente.
limit	integer	Não	Número máximo de mensagens a retornar.
conversation_id	string	Sim	Identificador único da conversa do Instagram. Obtenha chamando a ação INSTAGRAM_LIST_ALL_CONVERSATIONS, que retorna IDs de conversa no formato ‘aWdfZAG06…’ (string codificada em base64).
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Marcar como visto

INSTAGRAM_MARK_SEEN

Marca mensagens de DM do Instagram como lidas/vistas para um usuário específico. Envia uma ação de remetente ‘mark_seen’ para indicar que as mensagens do destinatário especificado foram lidas. Marcar como visto é visível para a outra parte e altera o estado de leitura da caixa de entrada — use com aprovação explícita do usuário em fluxos automatizados ou em massa. LIMITAÇÕES IMPORTANTES: o recurso de API sender_action pode ter suporte limitado no Instagram; o destinatário deve ter uma janela de mensagens ativa de 24 horas aberta; requer a permissão instagram_manage_messages; funciona apenas com contas Instagram Business ou Creator.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_user_id	string	Não	ID da conta Instagram Business. Opcional — quando não fornecido, o endpoint /me/messages é usado em vez de /{ig_user_id}/messages.
recipient_id	string	Sim	IGSID (Instagram-Scoped User ID) do destinatário. É uma string numérica obtida dos participantes da conversa (ex.: ‘17841479358498320’). O destinatário deve ter uma conversa existente com sua conta Instagram Business/Creator.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada (ex.: ‘v21.0’).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Publicar respostas a comentários do IG

INSTAGRAM_POST_IG_COMMENT_REPLIES

Cria uma resposta a um comentário do Instagram. Use quando precisar responder a um comentário específico em um post do Instagram pertencente a uma conta Business ou Creator. A resposta deve ter no máximo 300 caracteres, conter no máximo 4 hashtags e 1 URL, e não pode ser composta inteiramente de letras maiúsculas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
message	string	Sim	O conteúdo de texto da resposta a ser publicada. Comprimento máximo: 300 caracteres. Máximo de 4 hashtags permitidas. Máximo de 1 URL permitida. Não pode ser composta inteiramente de letras maiúsculas.
ig_comment_id	string	Sim	O identificador único do comentário do Instagram ao qual você deseja responder. Este é o ID do comentário pai que receberá a resposta.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Publicar comentários em mídia do IG

INSTAGRAM_POST_IG_MEDIA_COMMENTS

Cria um comentário em um objeto de mídia do Instagram. Use quando precisar publicar um comentário em um post, foto, vídeo ou carrossel específico do Instagram. O comentário deve ter no máximo 300 caracteres, conter no máximo 4 hashtags e 1 URL, e não pode ser composto inteiramente de letras maiúsculas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
message	string	Sim	O conteúdo de texto do comentário a ser publicado no objeto de mídia. Comprimento máximo: 300 caracteres. Máximo de 4 hashtags permitidas. Máximo de 1 URL permitida. Não pode ser composto inteiramente de letras maiúsculas.
ig_media_id	string	Sim	O identificador único do objeto de mídia do Instagram onde o comentário será publicado. Este é o ID do post, foto, vídeo ou carrossel do Instagram.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Publicar mídia do usuário IG

INSTAGRAM_POST_IG_USER_MEDIA

Cria um container de mídia para posts do Instagram. Use para criar um container para imagens, vídeos, Reels ou carrosséis. Esta é a primeira etapa do processo de publicação em dois passos do Instagram — após criar o container, use o endpoint media_publish para publicá-lo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
caption	string	Não	Texto da legenda do post. Use codificação HTML de URL para hashtags (# vira %23).
children	array	Não	Para posts carrossel — array de IDs de container (2–10 itens) de containers de mídia criados anteriormente.
cover_url	string	Não	Para Reels — deve ser uma URL HTTP/HTTPS válida apontando para uma imagem de capa personalizada. URLs com parâmetros de consulta (como URLs assinadas) NÃO são suportadas pelo Instagram. Use URLs diretas e acessíveis publicamente sem strings de consulta. Se tanto cover_url quanto thumb_offset forem fornecidos, cover_url tem precedência.
image_url	string	Não	Deve ser uma URL HTTP/HTTPS válida apontando para um arquivo de imagem JPEG publicamente acessível. URLs com parâmetros de consulta (como URLs assinadas do AWS S3) NÃO são suportadas pelo Instagram. Use URLs diretas e acessíveis publicamente sem strings de consulta. Ao menos um de: image_url, image_file, video_url, video_file ou children deve ser fornecido.
user_tags	array	Não	Array de objetos de marcação de usuário para marcar contas públicas do Instagram. Para imagens: coordenadas x e y (0,0–1,0, a partir do canto superior esquerdo) são OBRIGATÓRIAS. Para Reels: apenas nome de usuário é permitido; coordenadas x/y NÃO podem ser usadas.
video_url	string	Não	Deve ser uma URL HTTP/HTTPS válida apontando para um arquivo MP4 de vídeo ou Reel publicamente acessível. URLs com parâmetros de consulta NÃO são suportadas. Use URLs diretas e acessíveis publicamente. Ao usar apenas video_url, media_type será automaticamente definido como ‘REELS’ se não especificado.
audio_name	string	Não	Para Reels — nome personalizado para a faixa de áudio (padrão: ‘Original Audio’).
ig_user_id	string	Sim	O identificador único da conta Instagram Business (IG User ID) para a qual criar a mídia. Deve ser uma conta Instagram Business.
image_file	object	Não	Arquivo de imagem local para upload. Objeto FileUploadable onde ‘name’ é o nome do arquivo. O arquivo será enviado para uma URL pública temporária para o Instagram buscar.
media_type	string (“REELS” | “CAROUSEL” | “STORIES”)	Não	Tipo de mídia para o container. Valores válidos: ‘REELS’ (para conteúdo de vídeo), ‘CAROUSEL’ (para posts carrossel com filhos), ‘STORIES’ (para posts de story). ‘VIDEO’ está descontinuado e não é mais suportado — use ‘REELS’ para todo conteúdo de vídeo.
video_file	object	Não	Arquivo de vídeo local para upload. Objeto FileUploadable onde ‘name’ é o nome do arquivo. O arquivo será enviado para uma URL pública temporária para o Instagram buscar.
location_id	string	Não	ID de Página do Facebook de um local para marcar. A Página deve ter dados de latitude/longitude.
thumb_offset	integer	Não	Para vídeos/Reels — deslocamento em milissegundos para o frame de miniatura (padrão: 0).
collaborators	array	Não	Array de até 3 nomes de usuário públicos do Instagram para marcar como colaboradores. Suportado para imagens, vídeos e containers carrossel pai (não Stories ou itens filho de carrossel).
share_to_feed	boolean	Não	Para Reels — se deve compartilhar tanto para a aba Feed quanto para a aba Reels. Aplicável apenas quando media_type é REELS.
is_carousel_item	boolean	Não	Indica que este container faz parte de um carrossel. Para carrosséis: crie 2–10 containers individuais e depois crie um container carrossel pai com os IDs deles. Quando verdadeiro, colaboradores não podem ser definidos neste item filho.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Publicar mídia do usuário IG (publicar)

INSTAGRAM_POST_IG_USER_MEDIA_PUBLISH

Publica um container de mídia em uma conta Instagram Business. Esta ação aguarda automaticamente o container terminar de processar antes de publicar. Limitado a 25 posts publicados via API por janela móvel de 24 horas. O processo de publicação: 1. Primeiro, crie um container de mídia usando INSTAGRAM_CREATE_MEDIA_CONTAINER. 2. Chame esta ação com o creation_id — ela fará polling automático pelo status FINISHED. 3. Assim que pronto, a mídia é publicada e o ID da mídia publicada é retornado. Para vídeos/reels, o processamento pode levar 30–120 segundos. Imagens são normalmente instantâneas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_user_id	string	Sim	ID da conta Instagram Business (string numérica) ou ‘me’ para o usuário autenticado. Este ID é retornado por INSTAGRAM_GET_USER_INFO ou ações similares. Não passe números de conta bancária, IDs de conexão ou outros identificadores não-Instagram.
creation_id	string	Sim	ID de container retornado por INSTAGRAM_CREATE_MEDIA_CONTAINER (string numérica). NÃO é o mesmo que ig_user_id. Não passe números de conta bancária ou outros identificadores não-Instagram.
max_wait_seconds	integer	Não	Tempo máximo em segundos para aguardar o container atingir o status FINISHED antes de publicar. Imagens normalmente ficam prontas instantaneamente, mas vídeos/reels comumente levam 30–120 segundos para processar. AVISO: Definir como 0 pula todas as verificações de status e tenta a publicação imediata, o que falhará com o erro 9007 se o container ainda estiver processando (comum para vídeos). Para vídeos/reels, use pelo menos 60 segundos (padrão) ou mais (até 300).
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.
poll_interval_seconds	number	Não	Intervalo em segundos entre verificações de status enquanto aguarda o container ficar pronto. Padrão: 3 segundos.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Responder a menções de usuário IG

INSTAGRAM_POST_IG_USER_MENTIONS

Responde a uma menção da sua conta Instagram Business ou Creator. Use quando precisar responder a comentários ou legendas de mídia onde sua conta foi @mencionada por outro usuário do Instagram. Isso cria um comentário na mídia ou comentário que contém a menção.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
message	string	Sim	O conteúdo de texto da sua resposta à menção. Isso cria um comentário na mídia ou comentário onde você foi mencionado.
media_id	string	Sim	O ID do objeto de mídia do Instagram (post, foto, vídeo ou carrossel) onde sua conta foi mencionada. Esta é a mídia que contém a menção original.
comment_id	string	Não	ID opcional de um comentário específico onde você foi mencionado. Se fornecido, sua resposta será direcionada para aquele comentário. Se não fornecido, a resposta será publicada na mídia em si.
ig_user_id	string	Sim	O identificador único da conta Instagram Business ou Creator que foi mencionada. Este é o ID da sua conta do Instagram que recebeu a menção.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Responder a comentário (Descontinuada)

INSTAGRAM_REPLY_TO_COMMENT

DESCONTINUADA: Use INSTAGRAM_POST_IG_COMMENT_REPLIES em vez disso. Responde a um comentário em mídia do Instagram. Utilizável apenas em comentários pertencentes a mídias de propriedade da conta autenticada. Cria uma resposta pública e irreversível; invoque apenas com confirmação explícita do usuário, não para uso em massa ou especulativo.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
message	string	Sim	Texto da mensagem de resposta. Deve estar em conformidade com as políticas de conteúdo do Instagram; texto excessivamente longo ou que viola políticas pode ser rejeitado.
ig_comment_id	string	Sim	ID do comentário do Instagram para responder. Deve pertencer a uma mídia de propriedade da conta do Instagram autenticada; respostas a mídias de outras contas não são permitidas.
graph_api_version	string	Não	Versão da Facebook Graph API a ser utilizada.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Enviar imagem

INSTAGRAM_SEND_IMAGE

Envia uma imagem via DM do Instagram para um usuário específico. Cada envio altera o estado da caixa de entrada; evite envios em massa ou automatizados sem aprovação explícita do usuário.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
image_url	string	Sim	URL acessível publicamente da imagem a enviar. Deve ser um link direto para um arquivo de imagem (JPEG, PNG ou GIF) acessível via HTTPS. A URL não deve exigir autenticação para acesso.
ig_user_id	string	Não	ID da conta Instagram Business. Deve ser uma string de ID numérico (ex.: ‘17841400123456789’), não um nome de usuário. Opcional ao usar o endpoint /me/messages.
recipient_id	string	Sim	IGSID do destinatário (Instagram Scoped User ID). Deve ser uma string de ID numérico (ex.: ‘17841479358498320’), NÃO um nome de usuário. IGSIDs são obtidos de conversas ou eventos de webhook quando usuários enviam mensagem para seu negócio primeiro. Você só pode enviar mensagens para usuários que iniciaram uma conversa com seu negócio nas últimas 24 horas (ou 7 dias com a tag HUMAN_AGENT).
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada (ex.: ‘v21.0’).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Enviar mensagem de texto

INSTAGRAM_SEND_TEXT_MESSAGE

Envia uma mensagem de texto para um usuário do Instagram via DM em uma conversa existente. Não é possível iniciar novos threads de DM — uma conversa prévia deve existir. Requer conta Instagram Business ou Creator com permissões de mensagens. Falha com error_subcode 2534022 se estiver fora da janela de mensagens; não tente novamente essas falhas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
text	string	Sim	Texto da mensagem a enviar.
ig_user_id	string	Não	ID da conta Instagram Business (opcional ao usar /me/messages).
recipient_id	string	Sim	PSID do destinatário (Instagram-scoped ID). Deve ser um PSID real obtido de INSTAGRAM_LIST_ALL_CONVERSATIONS ou INSTAGRAM_LIST_ALL_MESSAGES — nomes de usuário ou IDs fabricados causam HTTP 400 (código 100).
graph_api_version	string	Não	Versão da Instagram Graph API.
reply_to_message_id	string	Não	ID da mensagem (mid) para responder. Isso cria um link de resposta visual para a mensagem original na conversa. O mid pode ser obtido de eventos de webhook ou respostas anteriores da API.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Atualizar perfil do Messenger

INSTAGRAM_UPDATE_MESSENGER_PROFILE

Atualiza as configurações do perfil do Messenger de uma conta Instagram. Use quando precisar configurar ice breakers e opções de mensagens. Ice breakers são perguntas sugeridas que ajudam usuários a iniciar conversas com sua conta Instagram Business.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
ig_user_id	string	Sim	ID da conta Instagram Business cujo perfil do Messenger será atualizado.
ice_breakers	array	Sim	Array de objetos ice breaker para configurar no perfil do Messenger. Ice breakers fornecem perguntas sugeridas para ajudar usuários a iniciar conversas. Máximo de 4 ice breakers permitidos.
graph_api_version	string	Não	Versão da Instagram Graph API a ser utilizada. Padrão: v21.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.