Платформа 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 -X POST "https://graph.facebook.com/v21.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "access_token={PAGE_ACCESS_TOKEN}"

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

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

Параметры

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

message

Объект

Тип сообщения, отправляемого Страницей. Если этот параметр используется, должен быть задан параметр 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

Перечисление

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

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

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

notification_type

Перечисление

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

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

recipient

Объект

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

Человек, который получит сообщение от вашей Страницы.

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

sender_action

Перечисление

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

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

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

tag

Перечисление

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ACCOUNT_UPDATE

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

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

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

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

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

CONFIRMED_EVENT_UPDATE

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

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

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

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

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

CUSTOMER_FEEDBACK

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

  • Опрос о впечатлениях от покупки.
  • Опрос о впечатлениях от события.
  • Отзывы о товарах.

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

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

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

HUMAN_AGENT

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

  • Операторская поддержка по вопросам, которые невозможно решить в рамках стандартного 24-часового окна переписки (например, вне часов работы компании или если для решения вопроса требуется более 24 часов).

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

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

Обязательно для Instagram Messaging API.

POST_PURCHASE_UPDATE

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

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

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

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

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

Чтение

Эта операция не поддерживается для данной конечной точки.

Дополнительную информацию о переписках вашей Страницы см. в соответствующей справочной статье.

Обновление

Эта операция не поддерживается для данной конечной точки.

Удаление

Эта операция не поддерживается для данной конечной точки.

См. также

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