Публикация контента

Вы можете использовать API Graph для Instagram, чтобы размещать публикации с одним изображением, с одним видео или с одним видео Reels (т. е. публикации с одним медиафайлом) либо публикации, содержащие несколько изображений или видео (кольцевые галереи), в профессиональных аккаунтах Instagram.

C 1 июля 2023 г. все публикации с одним видео, размещенные через API Content Publishing Instagram, будут публиковаться как видео Reels.

Требования

Маркеры доступа

В каждом запросе должен быть указан маркер доступа пользователя приложения.

Разрешения

Для публикации требуется сочетание перечисленных ниже разрешений, которое зависит от конечных точек, используемых вашим приложением. Разрешения для каждой конечной точки см. в справке по конечным точкам.

Если приложением будут пользоваться люди, не имеющие роли в нем или в компании, которой оно принадлежит, то все разрешения, используемые в этом приложении, должны быть одобрены в ходе проверки.

Общедоступный сервер

Мы создаем cURL медиаобъекта, используемого при попытках публикации, поэтому в момент публикации медиафайлы должны быть размещены на общедоступном сервере.

Авторизация для публикации на Странице

Если профессиональный аккаунт Instagram подключен к Странице, которая требует авторизации для публикаций на Странице, необходимо сначала пройти ее.

Возможна ситуация, когда для Страницы, на которой пользователь может выполнять задачи, авторизация изначально не требовалась, но затем стала необходима. В этом случае пользователь не сможет публиковать контент в своем профессиональном аккаунте Instagram, пока не пройдет авторизацию. Так как невозможно узнать заранее, требуется ли авторизация для публикации на Странице пользователя приложения, рекомендуется советовать всем пользователям пройти ее.

Ограничения

Изображения могут иметь только формат .jpeg. Расширенные форматы .jpeg, такие как .mpo и .jps, не поддерживаются.
Метки товаров не поддерживаются.
Метки брендированного контента не поддерживаются.
Фильтры не поддерживаются.
Публикация в Instagram TV не поддерживается.

Дополнительные ограничения см. в справке по каждой конечной точке.

Ограничение числа обращений

Для аккаунтов Instagram действует ограничение количества публикаций через API: не более 50 публикаций в течение 24 часов. Кольцевые галереи считаются одной публикацией. Это ограничение применяется при публикации контейнеров медиаобъектов через конечную точку POST /{ig-user-id}/media_publish. Желательно, чтобы ваше приложение также ограничивало количество публикаций, особенно если оно позволяет пользователям планировать их размещение в будущем.

Чтобы проверить состояние ограничения в профессиональном аккаунте Instagram, выполните запрос к конечной точке GET /{ig-user-id}/content_publishing_limit.

Конечные точки

Этот API включает в себя перечисленные ниже конечные точки. Информацию о требованиях для использования каждой из них см. в соответствующей документации.

POST /{ig-user-id}/media — загрузка медиаобъектов и создание их контейнеров.
POST /{ig-user-id}/media_publish — публикация загруженных медиаобъектов с помощью их контейнеров.
GET /{ig-container-id}?fields=status_code — проверка возможности и состояния публикации контейнера медиаобъекта.
GET /{ig-user-id}/content_publishing_limit — проверка текущего состояния ограничения числа обращений к публикации для пользователя приложения.

Публикации с одним медиаобъектом

Публикация с одним изображением, видео, историей или Reels происходит в два этапа:

Использование конечной точки POST /{ig-user-id}/media для создания контейнера из изображения или видео, размещенного на вашем общедоступном сервере.
Использование конечной точки POST /{ig-user-id}/media_publish для публикации контейнера.

Этап 1 из 2: Создание контейнера

Предположим, у вас есть изображение

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

...которое вы хотите опубликовать с хэштегом #BronzFonz в качестве подписи. Отправьте запрос к конечной точке POST /{ig-user-id}/media.

Пример запроса

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

Он возвращает ID для изображения.

Пример ответа

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

Этап 2 из 2: Публикация контейнера

Используйте конечную точку POST /{ig-user-id}/media_publish для публикации ID контейнера, возвращенного в предыдущем шаге.

Пример запроса

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

Пример ответа

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

Публикации с кольцевыми галереями

Вы можете публиковать до 10 изображений, видео или сочетания этих двух типов файлов в одной публикации (публикации с кольцевыми галереями) Публикация кольцевых галерей происходит в три этапа:

Использование конечной точки POST /{ig-user-id}/media для создания отдельных контейнеров объектов для каждого изображения или видео, которые появятся в кольцевой галерее.
Повторное использование конечной точки POST /{ig-user-id}/media для создания отдельного контейнера кольцевой галереи для объектов.
Использование конечной точки POST /{ig-user-id}/media_publish для публикации контейнера кольцевой галереи.

При учете ограничения числа обращений публикации кольцевых галерей считаются одной публикацией.

Ограничения

Кольцевые галереи нельзя продвигать.
В кольцевых галереях может быть до 10 изображений и видео.
Все изображения в кольцевых галереях обрезаются в соответствии с первым изображением в ней, а по умолчанию используется соотношение сторон 1:1.

Этап 1 из 3: Создание контейнера объекта

Используйте конечную точку POST /{ig-user-id}/media, чтобы создать контейнер объекта для изображения или видео, которое появится в кольцевой галерее. В кольцевых галереях может быть до 10 изображений и видео.

POST /{ig-user-id}/media

Параметры

Следующие параметры являются обязательными. Информацию о дополнительных поддерживаемых параметрах см. в справке по конечной точке POST /{ig-user-id}/media.

is_carousel_item — установить как true. Задает изображение или видео, которое появится в кольцевой галерее.
image_url — (только изображения) Путь к изображению. Мы создаем cURL изображения на основе переданного URL, поэтому он должен указывать на общедоступный сервер.
media_type — (только видео) установить как VIDEO. Указывает, что медиаобъект — это видео.
video_url — (только видео) путь к видео. Мы создаем cURL видео на основе переданного URL, поэтому он должен указывать на общедоступный сервер.

Если операция выполнена успешно, API предоставит ID контейнера объекта, который может быть использован при создании контейнера кольцевой галереи.

Повторите этот процесс для каждого изображения или видео, которое должно появиться в кольцевой галерее.

Пример запроса

curl -i -X POST \

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

Пример ответа

{
  "id": "17899506308402767"
}

Этап 2 из 3: Создание контейнера кольцевой галереи

Используйте конечную точку POST /{ig-user-id}/media, чтобы создать контейнер кольцевой галереи.

POST /{ig-user-id}/media

Параметры

media_type — установить как CAROUSEL. Указывает контейнер для кольцевой галереи.
children — массив не более чем из 10 ID контейнеров каждого изображения и видео, которые должны появиться в публикуемой кольцевой галерее. В кольцевых галереях может быть до 10 изображений и видео.

Пример запроса

curl -i -X POST \

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

Пример ответа

{
  "id": "18000748627392977"
}

Этап 3 из 3: Публикация контейнера кольцевой галереи

Используйте конечную точку POST /{ig-user-id}/media_publish, чтобы опубликовать контейнер кольцевой галереи (публикация кольцевой галереи). В аккаунтах можно разместить не более 50 публикаций за каждые 24 часа. Публикация кольцевой галереи считается одной публикацией.

POST /{ig-user-id}/media_publish

Параметры

Следующие параметры являются обязательными.

creation_id — ID контейнера кольцевой галереи.

Если операция выполнена успешно, API предоставит ID IG Media альбома кольцевой галереи.

Пример запроса

curl -i -X POST \

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

Пример ответа

{
  "id": "90010778390276"
}

Публикации видео Reels

Видео Reels — это видеоролики короткого формата, которые могут появляться на вкладке Reels в приложении Instagram, если они соответствуют определенным спецификациям и выбраны нашим алгоритмом. Чтобы опубликовать видео Reels, выполните те же действия, что и для размещения публикации с одним медиаобъектом, и добавьте параметр media_type=REELS вместе с указанием пути к видео, используя параметр video_url.

Reels — это не новый тип медиафайлов, хотя при публикации видео Reels вы и указываете параметр media_type=REELS. Если вы опубликуете видео Reels, а затем запросите его поле media_type, будет возвращено значение VIDEO. Чтобы определить, был ли опубликованный видеоролик обозначен как видео Reels, запросите его поле media_product_type.

Чтобы узнать, как публиковать видео Reels в Instagram, воспользуйтесь примером кода на GitHub (insta_reels_publishing_api_sample).

Для удобства разработчиков мы опубликовали полный список вызовов API Graph для видео Reels в Instagram на платформе API Postman. Подробнее см. в статье Подборки Postman для видео Reels на Facebook и в Instagram.

Подробнее о Reels см. в документации по видео Reels для разработчиков.

Публикации историй

В настоящий момент публиковать истории с помощью Content Publising API могут только бизнес-аккаунты.

Истории — это видеоролики или изображения, которые публикуются как истории в Instagram. Чтобы опубликовать историю, выполните те же действия, что и для размещения публикации с одним медиаобъектом, добавьте параметр media_type=STORIES и укажите путь к изображению или видео в параметре image_url или video_url.

Примечание. Истории — это не новый тип медиафайлов, хотя при публикации истории вы и указываете параметр media_type=STORIES. Если вы опубликуете историю, а затем запросите ее поле media_type, будет возвращено значение IMAGE/VIDEO. Чтобы определить, было ли опубликованное видео или изображение обозначено как история, рекомендуется запросить его поле media_product_type.

Метки соавтора

Вы можете добавить пользователей Instagram с открытым профилем в качестве соавторов изображения, кольцевой галереи или видео Reels. Эти пользователи получат приглашения стать соавтором для этого конкретного медиаобъекта. Чтобы отметить пользователей на изображении, выполните действия, перечисленные выше в пункте "Публикации с одним медиаобъектом", но при создании контейнера медиаобъекта укажите в параметре collaborators массив строк с именами пользователей Instagram, которых вы хотите пригласить в качестве соавторов для этого медиаобъекта.

Пример запроса

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

Примечания

Значением параметра collaborators должен быть массив строк.
Отмечать можно только пользователей с общедоступными аккаунтами Instagram.
На один медиаобъект можно добавить не более 3 соавторов.
Соавторов нельзя добавлять в медиаобъекты историй.

Метки геоданных

Вы можете использовать Pages Search API . Обязательно добавьте в свой запрос поле 'location' для поиска Страниц, названия которых соответствуют строке поиска. Затем обработайте результаты и определите все Страницы, созданные для физического местоположения. Если при публикации изображения или видео указать ID такой Страницы, к этому медиаобъекту будет добавлена соответствующая геометка.

Ограничения

Чтобы Страницу можно было отметить, ее данные о местоположении должны содержать широту и долготу.

Убедитесь, что в ответе для Страницы, которую вы хотите использовать, указаны широта и долгота. Если при создании контейнера вы попытаетесь указать Страницу без геоданных, возникнет исключение INSTAGRAM_PLATFORM_API__INVALID_LOCATION_ID.

Как только вы получите ID Страницы, назначьте его параметру location_id при публикации контейнеров объектов с одним медиафайлом или кольцевой галереи.

Метки товаров

Ставить метки товаров Instagram Shopping можно как в публикациях с одним медиафайлом, так и в кольцевых галереях. Подробнее см. в руководстве по работе с метками товаров.

Метки пользователей

Вы можете отметить на изображении пользователей с общедоступными аккаунтами Instagram, после чего они получат уведомление о том, что их отметили.

Чтобы отметить пользователей на изображении, выполните шаги, приведенные выше в пункте Публикации с одним медиаобъектом, но при создании контейнера медиаобъекта укажите параметр user_tags и массив объектов с отмеченными пользователями Instagram и их координатами X/Y на изображении.

Пример запроса

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 } ]

Будет получен ID контейнера, который затем можно опубликовать с использованием конечной точки Публикация медиаобъектов для IG User.

Примечания

Значением user_tags должен быть массив объектов в формате JSON.
Отмечать можно только пользователей с общедоступными аккаунтами Instagram.
Объект должен содержать все три свойства (username, x и y) для каждого пользователя.
Значения x и y должны быть числами с плавающей запятой (float) в диапазоне от 0.0 до 1.0 и отсчитываться от левого верхнего угла изображения.
Пользователей можно отмечать на изображениях в кольцевых галереях.

Устранение неполадок

Если вы создали контейнер для видео, но конечная точка POST /{ig-user-id}/media_publish не возвращает ID опубликованного медиафайла, выполните запрос к конечной точке GET /{ig-container-id}?fields=status_code, чтобы узнать статус публикации. Вы можете получить следующие значения:

EXPIRED — контейнер не был опубликован в течение 24 часов и больше не действителен;
ERROR — контейнер не удалось опубликовать из-за ошибки;
FINISHED — контейнер с медиаобъектом готов к публикации;
IN_PROGRESS — процесс публикации контейнера ещё идет;
PUBLISHED — медиаобъект опубликован.

Мы рекомендуем запрашивать статус публикации раз в минуту в течение максимум пяти минут.

Ошибки

См. справку по кодам ошибок.