Платформа Messenger

Справка по Send API

Send API — это основной API для отправки пользователям сообщений: текста, вложений, шаблонов, действий отправителя и т. д.

Создание

Создавайте и отправляйте сообщения клиентам или людям, проявившим интерес к вашей Странице Facebook.

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

Вам потребуются:

  • Маркер доступа к Странице, запрошенный человеком, который может выполнить задачу MESSAGE на Странице
  • Разрешение pages_messaging
  • Получатель сообщения должен отправить вашей Странице сообщение в течение последних 24 часов или согласился получать сообщения от вашей Страницы за пределами стандартного 24-часового окна

Ограничения

  • Метки сообщения нельзя использовать для отправки рекламного контента

API Send не включает recipient_id в ответ на сообщения, отправленные с помощью recipient.user_ref или recipient.phone_number , для определения получателя сообщения.

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

Чтобы отправить сообщение человеку, отправьте запрос POST конечной точке /PAGE-ID/messsages с параметрами messaging_type и recipient и содержимым сообщения.

Форматировано для улучшения читаемости.

Следующий пример — это отправленный вашей Страницей ответ, который содержит только текст.

curl -i -X POST "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/messages
    ?recipient={'id':'PSID'}
    &messaging_type=RESPONSE
    &message={'text':'hello,world'}
    &access_token=PAGE-ACCESS-TOKEN

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

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
}

Параметры

ПараметрОписание

message

object

Тип сообщения, которое отправляет ваша Страница. При использовании этого параметра нужно настроить text, либо attachement.

  • Объект attachment — обеспечивает предпросмотр URL. Используется для отправки сообщений с медиафайлами или структурированных сообщений. Необходимо настроить text или attachment.

    • type — тип вложения. Значение может быть audio, file, image, template или video. Максимальный размер файла — 25 МБ.
    • payload — объект, содержащий контент шаблона или файла

  • metadata — строка дополнительных данных, которые вы хотите передать в webhook message_echo. Менее 1000 символов.

  • quick_replies — массив быстрых ответов для отправки в сообщении
  • text — сообщение, содержащее только текст. UTF-8 и менее 2000 символов.

messaging_type

enum

Обязательный

Тип отправляемого сообщения

  • RESPONSE — сообщение отправляется в ответ на другое сообщение. Это могут быть рекламные или обычные сообщения, отправленные в стандартный 24-часовой период. Например, если пользователь запрашивает подтверждение резерва или обновление статуса, используйте эту метку в ответном сообщении.
  • UPDATE — сообщение отправляется заранее и не является ответом на полученное сообщение. Это могут быть рекламные или обычные сообщения, отправленные в стандартный 24-часовой период.
  • MESSAGE_TAG — сообщение не является рекламным и отправляется вне стандартного 24-часового периода с меткой сообщения. Такое сообщение следует отправлять только в ситуациях, которые подразумевает эта метка.

notification_type

enum

Тип push-уведомления, которое получает человек

  • NO_PUSH — без уведомлений
  • REGULAR (по умолчанию) — звук или вибрация в момент получения сообщения
  • SILENT_PUSH — только уведомления на экране

recipient

object

Обязательно

Получатель сообщения от вашей Страницы

  • id — PSID пользователя, используемый для ответа на сообщение, полученное вашей Страницей в последние 24 часа, или для связи с человеком, который согласился получать сообщения от вашей Страницы за пределами стандартного 24-часового окна
  • user_ref — ссылка на пользователя, предназначенная для отправки сообщения тому, кто воспользовался плагином для установки флажков или плагином чата с клиентами
  • comment_id — идентификатор комментария, предназначенный для отправки сообщения в качестве личного ответа на комментарий посетителя к публикации вашей Страницы
  • post_id — идентификатор публикации Страницы, предназначенный для отправки сообщения в качестве личного ответа на публикацию посетителя на вашей Странице

sender_action

enum

Значок действия в окне переписки, обозначающий выполненное Страницей действие с сообщением, которое Страница получила от человека.

  • typing_on — показывать значок ввода текста, когда Страница пишет ответ
  • typing_off — не показывать значок ввода текста
  • mark_seen — показывать значок просмотра для сообщений, которые были просмотрены Страницей

Можно отправлять только с параметром recipient. Нельзя отправлять с параметром message, но необходимо отправлять как отдельный запрос.

tag

enum

Метка, позволяющая вашей Странице отправить сообщение человеку за пределами стандартного 24-часового окна.

  • ACCOUNT_UPDATE — помечает сообщение, которое вы отправляете клиенту, как нерегулярное обновление приложения или аккаунта. Посмотрите допустимые варианты использования.

    Недоступно для API Instagram Messaging.

  • CONFIRMED_EVENT_UPDATE — помечает сообщение, которое вы отправляете клиенту, как напоминание о предстоящем мероприятии или новость о текущем мероприятии, где зарегистрирован клиент. Посмотрите допустимые варианты использования.

    Недоступно для API Instagram Messaging.

  • CUSTOMER_FEEDBACK — помечает сообщение, которое вы отправляете клиенту, как опрос клиента . Отзывы должны быть отправлены в течение 7 дней с момента отправки последнего сообщения клиента. Посмотрите допустимые варианты использования.

    Недоступно для API Instagram Messaging.

  • HUMAN_AGENT —Требуется для API Instagram Messaging. Если добавить эту метку в сообщение, которое отправляется пользователю, на сообщение этого пользователя сможет ответить оператор. Сообщения можно отправлять в течение 7 дней с момента отправки сообщения пользователем. Поддержка с привлечением оператора используется для решения проблем, которые невозможно решить в течение стандартного окна обмена сообщениями. Посмотрите допустимые варианты использования.
    • Приложения должны запросить разрешение Human Agent через панель приложения разработчика. Откройте панель приложения -> Проверка приложения -> Разрешения и функции -> Живой оператор. Приложения, которым раньше был одобрен бета-доступ к разрешению "Живой оператор", могут не подавать запрос повторно.

    Разрешение Human Agent недоступно в режиме стандартного доступа или в режиме разработки. Чтобы использовать метку живого оператора, сначала необходимо пройти проверку приложения. При отправке приложения на проверку предоставьте четкие инструкции и покажите, как вы намереваетесь использовать метку живого оператора.

  • POST_PURCHASE_UPDATE — помечает сообщение, которое вы отправляете клиенту, как новость о недавней покупке, совершенной клиентом. Посмотрите допустимые варианты использования.

    Недоступно для API Instagram Messaging.

Сценарии использования меток сообщения

В следующей таблице приведены типы сообщений для каждой метки.

Метка сообщенияИспользование

ACCOUNT_UPDATE

Допустимое использование

  • Уведомление об изменении статуса заявки, например заявки на кредитную карту или отклика на вакансию
  • Уведомление о подозрительных действиях, например мошенничестве

Недопустимое использование (не исчерпывающий список)

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

Недоступно для API Instagram Messaging.

CONFIRMED_EVENT_UPDATE

Допустимое использование

  • Напоминание о предстоящем занятии, встрече или мероприятии, которое запланировал пользователь
  • Подтверждение бронирования или намерения посетить мероприятие или встречу, на которые человек принял приглашение
  • Уведомления о запланированной поездке (прибытие, отмена, задержка багажа, другие изменения статуса поездки)

Недопустимое использование (не исчерпывающий список)

  • Рекламный контент, такой как сделки, предложения, купоны и скидки
  • Контент, связанный с мероприятиями, на которые пользователь не подписывался (напоминания о покупке билетов, перекрестная продажа, график гастролей)
  • Сообщения о прошедших мероприятиях
  • Предложения пройти опрос или оставить отзыв, не связанный с предыдущим взаимодействием в Messenger.

Недоступно для API Instagram Messaging.

CUSTOMER_FEEDBACK

Допустимое использование

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

Недопустимое использование (не исчерпывающий список)

  • Метка может использоваться в шаблоне отзыва клиентов. Использование в любой другой форме запрещено.

Недоступно для API Instagram Messaging.

HUMAN_AGENT

Допустимое использование

  • Поддержка с использованием функции "Живой оператор" для решения проблем, которые невозможно решить в течение стандартного 24-часового окна, например возникших в нерабочее время или требующих более длительной работы

Недопустимое использование (не исчерпывающий список)

  • Автоматические сообщения
  • Контент, не связанный с запросом пользователя

Требуется для API Instagram Messaging.

POST_PURCHASE_UPDATE

Допустимое использование

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

Недопустимое использование (не исчерпывающий список)

  • Рекламный контент, такой как сделки, промоакции, купоны и скидки
  • Сообщения для перекрестных продаж или продажи более дорогих или дополнительных товаров и услуг
  • Предложения пройти опрос или оставить отзыв, не связанный с предыдущим взаимодействием в Messenger.

Недоступно для API Instagram Messaging.

Чтение

Эту операцию нельзя выполнять на этой конечной точке.

Информация о переписках, в которых участвует ваша Страница, приведена здесь.

Обновление

Эту операцию нельзя выполнять на этой конечной точке.

Удаление

Эту операцию нельзя выполнять на этой конечной точке.

См. также

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