Facebook Stories API от Meta

В этом документе рассказывается, как использовать Facebook Stories API для публикации историй на Страницах Facebook.

Чтобы опубликовать историю, приложению нужно выполнить следующие действия:

1. Загрузить медиафайлы пользователя на серверы Meta.
2. Опубликовать медиафайлы пользователя на Странице как историю.

Прежде чем начать

Это руководство написано с расчетом, что вы ознакомились с обзором Pages API и реализовали необходимые компоненты, а также ознакомились с руководством по началу работы.

• Пользователям вашего приложения потребуется возможность выполнять действие CREATE_CONTENT на Странице, представляемой маркером доступа к Страницам. Кроме того, они должны будут дать вашему приложению следующие разрешения:

  • pages_manage_posts;
  • pages_read_engagement;
  • pages_show_list.

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

Требования к медиафайлам

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

Требования к фото

Требования к видео

Ограничения

• Фото или видео, загруженное для истории, не должно использоваться в ранее размещенной публикации.
• Максимальная продолжительность видеоистории: 60 секунд.
• Чтобы добавить в запрос GET на просмотр списка своих историй истории в архиве, включите архив историй Facebook

Рекомендации

Примеры кода в этом документе отформатированы для удобства чтения. Замените выделенный жирным шрифтом и курсивом текст, например page_id, собственными значениями.

Видеоистории

Чтобы опубликовать видеоисторию на Странице Facebook, вы должны инициализировать сеанс загрузки видео на серверах Meta, загрузить видео на серверы Meta и затем опубликовать видеоисторию.

Шаг 1. Инициализация сеанса

Чтобы инициализировать сеанс загрузки, отправьте запрос POST к конечной точке /page_id/video_stories, указав в качестве page_id ID вашей Страницы Facebook и задав для параметра upload_phase значение start.

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

curl -X POST "https://graph.facebook.com/v24.0/page_id/video_stories" \
      -d '{
           "upload_phase":"start",
         }'

В случае успеха ваше приложение получит ответ JSON с указанием ID видео и URL на Facebook, куда вы будете загружать это видео.

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

{
  "video_id": "video_id",
  "upload_url": "https://rupload.facebook.com/video-upload/v24.0/video_id",
}  

Шаг 2. Загрузка видео

Если вы инициализировали сеанс загрузки видео и получили URL для загрузки, можно загружать видео. Вы можете загрузить:

• видеофайл, размещенный в открытом доступе по адресу http/https, например в сети CDN;
• локальный видеофайл со своего устройства.

Загрузка файла из открытого доступа

Чтобы загрузить файл, размещенный в открытом доступе, отправьте запрос POST к конечной точке upload_url, полученной на этапе инициализации, со следующими параметрами:

• file_url (укажите в качестве значения URL вашего видеофайла).

Убедитесь, что используется хост rupload.facebook.com.

API теперь будет отклонять файлы, размещенные на сайтах, которые ограничивают доступ через robots.txt. Разработчикам необходимо убедиться, что сайт хостинга позволяет пользовательскому агенту "facebookexternalhit/1.1 (+http://www.facebook.com/externalhit_uatext.php)" извлекать размещенный файл.

Файлы, размещенные на Meta CDN (например, URL-адреса fbcdn), будут отклонены. Вместо этого разработчики могут использовать функцию кросспостинга для публикации видео на нескольких страницах, не загружая видео на каждую отдельно. Ознакомьтесь с нашим подробным руководством по кросспостингу.

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

curl -X POST "https://rupload.facebook.com/video-upload/v24.0/video_id" \
	-H "file_url: https://some.cdn.url/video.mp4"

Загрузка локального файла

Чтобы загрузить локальный файл, отправьте запрос POST к конечной точке upload_url, полученной на этапе инициализации, со следующими параметрами:

• offset (укажите значение 0);
• file_size (укажите в качестве значения общий размер загружаемого видео в байтах).

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

curl -X POST "https://rupload.facebook.com/video-upload/v24.0/video_id" \
	-H "offset: 0" \
        -H "file_size: file_size_in_bytes" \
	--data-binary "@/path/to/file/my_video_file.mp4"

В случае успеха ваше приложение получит ответ JSON, в котором параметр success будет иметь значение true.

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

{
    "success": true
}  

Прерывание загрузки

Если загрузка видео прерывается, вы можете продолжить или начать ее заново.

• Чтобы начать загрузку заново, отправьте запрос POST и задайте для параметра offset значение 0.
• Чтобы продолжить загрузку, отправьте новый запрос POST, указав в параметре offset значение bytes_transfered из проверки статуса видео.

Получение статуса загрузки

Чтобы проверить статус видео во время загрузки или публикации, отправьте запрос GET к конечной точке /video_id и укажите следующий параметр:

• fields (установите значение status).

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

curl -X GET "https://graph.facebook.com/v24.0/video_id" \
	-d "fields=status"

В случае успеха приложение получит ответ JSON с перечисленными далее объектами.

• status, который содержит:

  • video_status со значением ready, processing, expired или error;
  • uploading_phase со следующими парами "ключ-значение":

    • status со значением in_progress, not_started, complete или error;
    • bytes_transfered, в котором указано, сколько байт было загружено (его можно использовать в параметре offset, если загрузка была прервана);
  • processing_phase со следующими парами "ключ-значение":

    • status со значением in_progress, not_started, complete или error;
  • processing_phase со следующими парами "ключ-значение":

    • status со значением in_progress, not_started, complete или error;
    • publish_status со значением published или not_published;
    • publish_time с меткой текущего времени или времени публикации (в формате UNIX).

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

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "in_progress", 
      "bytes_transfered": 50002 
    },
    "processing_phase": {
      "status": "not_started"
    }
    "publishing_phase": {
      "status": "not_started",
      "publish_status": "published",
      "publish_time": 234523452 
    }
  }
}

{
  "status": {
    "video_status": "processing", 
    "uploading_phase": {
      "status": "complete"
    },
    "processing_phase": {
      "status": "not_started",
      "error": {
        "message": "Resolution too low. Video must have a minimum resolution of 540p."
      }
    }
    "publishing_phase": {
      "status": "not_started"
    }
  }
}

Шаг 3. Публикация видеоистории

Чтобы опубликовать видеоисторию на своей Странице, отправьте запрос POST к конечной точки /page_id/video_stories, указав следующие параметры:

• video_id (укажите в качестве значения ID своего загруженного видео);
• upload_phase (укажите значение finish).

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

curl -X POST "https://graph.facebook.com/v24.0/page_id/video_stories" \
      -d '{
           "video_id": "video_id",
           "upload_phase": "finish"
         }'

В случае успеха приложение получит ответ JSON, содержащий следующие пары "ключ-значение":

• success со значением true;
• post_id с ID вашей опубликованной истории.

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

{
  "success": true,
  "post_id": 1234
}

Фотоистории

Шаг 1. Загрузка фото

Чтобы узнать, как загрузить фото на серверы Meta с помощью конечной точки /page_id/photos, ознакомьтесь с руководством по публикации на Странице . Не забудьте указать параметр published и установить для него значение false.

Шаг 2. Публикация фотоистории

Чтобы опубликовать фотоисторию на своей Странице, отправьте запрос POST к конечной точке /page_id/photo_stories, указав следующие параметры:

• photo_id (укажите в качестве значения ID своего загруженного фото).

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

curl -X POST "https://graph.facebook.com/v24.0/page_id/photo_stories" \
      -d '{
           "photo_id": "photo_id"
         }'

В случае успеха приложение получит ответ JSON, содержащий следующие пары "ключ-значение":

• success со значением true;
• post_id с ID вашей опубликованной истории.

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

{
  "success": true,
  "post_id": 1234
}

Получение историй

Чтобы получить список всех историй Страницы и данные о каждой истории, отправьте запрос GET к конечной точке /page_id/stories, подставив в качестве page_id ID нужной Страницы.

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

    
curl -i -X GET "https://graph.facebook.com/v24.0/page_id/stories"

В случае успеха приложение получит ответ JSON с массивом объектов, в котором каждый объект будет содержать информацию об опубликованной на Странице истории. Каждый объект содержит следующие пары "ключ-значение":

• post_id с ID вашей опубликованной истории;
• status со значением PUBLISHED или ARCHIVED;
• creation_time с меткой времени публикации истории (в формате UNIX);
• media_type со значением video или photo;
• media_id с ID видео или фото в истории;
• url с URL Facebook, по которому размещена история, например https://facebook.com/stories/8283482737484972.

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

{
  "data": [
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "video",
      "media_id": "video_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "PUBLISHED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    {
      "post_id": "post_id",
      "status": "ARCHIVED",
      "creation_time": "123456",
      "media_type": "photo",
      "media_id": "photo_id",
      "url": "https://facebook.com/stories…"
    },
    ...
  ],
}

Истории можно фильтровать по статусу (опубликована или помещена в архив) и дате с помощью параметров since и until.

См. также

Ознакомьтесь с дополнительной информацией о конечных точках и понятиях, упоминаемых в этом руководстве.

Руководства

• Системный пользователь компании
• Вход через Facebook
• Вход через Facebook для компаний
• Graph API — разбиение результатов на страницы с помощью параметров since и until

Справка по конечным точкам

• Справка по Страницам
• Справка по видеоисториям Страниц
• Справка по фотоисториям Страниц
• Справка по видео
• Справка по статистике историй