Плагин чата (бета-версия)

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

В плагин чата автоматически загружается последняя переписка между клиентом и компанией с сайта messenger.com, из приложения Messenger или из этого же плагина на вашем сайте. Так клиенту будет удобнее общаться с вами, а вы сможете поддерживать переписку с ним, даже когда он покинет ваш сайт. Вам не потребуется сохранять переписку: достаточно будет снова открыть ее в Messenger.

Содержание

Поддерживаемые функции

Поддерживаемые браузеры

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

Типы сообщений и поддерживаемые шаблоны

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

Функция Поддержка

Текстовое сообщение

Да

Видео/изображение/аудио/GIF

Да

Общие функции/шаблон кнопки

Да (поддерживаются не все типы кнопок)

Обратная передача

Кнопка с URL

Кнопка вызова

Кнопка "Купить"

Кнопка "Поделиться"

Кнопка "Войти"

Кнопка "Выйти"

Кнопка "Запуск игры"

Список/мультимедиа/шаблон Open Graph

Нет

Быстрые ответы

Да (поддерживаются не все типы быстрых ответов)

Текстовые быстрые ответы

Быстрые ответы с номером телефона пользователя

Быстрые ответы с эл. адресом

Быстрые ответы о местоположении

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

Да

Действия отправителя

Да

Добавление SDK

Чтобы использовать плагин чата, добавьте Facebook SDK для JavaScript (версию с поддержкой чата) на страницу, где будет отображаться чат.

Инструкции по добавлению этого SDK см. здесь.

Локализация и интернационализация

Чтобы воспользоваться возможностями локализации, в частности автоматически переводить контент, вы должны заменить язык SDK на язык своего сайта. Для этого при инициализации SDK нужно заменить код en_US на код поддерживаемого языка.

Подробнее см. здесь.

Динамическое управление плагином

Мы также предоставляем API, которые позволяют динамически управлять некоторыми функциями плагина, например открытием и закрытием диалога.

Дополнительные сведения см. в статье об SDK чата с клиентами.

Настройка плагина

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

Вариант 1. Использование инструмента настройки.

В разделе "Настройки Страницы" есть удобный инструмент для настройки плагина чата, предназначенный для администраторов Страниц. Чтобы воспользоваться им, выполните следующие действия:

  1. Перейдите в раздел Настройки Страницы > Обмен сообщениями.
  2. В разделе "Добавьте Messenger на сайт" нажмите кнопку "Начать работу".

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

По завершении настройки инструмент автоматически генерирует фрагменты кода, которые можно скопировать и вставить, чтобы добавить плагин чата на веб-страницу.

Вариант 2. Настройка с помощью инструкций для разработчиков.

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

  1. Занесение домена сайта в белый список

    В целях безопасности плагин будет отображаться только в том случае, если он загружается в домене, который вы занесли в белый список. Подробнее о том, как занести домен в "белый" список программными средствами, см. в справке по свойству whitelisted_domains.

    Требования

    Чтобы домен можно было занести в «белый» список, должны быть выполнены следующие условия:

    • В домене поддерживается протокол HTTPS.

    • Название домена должно быть указано полностью, например так: https://www.messenger.com/. IP-адреса и адрес localhost нельзя занести в «белый» список.

    Если поддержку Messenger вашей компании предоставляет внешний поставщик услуг, вы не сможете генерировать маркер доступа к Странице в настройках приложения, поскольку приложение Facebook вам не принадлежит. В этом случае можно использовать настройки Страницы, чтобы добавлять и удалять домены в "белом" списке. Чтобы занести домен в "белый" список:

    1. Нажмите Настройки в верхней части Страницы.
    2. Слева нажмите Платформа Messenger.
    3. В разделе доменов из "белого" списка укажите нужный домен.
  2. Добавление плагина на страницу сайта

    Чтобы добавить плагин на страницу сайта, добавьте в HTML-код страницы элемент div с этими атрибутами:
    <div class="fb-customerchat"
     page_id="<PAGE_ID>">
    </div>

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

    Рекомендуемое место для плагина

    Настоятельно рекомендуем оставить плагин чата в правом нижнем углу страницы.

    Полный список атрибутов приведен в справке по плагину.

  3. Необязательно. Обработка события messaging_postbacks для новых переписок

    Если новая переписка начата из плагина и в вашем боте настроена кнопка "Начать", то при нажатии этой кнопки в ваш Webhook будет отправляться событие messaging_postbacks.

    Если вы добавите в плагин чата атрибут ref, он будет включен в событие обратной передачи.

    Важное изменение (5 мая 2020 г.)

    Событие Webhook messaging_postback API Graph версии 7.0 и новее от плагина чата не будет возвращать поле sender.id. Вместо этого будет возвращаться новое поле sender.user_ref. Это изменение вступит в силу для всех предыдущих версий API Graph с 2 ноября 2020 г.

    Новое событие Webhook обратной передачи при обращении (API Graph версии 7.0 и новее, а также все версии API Graph начиная с 2 ноября 2020 г.)

    {
      "sender":{
        "user_ref":"<USER_REF>" // new field
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    Старое событие Webhook обратной передачи при обращении (API Graph версии 6.0 и ниже до 2 ноября 2020 г.)

    {
      "sender":{
        "id":"<PSID>"
      },
      "recipient":{
        "id":"<PAGE_ID>"
      },
      "timestamp":1458692752478,
      "postback":{
        "title": "<TITLE_FOR_THE_CTA>",  
        "payload": "<USER_DEFINED_PAYLOAD>",
        "referral": {
          "ref": "<USER_DEFINED_REFERRAL_PARAM>",
          "source": "<SHORTLINK>",
          "type": "OPEN_THREAD",
        }
      }
    }    

    В новом формате Webhook messaging_postback для отправки сообщений нужно использовать USER_REF. USER_REF в API User Profile работать не будет. При ответе пользователя вы получите PSID, который затем можно использовать в API Send и API User Profile.

    API Send с применением USER_REF

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    
  4. Необязательно. Обработка события messaging_referrals для существующих переписок

    Если вы добавите в плагин чата атрибут ref, то каждый раз, когда существующая переписка возобновляется через плагин, в ваш Webhook будет отправляться событие Webhook messaging_referrals.

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

    Важное изменение (5 мая 2020 г.)

    Событие Webhook messaging_referrals API Graph версии 7.0 и новее от плагина чата не будет возвращать поле sender.id. Вместо этого будет возвращаться новое поле sender.user_ref. Это изменение вступит в силу для всех предыдущих версий API Graph с 2 ноября 2020 г.

    Новое событие Webhook перехода (API Graph версии 7.0 и новее, а также все версии API Graph начиная с 2 ноября 2020 г.)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "user_ref":"<USER_REF>" // new field
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    Старое событие Webhook перехода (API Graph версии 6.0 и ниже до 2 ноября 2020 г.)

    {
        "object": "page",
        "entry": [
            {
                "id": "<PAGE_ID>",
                "time": 1559598385735,
                "messaging": [
                    {
                        "recipient": {
                            "id": "<PAGE_ID>"
                        },
                        "timestamp": 1559598385735,
                        "sender": {
                            "id": "<USER_PSID>"
                        },
                        "referral": {
                            "ref": "<DEVELOPER_DEFINED_REFERRAL>",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                            "referer_uri": "<REFERRAL_URI>"
                        }
                    }
                ]
            }
        ]
    }
    

    В новом формате Webhook messaging_referrals для отправки сообщений нужно использовать USER_REF. USER_REF в API User Profile работать не будет. При ответе пользователя вы получите PSID, который затем можно использовать в API Send и API User Profile.

    API Send с применением USER_REF

    curl -X POST -H "Content-Type: application/json" -d '{
      "messaging_type": "<MESSAGING_TYPE>",
      "recipient": {
        "user_ref": "<USER_REF>"
      },
      "message": {
        "text": "hello, world!"
      }
    }' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"
    

Индивидуальная настройка плагина

Плагин чата поддерживает перечисленные ниже возможности настройки. Все настройки задаются как атрибуты при добавлении плагина на страницу вашего сайта:

Атрибут Описание

theme_color

Необязательно. Цвет темы оформления плагина, в том числе цвет фона значка для плагина и цвет фона сообщений, отправленных пользователями. Поддерживает все шестнадцатеричные коды цветов, которые начинаются со значка решетки (например, #0084FF), кроме белого. Настоятельно рекомендуем вам выбрать цвет, контрастный белому.

logged_in_greeting

Необязательно. Текст приветствия, который будет отображаться, если пользователь вошел на Facebook. Не более 80 символов.

logged_out_greeting

Необязательно. Текст приветствия, который будет отображаться, если пользователь не вошел на Facebook. Не более 80 символов.

greeting_dialog_display

Необязательно. Режим показа диалога приветствия. Поддерживаются следующие значения:


  • show: диалог приветствия отображается и остается открытым на ПК или мобильном устройстве через количество секунд, заданное атрибутом greeting_dialog_delay;
  • hide: диалог приветствия остается скрытым, пока пользователь не щелкнет плагин на ПК или мобильном устройстве;
  • fade: диалог приветствия кратковременно отображается на ПК через количество секунд, заданное атрибутом greeting_dialog_delay, а потом постепенно исчезает, после чего остается скрытым;

По умолчанию на ПК и мобильных устройствах используется значение show. Подробную информацию см. в разделе Кэширование ниже.

greeting_dialog_delay

Необязательно. Количество секунд, которое должно пройти между загрузкой плагина и показом диалога приветствия. Используйте этот атрибут, чтобы указать, когда должен появляться диалог приветствия. Если атрибут greeting_dialog_delay задан, а greeting_dialog_display отсутствует, диалог будет отображаться с задержкой на ПК и без задержки на мобильных устройствах.

ref

Необязательно. Если вы хотите передать в событие Webhook дополнительный контекст, используйте необязательный параметр ref. Это можно использовать в разных целях: для отслеживания того, на какой странице пользователь начал переписку, направления пользователей на конкретный контент или функции, которые предлагает бот, или привязки пользователя Messenger к сеансу или аккаунту на сайте.

Отключение постоянного меню

В некоторых случаях постоянное меню бота в плагине нужно отключить. Для этого при настройке постоянного меню добавьте в код элемент "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"]:

Пример полезных данных API Messenger Profile

{
  "persistent_menu":[
    {
      "locale":"default",
      "disabled_surfaces": ["CUSTOMER_CHAT_PLUGIN"],
      "composer_input_disabled": false,      
      "call_to_actions":[
        {
          "title":"My Account",
          "type":"postback",
          "payload":"PAYBILL_PAYLOAD"
        }
      ]
    }
  ]
}

Гостевой режим

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

Если компания отправит пользователю-гостю сообщение после удаления гостевого аккаунта, появится сообщение об ошибке с текстом "Этот человек не может получить сообщения: в данный этот человек момент не получает сообщения от вас". Гостевые переписки хранятся в браузере пользователя-гостя не более 24 часов. Для компаний копия переписки сохраняется во входящих даже после истечения срока действия чата. Переписка сохраняется, пока компания не удалит ее.

С 16 июня в плагине будут введены следующие изменения для разработчиков, у чьих страниц есть доступ к гостевому режиму:

  • Webhook переходов при обращении: упрощена идентификация пользователей-гостей. Webhook messaging_referrals теперь включает флажок is_guest_user=true для пользователей-гостей.
  • Webhook завершения: когда пользователь завершает переписку, мы отправляем компании уведомление Webhook о том, что гость больше не доступен. Отправка дальнейших сообщений на этот GuestID завершится неудачно.

Компании могут управлять гостевым режимом следующим образом:

  • Включать и отключать режим гостя в настройках Страницы → Обмен сообщениями → Добавить Messenger на сайт → Начало работы → Отключить режим гостя.
  • Блокировать пользователей-гостей во Входящих Страницы Facebook.
  • С помощью этой формы можно пожаловаться на гостя, повторно отправляющего нежелательные сообщения.

Webhook переходов при обращении

Webhook messaging_referrals от пользователей-гостей включает флажок is_guest_user=true.

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>",
     "is_guest_user": "true"
  }
}

Webhook завершения

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

{
  "sender":{
    "id":"<GUEST_ID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp":1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "END_CHAT",
     "referer_uri": "<WEBSITE_URL>"
     "is_guest_user": "true" #this is optional
  }
}

API User Profile

Для пользователей-гостей недоступна информация о языке, поле и часовом поясе.

curl -X GET "https://graph.facebook.com/v7.0/<GUEST_ID>?fields=first_name,last_name,profile_pic,is_guest_user"
  
{
    "first_name": "Guest",
    "last_name": "1234",
    "profile_pic": "https://example.com/profile.jpg",
    "is_guest_user": "true"
}

API Conversation

Параметр user_id API Conversation может принимать GUEST_ID, с помощью которого разработчики смогут получать историю переписки с пользователем-гостем.

curl -i -X GET \
 "https://graph.facebook.com/v7.0/me/conversations?user_id=<PSID/GUEST_ID>"

API Send

Параметр id API Send может принимать GUEST_ID, с помощью которого разработчики смогут отправлять сообщения пользователям-гостям.

curl -X POST -H "Content-Type: application/json" -d '{
  "messaging_type": "<MESSAGING_TYPE>",
  "recipient": {
    "id": "<GUEST_ID>"
  },
  "message": {
    "text": "hello, world!"
  }
}' "https://graph.facebook.com/v7.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Вход пользователя

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

Ограничения по возрасту и странам на Страницах

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

Кэширование

Состояние диалога приветствия кэшируется в браузере и сохраняется, даже если закрыть и вновь открыть браузер. Плагин по умолчанию всегда будет применять настройки, заданные пользователем и сохраненные в кэше браузера (за исключением браузеров Safari 12 или более поздних версий и браузеров Firefox).

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

Определение происхождения сообщения

Иногда возникает необходимость определить, общается ли пользователь с вашей компанией с помощью плагина или других средств. Для этого платформа Messenger включает в полезную нагрузку всех отправленных из плагина сообщений свойство "source": "customer_chat_plugin".

Пример события сообщений Webhook

{
    "object": "page",
    "entry": [
        {
            "id": "<PAGE_ID>",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "<USER_PSID>"
                    },
                    "recipient": {
                        "id": "<PAGE_ID>"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

Плагин WordPress

Чтобы упростить интеграцию плагина чата в сайты на WordPress, мы создали для них отдельную официальную версию этого плагина Messenger (доступна на wordpress.org).

Советы по устранению неполадок

Если плагин отображается с ошибками, попробуйте сделать следующее.

  • Если возникла ошибка консоли, например "*** не отображается во фрейме, поскольку предшественник нарушил следующую директиву Политики защиты контента: ***", убедитесь, что домен страницы с плагином добавлен в "белый" список. Убедитесь в том, что для заголовка Referrer-Policy не задано значение no-referrer.
  • Отображению плагина препятствует расширение Facebook Container для Firefox. Удалите это расширение, чтобы отобразить плагин.
  • Мобильный браузер и версии Firefox для ПК с функцией приватного просмотра (версия 63 и новее) по умолчанию блокируют отслеживание содержимого, в результате чего плагин не отображается. Выключите блокировку содержимого (нажмите значок щита в панели поиска), чтобы отобразить плагин.