Publicación de contenido

Puedes usar la API Graph de Instagram para realizar publicaciones con un único vídeo, reel o imagen (es decir, publicaciones con un único archivo multimedia) o publicaciones con varios vídeos e imágenes (publicaciones por secuencia) en cuentas profesionales de Instagram.

A partir del 1 de julio de 2023, todos los vídeos individuales publicados en la sección de noticias mediante la API de publicación de contenido de Instagram se compartirán como reels.

Requisitos

Identificadores de acceso

Todas las solicitudes deben incluir el identificador de acceso de usuario de la aplicación.

Permisos

La publicación se basa en una combinación de los siguientes permisos. La combinación exacta depende de los extremos que utilice tu aplicación. Consulta nuestras referencias de los extremos para determinar los permisos que requiere cada uno de ellos.

Si utilizarán tu aplicación usuarios que no tengan ningún rol en ella ni en una empresa que la haya reclamado, debes solicitar la aprobación para cada permiso mediante la revisión de la aplicación. De este modo, los usuarios de la aplicación sin rol podrán conceder permisos a tu aplicación.

Servidor público

Aplicaremos cURL al contenido multimedia usado en los intentos de publicación. Por esta razón, este contenido debe estar hospedado en un servidor accesible públicamente en el momento que se lleve a cabo el intento.

Autorización de publicación en páginas

No se puede publicar en las cuentas profesionales de Instagram conectadas a una página que requiera autorización de publicación en páginas (PPA) hasta que se haya completado la PPA.

Es posible que un usuario de la aplicación pueda realizar tareas en una página que al principio no necesite PPA, pero más adelante, sí. En tal caso, el usuario de la aplicación no podría publicar contenido en su cuenta profesional de Instagram hasta que se completara la PPA. Dado que no es posible determinar si la página de un usuario de la aplicación requiere PPA, recomendamos que aconsejes a los usuarios de la aplicación que completen la PPA de manera preventiva.

Limitaciones

  • JPG es el único formato de imagen admitido. No se admiten los formatos JPEG extendidos, como MPO y JPS.
  • No se admiten las etiquetas de compra.
  • No se admiten las etiquetas de contenido de marca.
  • No se admiten los filtros.
  • No se admite la publicación en Instagram TV.

Para obtener información sobre otras limitaciones, consulta la referencia de cada extremo.

Límite de frecuencia

Las cuentas de Instagram están limitadas a 50 publicaciones de la API por cada periodo dinámico de 24 horas. Las secuencias se consideran una única publicación. El límite se aplica en el extremo POST /{ig-user-id}/media_publish al intentar publicar un contenedor de archivos multimedia. Recomendamos que tu aplicación también aplique el límite de frecuencia de publicación, especialmente si permite que los usuarios programen publicaciones para que se publiquen en el futuro.

Para comprobar el uso del límite de frecuencia actual de una cuenta profesional de Instagram, envía una consulta al extremo GET /{ig-user-id}/content_publishing_limit.

Extremos

La API consta de los extremos siguientes. Consulta los requisitos de uso en cada documento de referencia de los extremos.

Publicaciones con un único archivo multimedia

Para publicar un único vídeo, reel, imagen o historia, debes seguir dos pasos:

  1. Utiliza el extremo POST /{ig-user-id}/media para crear un contenedor a partir de una imagen o un vídeo hospedado en tu servidor público.
  2. Utiliza el extremo POST /{ig-user-id}/media_publish para publicar el contenedor.

Paso 1 de 2: Crear el contenedor

Supongamos que tienes una imagen en…

https://www.example.com/images/bronz-fonz.jpg

… y quieres publicarla con el hashtag “#BronzFonz” como subtítulo. Envía una solicitud al extremo POST /{ig-user-id}/media:

Ejemplo de solicitud

POST https://graph.facebook.com/v20.0/17841400008460056/media
  ?image_url=https://www.example.com/images/bronz-fonz.jpg
  &caption=#BronzFonz

Esta solicitud devuelve un identificador de contenedor para la imagen.

Ejemplo de respuesta

{
  "id": "17889455560051444"  // IG Container ID
}

Paso 2 de 2: Publicar el contenedor

Utiliza el extremo POST /{ig-user-id}/media_publish para publicar el identificador de contenedor devuelto en el paso anterior.

Ejemplo de solicitud

POST https://graph.facebook.com/v20.0/17841400008460056/media_publish ?creation_id=17889455560051444

Ejemplo de respuesta

{
  "id": "17920238422030506" // IG Media ID
}

Publicaciones por secuencia

Puedes publicar hasta 10 imágenes, vídeos o una combinación de ambos en una única publicación (una publicación por secuencia). La publicación de secuencias es un proceso de tres pasos:

  1. Utiliza el extremo POST /{ig-user-id}/media a fin de crear contenedores de elementos individuales para cada imagen y vídeo que aparecerá en la secuencia.
  2. Vuelve a usar el extremo POST /{ig-user-id}/media para crear un único contenedor de secuencia para los elementos.
  3. Utiliza el extremo POST /{ig-user-id}/media_publish para publicar el contenedor de la secuencia.

Las publicaciones por secuencia se consideran una única publicación con respecto al límite de frecuencia de la cuenta.

Limitaciones

  • Las secuencias no se pueden promocionar.
  • Las secuencias están limitadas a 10 imágenes, vídeos o una combinación de ambos.
  • Todas las imágenes de secuencia se recortan en función de la primera imagen de la secuencia, y la relación de aspecto predeterminada es 1:1.

Paso 1 de 3: Crear el contenedor de elementos

Utiliza el extremo POST /{ig-user-id}/media a fin de crear un contenedor de elementos para la imagen o el vídeo que aparecerá en una secuencia. En total, las secuencias pueden tener hasta diez imágenes, vídeos o una combinación de ambos.

POST /{ig-user-id}/media

Parámetros

Los parámetros siguientes son obligatorios. Puedes consultar los demás parámetros admitidos en la referencia del extremo POST /{ig-user-id}/media.

  • is_carousel_item: definido como true. Indica que la imagen o el vídeo aparecerá en una secuencia.
  • image_url: (solo imágenes) ruta de la imagen. Aplicaremos cURL a la imagen mediante la URL pasada, por lo que se debe encontrar en un servidor público.
  • media_type: (solo vídeos) definido como VIDEO. Indica que el contenido multimedia es un vídeo.
  • video_url: (solo vídeos) ruta del vídeo. Aplicaremos cURL al vídeo mediante la URL pasada, por lo que se debe encontrar en un servidor público.

Si la operación se realiza correctamente, la API devolverá un identificador de contenedor del elemento que se puede usar al crear el contenedor de la secuencia.

Repite este proceso para cada imagen o vídeo que deba aparecer en la secuencia.

Ejemplo de solicitud

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?image_url=https%3A%2F%2Fsol...&is_carousel_item=true&access_token=EAAOc..."

Ejemplo de respuesta

{
  "id": "17899506308402767"
}

Paso 2 de 3: Crear el contenedor de secuencia

Utiliza el extremo POST /{ig-user-id}/media para crear un contenedor de secuencia.

POST /{ig-user-id}/media

Parámetros

Los parámetros siguientes son obligatorios. Puedes consultar los demás parámetros admitidos en la referencia del extremo POST /{ig-user-id}/media.

  • media_type: definido como CAROUSEL. Indica que el contenedor es para una secuencia.
  • children: una matriz de hasta 10 identificadores de contenedor de cada imagen y vídeo que debe aparecer en la secuencia publicada. En total, las secuencias pueden tener hasta 10 imágenes, vídeos o una combinación de ambos.

Ejemplo de solicitud

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media?caption=Fruit%20candies&media_type=CAROUSEL&children=17899506308402767%2C18193870522147812%2C17853844403701904&access_token=EAAOc..."

Ejemplo de respuesta

{
  "id": "18000748627392977"
}

Paso 3 de 3: Publicar el contenedor de secuencia

Utiliza el extremo POST /{ig-user-id}/media_publish para publicar el contenedor de secuencia (una publicación por secuencia). Las cuentas están limitadas a 50 publicaciones por cada periodo de 24 horas. La publicación de una secuencia se considera una única publicación.

POST /{ig-user-id}/media_publish

Parámetros

Los parámetros siguientes son obligatorios.

  • creation_id: identificador del contenedor de la secuencia.

Si la operación se realiza correctamente, la API devolverá un identificador de contenido multimedia de Instagram del álbum de la secuencia.

Ejemplo de solicitud

curl -i -X POST \

"https://graph.facebook.com/v20.0/90010177253934/media_publish?creation_id=18000748627392977&access_token=EAAOc..."

Ejemplo de respuesta

{
  "id": "90010778390276"
}

Publicaciones de reels

Los reels son vídeos breves que pueden aparecer en la pestaña Reels de la aplicación de Instagram si cumplen determinadas especificaciones y nuestro algoritmo los selecciona. Para publicar un reel, sigue los pasos de publicación de un único archivo multimedia y añade el parámetro media_type=REELS junto con la ruta del vídeo mediante el parámetro video_url.

Los reels no son un nuevo tipo de contenido multimedia, a pesar de que defines el parámetro media_type=REELS cuando publicas un reel. Si publicas un reel y, después, solicitas su campo media_type, el valor devuelto es VIDEO. Para determinar si un vídeo publicado se ha designado como reel, solicita el campo media_product_type en su lugar.

Puedes usar el código de ejemplo disponible en GitHub (insta_reels_publishing_api_sample) para obtener información sobre cómo publicar reels en Instagram.

A fin de que resulte más cómodo para los desarrolladores, Meta ha publicado el conjunto completo de llamadas a la API Graph para Instagram Reels en la plataforma de la API de Postman. Para obtener más información, consulta las colecciones de Postman para Facebook Reels e Instagram Reels.

Para obtener más información sobre reels, consulta la documentación para desarrolladores de reels.

Publicaciones de historias

Por el momento, solo las cuentas empresariales pueden publicar historias con la API de publicación de contenido.

Las historias son vídeos e imágenes que se publican como historias de Instagram en esta plataforma. Para publicar una historia, sigue los mismos pasos que para publicar un único archivo multimedia e incluye el parámetro media_type=STORIES junto con la ruta al vídeo o la imagen mediante el parámetro image_url o video_url.

Nota: Las historias no son un nuevo tipo de contenido multimedia a pesar de que defines el parámetro media_type=STORIES al publicar una historia. Si publicas una historia y, después, solicitas su campo media_type, el valor se devolverá como IMAGE/VIDEO. Para determinar si una imagen o vídeo publicado ha sido designado como historia, solicita el campo media_product_type en su lugar.

Protocolo de subida reanudable

El protocolo de subida reanudable es un nuevo proceso para la publicación de contenido en Instagram que admite las subidas de vídeos para los siguientes media_types: reels, historias de vídeo y elementos de secuencias de vídeos.

Este nuevo protocolo admite la creación de contenido multimedia para Instagram a partir de vídeos locales y vídeos de URL alojadas públicamente. El protocolo te permite reanudar operaciones de subida de archivos locales después de interrupciones en la red u otros fallos en la transmisión, lo que ahorra tiempo y ancho de banda en caso de fallos en la red. Se mantienen las mismas especificaciones del contenido multimedia.

Extremos

  • POST https://graph.facebook.com/{api-version}/{ig-user-id}/media: inicializar los contenedores de creación de vídeos especificando “upload_type=resumable”.
  • POST https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}: subir vídeos desde archivos de vídeo locales o de URL hospedadas de forma más fiable mediante el protocolo de subida reanudable.
  • POST https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish: publicar contenido multimedia subido mediante sus contenedores de contenido multimedia.
  • GET /{ig-container-id}?fields=status_code: comprobar la idoneidad y el estado de publicación de los contenedores de contenido multimedia.

Consejos para la codificación de URL HTML

  • Algunos parámetros se admiten en formato list/dict.
  • Algunos caracteres tienen que codificarse siguiendo un formato que pueda transmitirse por internet. Por ejemplo: user_tags=[{username:’ig_user_name’}] está codificado como user_tags=%5B%7Busername:ig_user_name%7D%5D, donde [ está codificado como %5B y { está codificado como %7B. Para ver más conversiones, consulta las normas de codificación de URL HTML.

Paso 1: Iniciar una sesión de subida para reels, historias de vídeo o elementos de secuencias

Ejemplo de solicitud para reels

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=REELS" \
    -d "upload_type=resumable" \
    -d "caption={caption}"\
    -d "collaborators={collaborators-username}"
    -d "cover_url={cover-url}" \
    -d "audio_name={audio-name}" \
    -d "user_tags={user-tags}" \
    -d "location_id={location-id}" \
    -d "thumb_offset={thumb-offset}" \
    -H "Authorization: OAuth {access-token}"

Ejemplo de solicitud para historias de vídeo

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=STORIES" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Ejemplo de solicitud para elementos de secuencias de vídeos

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=VIDEO" \
    -d "is_carousel_item=true" \
    -d "upload_type=resumable" \
    -H "Authorization: OAuth {access-token}"

Ejemplo de respuesta

{
   "id": "{ig-container-id}",
   "uri": "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}"
}

Paso 2: Subir el vídeo mediante el protocolo de subida reanudable

La mayoría de las llamadas a la API Graph utilizan el host graph.facebook.com. Sin embargo, las llamadas para subir vídeos para reels utilizan rupload.facebook.com.

Para la subida de archivos de vídeo se admiten los orígenes de archivos siguientes:

  • Archivos ubicados en el ordenador
  • Archivos alojados en un servidor orientado al público, como un CDN

Ejemplo de solicitud para subir un archivo de vídeo local

Sube el vídeo con el valor de ig-container-id devuelto en la llamada de la sesión de subida reanudable.

  • Asegúrate de que el host es rupload.facebook.com.
  • El proceso de subida del vídeo es el mismo sea cual sea el valor de media_type.
  • ig-container-id es el identificador devuelto en la llamada de la sesión de subida reanudable.
  • El valor de access-token es el mismo que se ha usado en los pasos anteriores.
  • offset se establece en el primer byte de la subida; normalmente, 0.
  • file_size se establece en el tamaño del archivo en bytes.
  • Your_file_local_path se establece en la ruta de archivo del archivo local. Por ejemplo, si se sube un archivo desde la carpeta de descargas en macOS, la ruta es @Downloads/example.mov.
curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "offset: 0" \
     -H "file_size: Your_file_size_in_bytes" \
     --data-binary "@my_video_file.mp4"

Ejemplo de solicitud para subir un vídeo alojado públicamente

curl -X POST "https://rupload.facebook.com/ig-api-upload/{api-version}/{ig-container-id}" \
     -H "Authorization: OAuth {access-token}" \
     -H "file_url: https://example_hosted_video.com"

Ejemplo de respuesta

// Success Response Message
{
  "success":true,
  "message":"Upload successful."
}

// Failure Response Message
{
  "debug_info":{
    "retriable":false,
    "type":"ProcessingFailedError",
    "message":"{\"success\":false,\"error\":{\"message\":\"unauthorized user request\"}}"
  }
}

Paso 3: Crear el contenedor de secuencia (solo para secuencias)

Puedes volver a realizar los Pasos 1 y 2 para crear varios ig-container-ids con el parámetro is_carousel_item establecido en true. A continuación, crea el contenedor de secuencia para incluir todos los elementos de secuencia, que pueden combinar imágenes y vídeos.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media" \
    -d "media_type=CAROUSEL" \
    -d "caption={caption}"\
    -d "collaborators={collaborator-usernames}" \
    -d "location_id={location-id}" \
    -d "product_tags={product-tags}" \
    -d "children=[{ig-container-id},{ig-container-id}...]" \
    -H "Authorization: OAuth {access-token}"

Paso 4: Publicar el contenido multimedia

En el caso de los reels y las historias de vídeo, se utiliza el {ig-container-id} creado en el Paso 1 para publicar el vídeo. Para publicar el contenedor de secuencia, se utiliza el valor de {ig-container-id} creado en el Paso 3.

curl -X POST "https://graph.facebook.com/{api-version}/{ig-user-id}/media_publish" \
    -d "creation_id={ig-container-id}" \
    -H "Authorization: OAuth {access-token}"

Paso 5: Obtener el estado del contenido multimedia

graph.facebook.com proporciona un extremo GET para leer el estado de la subida y el campo video_status contiene los detalles sobre el proceso de subida local.

  • El campo uploading_phase indica si el archivo se ha subido correctamente y cuántos bytes se han transferido.
  • El campo processing_phase contiene los detalles sobre el estado de procesamiento del vídeo una vez que este se ha subido.
// GET status from graph.facebook.com
curl -X GET "https://graph.facebook.com/v19.0/{ig-container-id}?fields=id,status,status_code,video_status" \
    -H "Authorization: OAuth {access-token}"

Ejemplo de respuesta del extremo graph.facebook.com

// A successfully created ig container
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "complete",
      "bytes_transferred": 37006904
    },
    "processing_phase": {
      "status": "complete"
    }
  }
}

// An interrupted ig container creation, from here you can resume your upload in step 2 with offset=50002. 
{
  "id": "{ig-container-id}",
  "status": "Published: Media has been successfully published.",
  "status_code": "PUBLISHED",
  "video_status": {
    "uploading_phase": {
      "status": "in_progress",
      "bytes_transferred": 50002
    },
    "processing_phase": {
      "status": "not_started"
    }
  }
}

Etiquetas de colaborador

Puedes añadir a usuarios públicos de Instagram a una imagen, una secuencia o un reel como colaboradores y recibirán una invitación para ser colaboradores de ese archivo multimedia específico. Para etiquetar a usuarios en una imagen, sigue los pasos descritos anteriormente en “Publicaciones con un único archivo multimedia”. No obstante, al crear el contenedor de archivos multimedia, incluye el parámetro “collaborators” y una matriz de cadenas en la que se indiquen los nombres de usuario de Instagram de los usuarios que quieres invitar como colaboradores del archivo multimedia.

Ejemplo de solicitud

POST graph.facebook.com/17841400008460056/media
?image_url=https://www.example.com/images/bronzed-fonzes.jpg
&caption=#BronzedFonzes!
&collaborators= [‘username1’,’username2’]

Notas

  • El valor de “collaborators” debe ser una matriz de cadenas.
  • Solo puedes etiquetar a los usuarios con cuentas de Instagram públicas.
  • Puedes añadir un máximo de tres colaboradores al archivo multimedia.
  • No se pueden añadir colaboradores a archivos multimedia de historias.

Etiquetas de ubicación

Puedes usar la API de búsqueda de páginas ; asegúrate de añadir el campo “location” a la consulta para buscar páginas cuyo nombre coincida con una cadena de búsqueda. A continuación, analiza los resultados para identificar las páginas que se hayan creado para una ubicación física. Si incluyes un identificador de página al publicar una imagen o un vídeo, se etiquetará con la ubicación asociada con la página.

Limitaciones

Para ser apta para las etiquetas, una página debe tener los datos de ubicación de latitud y longitud.

Verifica si la página que quieres usar tiene datos de latitud y longitud en la respuesta. Si se intenta crear un contenedor con una página que no tiene datos de ubicación, se producirá un error con el código de excepción INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Cuando tengas el identificador de página, asígnalo al parámetro location_id al publicar contenedores de elementos multimedia únicos o por secuencia.

Etiquetas de productos

Puedes realizar publicaciones con un único archivo multimedia y publicaciones por secuencia etiquetadas con productos de compras de Instagram. Consulta la guía Etiquetado de productos para obtener más información al respecto.

Etiquetas de usuario

Puedes etiquetar a usuarios públicos de Instagram en una imagen y recibirán una notificación que indica que los has etiquetado.

Para etiquetar a usuarios en una imagen, sigue los pasos descritos anteriormente en Publicaciones con un único archivo multimedia. No obstante, al crear el contenedor de archivos multimedia, incluye el parámetro user_tags y una matriz de objetos donde se indiquen los usuarios de Instagram de la imagen, así como sus coordenadas x/y en la imagen.

Ejemplo de solicitud

POST graph.facebook.com/17841400008460056/media ?image_url=https://www.example.com/images/bronzed-fonzes.jpg &caption=#BronzedFonzes! &user_tags= [ { username:'kevinhart4real', x: 0.5, y: 0.8 }, { username:'therock', x: 0.3, y: 0.2 } ] 

Esta solicitud devuelve un identificador de contenedor que, posteriormente, puedes publicar mediante el extremo de publicación de contenido multimedia del usuario de Instagram.

Notas

  • El valor de user_tags debe ser una matriz de objetos con formato JSON.
  • Solo puedes etiquetar a los usuarios con cuentas de Instagram públicas.
  • El objeto debe contener las tres propiedades (username, x y y) para cada usuario.
  • Los valores de x y y deben ser números de tipo float desde la esquina superior izquierda de la imagen, con un rango entre 0.0 y 1.0.
  • Las etiquetas de usuario se pueden usar con imágenes en secuencias.

Solución de problemas

Si puedes crear un contenedor para un vídeo, pero el extremo POST /{ig-user-id}/media_publish no devuelve el identificador del contenido multimedia publicado, puedes enviar una consulta al extremo GET /{ig-container-id}?fields=status_code para obtener el estado de publicación del contenedor. Este extremo devolverá una de las siguientes opciones:

  • EXPIRED: el contenedor no se ha publicado en 24 horas y ha caducado.
  • ERROR: el contenedor no ha completado el proceso de publicación.
  • FINISHED: el contenedor y su objeto de contenido multimedia están listos para publicarse.
  • IN_PROGRESS: el contenedor sigue en el proceso de publicación.
  • PUBLISHED: el objeto de contenido multimedia del contenedor se ha publicado.

Recomendamos enviar una consulta sobre el estado del contenedor por minuto durante un máximo de 5 minutos.

Errores

Consulta la referencia de códigos de error.