Начало работы

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

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

Вам понадобятся:

• профессиональный аккаунт Instagram;
• Страница Facebook, связанная с этим аккаунтом;
• аккаунт разработчика Meta, который может выполнять MODERATE задачу на соответствующей Странице;
• Приложение Meta, которое создано со сценарием использования входа через Facebook и для которого заданы базовые настройки.

Для разработчиков, еще не знакомых с платформой Messenger

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

Для разработчиков с опытом использования платформы Messenger

• Понятия маркеров доступа и Webhooks похожи. Для поддержки Instagram в API Messenger требуется разрешение instagram_manage_messages для маркера доступа к Странице и подписка на Webhooks в разделе Instagram.
• Большинство функций аналогичны API Messenger. Ознакомьтесь с их описаниями в списке и реализуйте те, которые вам нужны.

Процесс входа

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

В процессе входа в Instagram от имени компании пользователь может:

• преобразовать свой аккаунт в профессиональный аккаунт Instagram;
• создать Страницу Facebook для своей компании;
• связать свою Страницу с профессиональным аккаунтом Instagram.

Информацию о том, как реализовать вход в Instagram от имени компании, см. в нашем руководстве , после чего вернитесь к этому руководству.

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

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

Запустив модальное окно, нажмите ОК, чтобы предоставить приложению разрешения instagram_basic, instagram_manage_messages и pages_manage_metadata.

API вернет маркер доступа пользователя. Сохраните его, чтобы приложение могло использовать маркер в следующих запросах. Если вы используете Graph API Explorer, маркер сохранится автоматически и будет отображаться в поле "маркер доступа".

2. Получение Страниц пользователя

Отправьте запрос к конечной точке GET /me/accounts (он преобразуется в вид GET /{user-id}/accounts, т. е. запрос GET отправляется к узлу User Facebook для вашего маркера доступа).

curl -i -X GET \
 "https://graph.facebook.com/v9.0/me/accounts?access_token={access-token}"

Запрос должен вернуть подборку Страниц Facebook, на которых текущий пользователь Facebook может выполнять задачи MANAGE, CREATE_CONTENT, MODERATE или ADVERTISE:

{
  "data": [
    {
      "access_token": "EAAJjmJ...",
      "category": "App Page",
      "category_list": [
        {
          "id": "2301",
          "name": "App Page"
        }
      ],
      "name": "Metricsaurus",
      "id": "134895793791914",  // capture the Page ID
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ]
}

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

3. Получение маркера доступа к Странице

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

Отправьте запрос GET к конечной точке /{page-id} с указанием маркера доступа пользователя. Пример:

curl -i -X GET "https://graph.facebook.com/{page-id}?
  fields=access_token&
  access_token={user-access-token}"  

В случае успеха приложение получит следующий ответ:

{
  "access_token":"{page-access-token}",
  "id":"{page-id}"              
}  

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

Чтобы сгенерировать долгосрочный маркер доступа к Странице, воспользуйтесь этими инструкциями.

3a. Получение маркера доступа к Странице через инструмент панели разработчика Instagram

Если вам принадлежат объекты (аккаунт Instagram и Страница Facebook), которые вы хотите подключить для поддержки Instagram в API Messenger, вы можете воспользоваться инструментом настройки Instagram на панели приложений разработчика, позволяющим легко сконфигурировать маркеры доступа к Странице и Webhooks. Этот инструмент находится на панели приложений разработчика в разделе Messenger → "Настройки Instagram". Текущий способ настройки маркеров и Webhooks также работает, однако этот инструмент упрощает настройку среды.

4. Включение связанных инструментов в настройках управления сообщениями

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

5. Получение объектов из входящих сообщений профессионального аккаунта Instagram

Отправьте запрос к конечной точке GET /{page-id}/conversations?platform=instagram, указав сохраненный ранее ID страницы и маркер доступа к Странице:

curl -i -X GET \
 "https://graph.facebook.com/v9.0/17841405822304914/conversations?platform=instagram&access_token={access-token}"  

Запрос должен вернуть ID всех объектов переписки для этого пользователя Instagram.

{
  "data": [
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTM2MDk5MDc1MzYyOTgx"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTYzMzQ2MzE5NjM1NDcy"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MTk3MTY0NjI2NzAyMjMw"
    },
    {
      "id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6OTAwMTAxNDYyOTkyODI6MzQwMjgyMzY2ODQxNzEwMzAwOTQ5MTI4MzkzNDI5MDYzMzkyNjU0"
    }
}

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

Дальнейшие действия

• Продолжайте разработку приложения и реализуйте работу со всеми необходимыми ему конечными точками с учетом разрешений, которые нужны для каждой из них.
• Настройте объекты Webhooks, чтобы в режиме реального времени получать уведомления каждый раз, когда пользователь отправляет сообщение профессиональному аккаунту Instagram.
• Пройдите проверку приложения и запросите для него все необходимые разрешения, которые пользователи смогут предоставлять ему в рабочем режиме.