oEmbed de Instagram

Puedes hacer una consulta al punto de conexión oEmbed de Instagram para obtener los metadatos básicos y el código de inserción de HTML de una publicación de Instagram con el objetivo de mostrar la publicación en otro sitio web o app. Admite publicaciones de fotos, videos, reels y guías.

Usos comunes

Representar publicaciones en apps de mensajes.
Insertar publicaciones en sitios web y blogs.
Representar publicaciones en sistemas de administración de contenido.

Puntos de conexión

Punto de conexión	Descripción
`GET /instagram_oembed`	Permite obtener los metadatos básicos y el código de inserción de HTML de una publicación de Instagram.

Requisitos

Una cuenta de desarrollador de Facebook
Una app de Facebook en modo activo
Un token de acceso
Revisión de apps para la función oEmbed Read

Limitaciones

El punto de conexión oEmbed de Instagram solo está diseñado para insertar contenido de Instagram en sitios web y apps. No se lo puede utilizar con otros fines. Está estrictamente prohibido el uso de los metadatos y el contenido de las páginas, las publicaciones o los videos (o sus derivados) del punto de conexión con cualquier fin que no sea el de ofrecer una visualización final de la página, la publicación o el video. La prohibición incluye el consumo, la manipulación, la extracción o el almacenamiento de metadatos y contenido, por ejemplo, la obtención de información sobre páginas, publicaciones y videos a partir de metadatos con fines de análisis.
No se pueden consultar publicaciones en cuentas de Instagram privadas, inactivas o con restricciones por edad.
No se admiten las cuentas con Embeds desactivados.
No se admiten las historias.
No se admite Shadow DOM.

Revisión de apps

A fin de usar oEmbed, tu app debe someterse a la revisión de apps en relación con la función oEmbed Read.

En el campo del formulario para proporcionar una URL en la que podamos probar oEmbed Read, usa el punto de conexión oEmbed de Instagram a fin de obtener el código de inserción de HTML de las publicaciones de carácter público de nuestra página de Facebook oficial o en la página de Instagram (o bien, obtén el código de inserción de HTML de alguna de las páginas). Agrega el código de inserción de HTML a la página de tu propiedad en la que mostrarás el contenido de oEmbed, e ingresa la URL de esa página en el campo del formulario.

Una vez que te hayan aprobado la función oEmbed Read, podrás insertar tus páginas, publicaciones o videos propios con las URL respectivas.

Tokens de acceso

El punto de conexión oEmbed de Instagram requiere un token de acceso a la app (recomendado) o un token de acceso del cliente.

Tokens de acceso a la app

Si tu app depende de un servidor de sistema interno, recomendamos que uses el token de acceso a la app cuando accedas al punto de conexión oEmbed. Los límites de frecuencia dependen del tipo de token incluido en la solicitud, y los límites de frecuencia de token de app permiten hasta 5 millones de solicitudes por día.

Puedes encontrar las instrucciones para generar tokens de acceso a la app en la sección de tokens de apps de nuestra documentación sobre tokens de acceso.

Ten en cuenta que los tokens de acceso a la app nunca pueden usarse del lado del cliente. Estos siempre deben estar protegidos y almacenados en tu servidor. En cambio, si tu app debe usar un token del lado del cliente, usa un token de acceso del cliente.

Tokens de acceso del cliente

Si tu app debe acceder al punto de conexión oEmbed desde un agente de usuario, como un dispositivo móvil o un navegador web, debe usar un token de acceso del cliente y estará sujeta a los límites de frecuencia del token de cliente.

Para obtener un token de acceso del cliente, inicia sesión en tu panel de apps y navega a Configuración > Avanzada > Seguridad > Token de cliente.

A diferencia de los tokens de acceso a la app, los tokens de acceso del cliente no se pueden usar en solicitudes de punto de conexión oEmbed solos, sino que deben estar combinados con tu identificador de la app. Para eso, agrega el token al final del identificador de la app, separado por una barra vertical (|):

{app-id}|{client-token}

Por ejemplo:

access_token=1234|5678

Límites de frecuencia

Los límites de frecuencia dependen del tipo de token de acceso que tu app incluye en cada solicitud.

Límites de frecuencia de token de la app

Las apps que dependen de tokens de acceso a la app pueden hacer hasta 5 millones de solicitudes cada 24 horas.

Límites de frecuencia de token de cliente

Los límites de frecuencia de token de cliente son bastante más bajos que los límites de frecuencia de token de la app. No revelamos el límite real porque este variará según la actividad de tu app. Sin embargo, puedes estar tranquilo de que tu app no alcanzará el límite a menos que tenga un comportamiento similar a un bot, como el procesamiento por lotes de miles de solicitudes o el envío de miles de solicitudes por agente o usuario de app.

Cómo obtener el código HTML de inserción

Para obtener el código de inserción de HTML de una publicación de Instagram, envía una solicitud a:

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

Reemplaza {url} por la URL de la publicación de Instagram que quieres consultar y {access-token} por el token de acceso del cliente o el token de acceso a la app (o envíalo en un encabezado HTTP). Si usas un token de acceso del cliente, recuerda que debes combinarlo con el identificador de la app mediante un símbolo de barra vertical, de lo contrario, la solicitud no funcionará.

Si la operación es exitosa, la API responderá con un objeto JSON que incluirá el código de inserción de HTML de la publicación, entre otros datos. El código de inserción de HTML se asignará a la propiedad html.

Consulta la referencia de oEmbed de Instagram a fin de obtener una lista de parámetros de cadena de consulta que puedes incluir para expandir la solicitud. También puedes incluir el parámetro de cadena de consulta fields para especificar los campos que quieres obtener. Si omites esta información, todos los campos predeterminados se incluirán en la respuesta.

Ejemplo de solicitud

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

Ejemplo de respuesta

Para facilitar la lectura, se truncaron algunos valores y se agregaron puntos suspensivos (...).

{
  "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

El parámetro de cadena de consulta url acepta los siguientes 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}

Código JS para insertar

El código de inserción de HTML contiene una referencia a la biblioteca de JavaScript embed.js de Instagram. Cuando la biblioteca se carga, busca el código HTML de la publicación en la página y genera la representación completa de la publicación. Si quieres cargar la biblioteca por separado, incluye el parámetro de cadena de consulta omitscript=true en la solicitud. Para iniciar manualmente el código de inserción de HTML, llama a la función instgrm.Embeds.process() después de cargar la biblioteca.

Tamaño de la publicación

La publicación insertada es ajustable y se adaptará al tamaño del contenedor. Eso significa que la altura variará según el ancho del contenedor y la longitud del texto. Puedes incluir el parámetro de cadena de consulta maxwidth en la solicitud para establecer el ancho máximo.

Cómo obtener imágenes en miniatura

Recomendamos que representes todo el código de inserción de HTML de la publicación siempre que sea posible. De lo contrario, puedes obtener la URL de la imagen en miniatura de una publicación y representar eso en su lugar. Sin embargo, si haces eso, debes proporcionar una atribución clara junto a la imagen, incluida la atribución al autor original y a Instagram, y un enlace a la publicación de Instagram que estás consultando.

Para obtener la URL de una imagen en miniatura de una publicación y la información de atribución, envía una solicitud a:

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

Reemplaza {url} por la URL de la publicación de Instagram que quieres consultar, {maxwidth} por el tamaño máximo de la imagen en miniatura que quieres representar y {access-token} por el token de acceso del cliente o el token de acceso a la app.

Ejemplo de solicitud

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..."

Ejemplo de respuesta

Algunos valores se truncaron y se agregaron puntos suspensivos (...) para facilitar la lectura.

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

Cómo enviar tokens de acceso en un encabezado

Si no quieres incluir el token de acceso en la cadena de consulta de la solicitud, puedes enviarlo a través de un encabezado HTTP Authorization.

Authorization: Bearer {access-token}

Por ejemplo:

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..."