oEmbed do Instagram

Consulte o ponto de extremidade oEmbed do Instagram para obter um HTML incorporado de uma publicação do Instagram e os metadados básicos para exibi-la em outro site ou app. Compatível com publicações de foto, vídeo, Reel e guia.

Usos comuns

Renderização de publicações em apps de mensagem.
Incorporação de publicações em sites e blogs.
Renderização de publicações em sistemas de gerenciamento de conteúdo.

Pontos de extremidade

Ponto de extremidade	Descrição
`GET /instagram_oembed`	Obtenha um HTML incorporado e os metadados básicos de uma publicação do Instagram.

Requisitos

Uma conta de desenvolvedor do Facebook
Um app do Facebook no modo Publicado
Um token de acesso
Análise do app para o recurso oEmbed Read

Limitações

O ponto de extremidade oEmbed do Instagram deve ser usado somente para incorporar conteúdo do Instagram em sites e apps. Ele não deve ser usado para nenhum outro propósito. O uso de metadados e conteúdo de páginas, publicações ou vídeos (ou derivados) do ponto de extremidade para qualquer propósito que não o fornecimento de visualização de front-end da página, da publicação ou do vídeo em questão é estritamente proibido. Essa proibição engloba o consumo, a manipulação, a extração ou a persistência de metadados e conteúdo, incluindo, entre outros, obter informações sobre Páginas, publicações e vídeos a partir dos metadados para fins de análise.
As publicações em contas do Instagram privadas, inativas e com restrição de idade não são compatíveis.
As contas com incorporações desabilitadas não são compatíveis.
Não há compatibilidade com Stories.
Não há compatibilidade com Shadow DOM.

Análise do app

Para usar o oEmbed, o app precisa passar pela análise para o recurso oEmbed Read.

No campo do formulário em que você fornece uma URL para o teste do oEmbed Read, use o ponto de extremidade oEmbed do Instagram para obter o HTML incorporado de qualquer publicação aberta na nossa Página oficial no Facebook ou no Instagram (ou obtenha o HTML incorporado de qualquer uma das páginas). Adicione o HTML incorporado obtido à página onde o conteúdo oEmbed deverá ser exibido e insira a URL dessa página no campo do formulário.

Depois de receber a aprovação para o recurso oEmbed Read, você poderá incorporar páginas, publicações ou vídeos usando as respectivas URLs.

Tokens de acesso

O ponto de extremidade oEmbed do Instagram requer um token de acesso do app (recomendado) ou um token de acesso do cliente.

Tokens de acesso do app

Caso seu app dependa de um servidor de back-end, recomendamos que você use o token de acesso do app ao acessar o ponto de extremidade oEmbed. Os limites de volume dependem do tipo de token incluído na solicitação, e os limites de volume do token do app permitem até 5 milhões de solicitações por dia.

Para ver instruções sobre como gerar esses tokens, consulte a seção sobre tokens do app da nossa documentação sobre tokens de acesso.

Lembre-se de que os tokens de acesso do app nunca devem ser usados no lado do cliente. Eles devem ser mantidos em segurança e armazenados no seu servidor. Se o app precisar usar um token no lado do cliente, use um token de acesso do cliente.

Tokens de acesso do cliente

Caso o app precise acessar o ponto de extremidade oEmbed a partir de um agente do usuário (como um dispositivo móvel ou um navegador da web), o app deverá usar um token de acesso do cliente e estará sujeito aos limites de volume correspondentes.

Para obter um token de acesso do cliente, entre no Painel de Apps e navegue até Configurações > Avançado > Segurança > Token de cliente.

Ao contrário dos tokens de acesso do app, os tokens de acesso do cliente não podem ser usados em solicitações do ponto de extremidade oEmbed sozinhos. Eles devem ser combinados com o ID do app. Para fazer isso, adicione seu token ao final do ID do app, separado por um símbolo de barra (|):

{app-id}|{client-token}

Por exemplo:

access_token=1234|5678

Limites de volume

Os limites de volume dependem do tipo de token de acesso que seu app inclui em cada solicitação.

Limites de volume do token do app

Os apps que dependem de tokens de acesso do app podem fazer até 5 milhões de solicitações em 24 horas.

Limites de volume do token de cliente

Os limites de volume do token de cliente são significativamente mais baixos em comparação aos do token do app. Não revelamos o limite real, pois ele mudará dependendo da atividade do app. Contudo, você pode supor com segurança que seu app não alcançará o limite a menos que ele exiba um comportamento similar a um bot, como fazer milhares de solicitações em lote ou enviar milhares de solicitações por agente ou usuário.

Obter HTML incorporado

Para obter o HTML incorporado de uma publicação do Instagram, envie uma solicitação para:

GET /instagram_oembed?url={url}&access_token={access-token}

Substitua {url} pela URL da publicação do Instagram que você deseja consultar e {access-token} pelo seu token de acesso do cliente ou app (ou transmita-o para nós em um cabeçalho HTTP). Se estiver usando um token de acesso do cliente, lembre-se de que você deve combiná-lo com o ID do app usando um símbolo de barra, do contrário, a solicitação falhará.

Caso a solicitação seja bem-sucedida, a API responderá com um objeto JSON contendo o HTML incorporado da publicação e dados adicionais. O HTML incorporado será atribuído à propriedade html.

Consulte a referência do oEmbed do Instagram para ver uma lista dos parâmetros da string de consulta que você pode incluir para aumentar a solicitação. Além disso, é possível incluir o parâmetro da string de consulta fields para especificar os campos que você deseja que sejam retornados. Caso ele seja omitido, todos os campos padrão serão incluídos na resposta.

Exemplo de solicitação

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

Exemplo de resposta

Alguns valores foram reduzidos com reticências (...) para facilitar a leitura.

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

Formatos de URL

O parâmetro da string de consulta url aceita os seguintes formatos de URL:

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

Incorporar JS

O HTML incorporado contém uma referência à biblioteca de JavaScript embed.js do Instagram. Quando carregar, a biblioteca buscará o HTML da publicação na página e gerará a publicação renderizada. Se você quiser carregar a biblioteca separadamente, inclua o parâmetro da string de consulta omitscript=true na solicitação. Para inicializar manualmente o HTML incorporado, chame a função instgrm.Embeds.process() depois de carregar a biblioteca.

Tamanho da publicação

A publicação incorporada é responsiva e se adapta ao tamanho do contêiner. Isso significa que a altura variará dependendo da largura do contêiner e do comprimento da legenda. Você pode definir a largura máxima incluindo o parâmetro da string de consulta maxwidth na solicitação.

Como obter miniaturas

Recomendamos que você renderize todo o HTML incorporado da publicação sempre que possível. Se você não conseguir fazer isso, pode obter a URL da imagem de miniatura de uma publicação e renderizá-la. No entanto, se fizer isso, você precisará informar a atribuição de modo claro próxima à imagem, incluindo a atribuição ao autor original e ao Instagram, além de um link para a publicação do Instagram que está consultando.

Para obter a URL da miniatura e a atribuição de uma publicação, envie uma solicitação para:

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

Substitua {url} pela URL da publicação do Instagram que você quer consultar, {maxwidth} pelo tamanho máximo da miniatura que deseja renderizar e {access-token} pelo seu token de acesso do cliente ou app.

Exemplo de solicitação

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

Exemplo de resposta

Alguns valores foram reduzidos com reticências (...) para facilitar a leitura.

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

Como transmitir tokens de acesso por cabeçalhos

Se você não quiser incluir seu token de acesso na string de consulta da solicitação, transmita-o para nós por meio de um cabeçalho HTTP Authorization.

Authorization: Bearer {access-token}

Por exemplo:

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."