Facebook Stories API от Meta

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

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

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

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

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

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

• Пользователям вашего приложения потребуется возможность выполнять действие 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/v21.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/v21.0/video_id",
}  

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

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

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

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

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

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

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

curl -X POST "https://rupload.facebook.com/video-upload/v21.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/v21.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/v21.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/v21.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/v21.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/v21.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

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

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