API однократных уведомлений (бета-версия)

Краткие сведения

API One-Time Notification (бета-версия) платформы Messenger позволяет странице запросить у пользователя разрешение на отправку ему одного дополнительного сообщения по прошествии 24-часового окна отправки. Пользователю будет предложена возможность получить уведомление. Если он даст свое согласие, страница получит маркер — эквивалент разрешения на отправку пользователю одного сообщения. Этот маркер можно использовать только один раз. Срок его действия составляет один год с момента создания.

Разрешения

Страницам, которые хотят использовать этот API, нужно подать заявку на разрешение «Однократное уведомление» в разделе «Расширенный обмен сообщениями» настроек Страницы. От имени страницы нужно будет принять условия бета-тестирования. Если необходимые условия выполняются, она получит соответствующее разрешение.

Содержание

• Использование
• Отправка запроса на однократное уведомление
• Отправка дополнительного сообщения
• События Webhooks
• Ограничения

Использование

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

Отправка запроса на однократное уведомление

С помощью API Send страница может направить запрос на отправку уведомления на базе шаблона. Используйте шаблон one_time_notif_req. Запрос должен выполняться в формате, стандартном для всех типов шаблонов. В свойстве message.attachment.payload необходимо указать сведения о типе и контенте для шаблона соответствующего типа. Изменения разрешается вносить только в заголовок и полезные данные шаблона. Максимальная длина поля title — 65 символов.

{
  "recipient": {
    "id":"

Пользователь увидит шаблонный запрос на однократное уведомление. Если он нажмет кнопку «Сообщить мне», то в вашу систему будет отправлен Webhooks message_optins, после чего вы сможете направить пользователю одно дополнительное сообщение по прошествии 24-часового окна, используя one_time_notif_token.

Отправка дополнительного сообщения

Чтобы отправить дополнительное сообщение, выполните запрос POST к API Send, используя полученный через Webhooks маркер one_time_notif_token и указав в теле запроса текст сообщения message.text:

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "one_time_notif_token":"<ONE_TIME_TOKEN>"
  },
  "message": {
    "text":"<MESSAGE_CONTENT>"
  }
}' "https://graph.facebook.com/v21.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Чтобы отправить сообщение с форматированным текстом, замените простой текст в теле запроса форматированным. Полный список поддерживаемых типов сообщений см. в справке по API Send. Маркер one_time_notif_token можно использовать только один раз. Он перестает действовать после успешной отправки сообщения.

События Webhooks

Если пользователь согласится на получение уведомлений по определенной теме, вы получите событие Webhooks с параметрам payload и one_time_notif_token. Сохраните полезные данные и маркер для отправки дополнительного сообщения. Обратите внимание, что запросить список маркеров one_time_notif_token через API вы не сможете, поэтому необходимо надлежащим образом принять и сохранить полученные данные Webhooks. Каждый маркер можно использовать только один раз. Срок его действия составляет один год с момента создания.

{
   "sender": {
     "id":"<PSID>"
   },
   "recipient": {
     "id":"<PAGE_ID>"
   },
   "timestamp":1458692752478,
   "optin": {
     "type": "one_time_notif_req",
     "payload": "<USER_DEFINED_PAYLOAD>",
     "one_time_notif_token":"<ONE_TIME_TOKEN>",
   }
}

Ограничения

• Не используйте поле полезных данных для отправки паролей, учетных данных, информации, которая позволяет идентифицировать пользователей (например, имени или адреса электронной почты, т. е. сведений, по которым можно связаться с человеком или установить его личность) и других конфиденциальных данных (информации о состоянии здоровья, финансовых сведений, платежных данных, реквизитов банковских карт и информации других категорий, которая считается конфиденциальной согласно действующему законодательству).
• Из соображений удобства пользователей для отправки запросов на однократное уведомление может действовать ограничение числа обращений.

Часто задаваемые вопросы

Дополнительные сведения см. на нашей странице с часто задаваемыми вопросами.