Платформа Messenger

Conversations API для платформы Messenger

В этом документе описано, как получать информацию о переписках в Messenger и Instagram. Вы можете получить:

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

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

Для прохождения курса необходимо ознакомиться с обзором платформы Messenger и возможностями обмена сообщениями в Instagram, а также реализовать нужные компоненты.

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

  • ID Страницы Facebook вашей компании или Страницы Facebook, связанной с вашим профессиональным аккаунтом Instagram;
  • маркер доступа к Странице, запрошенный у пользователя, который может выполнять действие MESSAGING или MODERATE на Странице;
  • расширенный доступ к перепискам вашей компании с пользователями, у которых нет роли в вашем приложении для обмена сообщениями, а также вашему профессиональному аккаунту Instagram, вашей Странице Facebook или Странице вашей компании.

Для получения переписок в Messenger между компанией и пользователями вашему приложению понадобятся:

Для получения переписок в Instagram между вашим профессиональным аккаунтом Instagram и пользователями вашему приложению понадобятся:

  • маркер доступа к Странице от пользователя, способного выполнять задачу MESSAGING на Странице, которая связана с вашим бизнес-аккаунтом Instagram;
  • разрешения instagram_basic, instagram_manage_messages и pages_manage_metadata;
  • владельцем вашего приложения должна быть подтвержденная компания.

Ограничения

  • В данные, возвращаемые в ответе API, или в уведомление Webhooks добавляется только URL для публикации изображения или видео.
  • Если ваши аккаунты связаны с помощью закрытых ключей, например электронного адреса или номера телефона, вы не сможете получить переписки этих аккаунтов. Доступны только переписки между пользователем Facebook и одним аккаунтом Instagram. Эта проблема устраняется, когда ваше приложение получает одобрение на расширенный доступ. Если у вас есть несколько аккаунтов, связанных в Центре аккаунтов приложения Instagram, вы можете получить переписки всех этих аккаунтов.
  • Переписки в папке "Запросы", которые остаются неактивными в течение 30 дней, не будут возвращаться в вызовах API.

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

Получение списка переписок

Чтобы получить список переписок, отправьте запрос GET к конечной точке /PAGE-ID/conversations и задайте для параметра platform значение instagram или messenger.

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

Для удобства чтения применено форматирование.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

В случае успеха ваше приложение получит объект JSON со списком ID переписок между вами и пользователем, а также датой последнего сообщения.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

Поиск переписки с определенным пользователем

Чтобы получить переписку между вашим профессиональным аккаунтом Instagram или Страницей Facebook и конкретным человеком, отправьте запрос GET к конечной точке /PAGE-ID/conversations с параметрами platform и user_id, указав ID в Instagram (IGSID) или ID внутри страницы (PSID) этого человека.

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

Для удобства чтения применено форматирование.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

В случае успеха ваше приложение получит ID переписки.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

Получение списка сообщений переписки

Чтобы получить список сообщений переписки, отправьте запрос GET к конечной точке messages с полем /CONVERSATION-ID.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

В случае успеха ваше приложение получит список ID сообщений и время создания каждого из них.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

Получение информации о сообщении

Чтобы получить информацию о сообщении, например имя получателя, отправителя и контент сообщения, отправьте запрос GET к конечной точке /MESSAGE-ID и укажите нужные поля.

Поля по умолчанию: id и created_time.

Примечание. Запросы к конечной точке /CONVERSATION-ID возвращают ID всех сообщений в переписке. Однако запросить данные можно только для 20 последних сообщений. Если вы запросите сообщение, которое не входит в последние 20, то получите ошибку с информацией о том, что сообщение удалено . 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

В случае успеха приложение получит следующий ответ в формате JSON. В этом примере клиент отправляет текстовое сообщение вашему профессиональному аккаунту Instagram.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

Дополнительная информация

Справочные материалы:

Поддержка разработчиков