Протокол передачи

Протокол передачи платформы Messenger позволяет нескольким приложениям участвовать в переписке и передавать управление друг другу. Если на приложение подписана Страница Facebook, для этого приложения автоматически включается протокол передачи.

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

Принцип работы

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

По умолчанию, когда пользователь отправляет сообщение, начатая переписка считается неактивной. Приложение получает уведомление Webhooks о том, что получено сообщение и ожидается ответ. Чтобы получить это уведомление, приложение должно быть подписано на Webhooks передачи.

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

Управляющее приложение получает уведомления от Webhooks переписки, а все другие приложения — от Webhooks передачи.

Если в течение 24 часов в переписке отсутствуют действия, она автоматически становится неактивной. При необходимости управляющее приложение может продлить этот период контроля.

Если приложение, не контролирующее переписку, попытается отправить сообщение пользователю, вернется ошибка 400 с подкодом 2018300.

Основной получатель

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

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

Примечание. Указывать основного получателя необязательно.

Входящие

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

Точки входа для начала переписки

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

Постоянное меню

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

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

Когда пользователь выбирает элемент меню, управление переходит к приложению, настроившему это меню. Это происходит потому, что это приложение настроено для обработки данных от меню.

Призыв к действию с обратной передачей

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

Опросы клиентов

Если опрос отправлен, когда перепиской управляет другое приложение, он не будет доставляться до тех пор, пока переписка не станет неактивной.

Компоненты

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

Маркеры доступа

Для вызова конечных точек протокола передачи требуется маркер доступа к Странице, запрошенный пользователем, который имеет право выполнять задачу MODERATE на Странице.

Проверка приложения

Проверка требуется для приложений, которые:

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

Функция "Оператор"

Приложение, не контролирующее переписку, может отправлять сообщение человеку, используя функцию "Оператор". Для этого оно должно пройти проверку и получить одобрение на использование этой функции. Сообщение должно быть помечено тегом оператора. Это единственный сценарий, при котором приложение, не контролирующее переписку, может отправить сообщение.

Разрешения

Для запроса разрешения на доступ к данным переписки у клиентов приложениям требуется разрешение pages_messaging.

Webhooks

Для протокола передачи существует два набора Webhooks, на которые приложению нужно подписаться: Webhooks переписки и Webhooks ожидания. То, какие уведомления получает приложение, зависит от того, кто управляет перепиской. Если приложение управляет перепиской, оно получает уведомления Webhooks переписки. Если оно не управляет перепиской, то получает уведомления ожидания.

Стандартное использование

Поддержка клиентов

Компания использует приложение-бот для часто задаваемых вопросов. Если бот не может ответить на вопрос, клиент переводится в другое приложение для общения с оператором. Приложение-бот задано в качестве основного получателя и выступает владельцем всех переписок. Когда в переписку должен вступить оператор, соответствующее приложение запрашивает передачу управления перепиской. После того как приложение оператора завершило работу с перепиской, управление вновь передается приложению-боту. Если приложению оператора требуется больше времени, чтобы решить проблему клиента, оно может запросить продление. Чтобы работа с перепиской шла без ошибок, оба приложения должны быть подписаны на Webhooks.

Маркетинговая кампания: лиды для продуктов

Компания проводит маркетинговую кампанию с использованием чат-бота, который квалифицирует лиды или предоставляет рекомендации продуктов на основании результатов опроса. После квалификации лида компания продолжает переписку с потенциальными клиентами через "Входящие" Страницы Facebook или аккаунта Instagram. Приложение-бот задано в качестве основного получателя и выступает владельцем всех переписок. Как только чат-бот закончил квалификацию лидов, управление перепиской переходит к "Входящим" Страницы Facebook или аккаунта Instagram. По завершении переписку нужно пометить как законченную (Готово). Благодаря этому управление перепиской вновь перейдет к основному приложению. Чтобы работа с перепиской шла без ошибок, оба приложения должны быть подписаны на Webhooks.

Маркетинговая кампания: реклама с переходом в Messenger

Компания проводит маркетинговую кампанию, где потенциальные клиенты перенаправляются в бот Messenger, которым управляет автоматизированное приложение. Приложение-бот задано в качестве основного получателя и выступает владельцем всех переписок. Когда в переписку должен вступить оператор, соответствующее приложение запрашивает передачу управления перепиской. После того как приложение оператора завершило работу с перепиской, управление вновь передается приложению-боту. Если приложению оператора требуется больше времени, чтобы решить проблему клиента, оно может запросить продление. Чтобы работа с перепиской шла без ошибок, оба приложения должны быть подписаны на Webhooks.

Рекомендации

  1. Рекомендуем задавать приложения-боты в качестве основных получателей, а приложения операторов — в качестве вторичных. Приложение оператора должно прослушивать события ожидания и вступать в переписку только по необходимости.
  2. Всегда проверяйте, управляете ли вы перепиской, с помощью Get Thread Control API. После этого вызывайте другие API в зависимости от ситуации. Если вы не управляете перепиской, не пытайтесь перехватить управление.
  3. Не отправляйте сообщения в переписку, когда ею управляет другое приложение. Если ваше приложение — основное, используйте Get Thread Control API только при необходимости. Если этой необходимости нет или ваше приложение не основное, просто запросите передачу управления.
  4. Обеспечьте выполнение запросов на передачу управления от других приложений во всех возможных сценариях. Если вы по какой-то причине не можете сразу передать управление, воспользуйтесь Pass Metadata API, чтобы отправить запрашивающему приложению дополнительную информацию, создайте и сохраняйте очередь передачи управления.
  5. Закончив работу с перепиской, передайте управление запрашивающему приложению, если оно ещё находится в очереди, или верните переписку в состояние неактивной, чтобы другие приложения могли управлять ею. В противном случае через 24 часа переписка сама перейдет в режим неактивной. Обеспечьте в коде обработку этого сценария и соответствующих изменений статуса.
  6. Если отклик на вызов к Get Thread Control API сообщает, что переписка неактивна, запросите управление перепиской, чтобы беспрепятственно общаться с пользователем. По окончании переписки верните ее в состояние неактивной.