Плагин чата

В этом документе рассказывается, как добавить плагин чата в бот Messenger на сайте программным путем.

Если вы хотите использовать Meta Business Suite, чтобы добавить плагин чата на свою веб-страницу (рекомендуется), ознакомьтесь с информацией в Справочном центре Meta для бизнеса.

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

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

Входы в систему

Если человек вошел в Facebook, плагин будет показывать кнопки "Продолжить как [NAME]" и "Продолжить как гость". Если человек не вошел, плагин будет показывать кнопки "Войти в Messenger" и "Продолжить как гость".

Уведомления Webhooks

Когда человек нажимает плагин, чтобы начать или продолжить переписку с вашей компанией, на ваш сервер отправляется уведомление Webhooks, которое содержит:

• информацию о пользователе — ID внутри страницы (PSID) или ID реферала пользователя;
• указание источника сообщения в плагине чата;
• информацию о перенаправлении, добавленную в уведомление.

Если вы реализовали в плагине экран приветствия и человек нажимает кнопку "Начать", чтобы начать переписку с вашей компанией, на ваш сервер отправляется уведомление Webhooks messaging_postbacks. Ваша компания может использовать ID реферала пользователя для отправки сообщений пользователю в рамках стандартного 24-часового окна.

Существующие переписки

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

Типы сообщений, поддерживаемые плагином чата:

Плагин не поддерживает:

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

Вам понадобится:

• разрешение pages_messaging;
• маркер доступа к Странице, запрошенный у пользователя, который может выполнять задачу MODERATE на этой Странице;
• приложение, связанное с вашей Страницей Facebook и подписанное на поля Webhooks messaging, messaging_postbacks и messaging_referrals;
• домен вашего сайта, добавленный в белый список с помощью Messenger Profile API или Meta Business Suite.

Использование плагина чата регулируется Условиями использования инструментов Meta для бизнеса.

Ограничения

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

Добавление плагина чата

Шаг 1. Добавление SDK

Добавьте Facebook SDK для JavaScript на каждую страницу вашего сайта, на которой должен отображаться плагин.

<!-- Messenger Chat Plugin Code --> <div id="fb-root"></div> <div id="fb-customer-chat" class="fb-customerchat"></div> <script> var chatbox = document.getElementById('fb-customer-chat'); chatbox.setAttribute("page_id", "PAGE-ID"); chatbox.setAttribute("attribution", "biz_inbox"); </script> <script> window.fbAsyncInit = function() { FB.init({ xfbml : true, version : 'API-VERSION' }); }; (function(d, s, id) { var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; js.src = 'https://connect.facebook.net/en_US/sdk/xfbml.customerchat.js'; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'facebook-jssdk')); </script> 

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

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

Отправьте запрос POST к конечной точке /PAGE-ID/chat_plugin, чтобы настроить текст приветствия, цвет, значок и другие параметры плагина.

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

curl -i -X POST "https://graph.facebook.com/v21.0/PAGE-ID/chat_plugin
    ?welcome_screen_greeting:YOUR-WELCOME-TEXT
    &theme_color:553399
    &entry_point_icon:MESSENGER-ICON
    &entry_point_label:CHAT
    &access_token=PAGE-ACCESS-TOKEN"

Подробную информацию о полях для настройки плагина см. в справке по плагину чата .

Использование атрибутов HTML

Мы рекомендуем использовать этот метод только для изменения параметров, которые невозможно задать с помощью инструмента в разделе "Настройки Страницы" или API.

Уведомления Webhooks

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

Существующие переписки

Когда человек отправляет сообщение в существующей переписке с вашей компанией, отправляется уведомление Webhooks messaging. Оно содержит ID внутри страницы и параметр source объекта tags со значением customer_chat_plugin.

Уведомление о сообщении

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "id": "PSID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "message": {
                        "tags": {
                            "source": "customer_chat_plugin"
                        },
                        "mid": "nhEqs_THGoYyAhpK93uNCrIfLZD...",
                        "text": "hello, from customer chat!"
                    }
                }
            ]
        }
    ]
}

Уведомление о переходах при обращении

Если для плагина чата задано свойство ref, на ваш сервер будет отправляться уведомление Webhooks messaging_referrals.

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598385735,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598385735,
                    "sender": {
                        "user_ref":"USER-REFERENCE-ID"
                    },
                    "referral": {
                        "ref": "REF-PARAMETER-INFORMATION",
                        "source": "CUSTOMER_CHAT_PLUGIN",
                        "type": "OPEN_THREAD",
                        "referer_uri": "REFERRAL-URI"
                    }
                }
            ]
        }
    ]
}

Новые переписки

Когда человек начинает переписку, нажав кнопку "Начать" на экране приветствия плагина, отправляется уведомление Webhooks messaging_postbacks.

Уведомление об обратной передаче

{
    "object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": 1559598624359,
            "messaging": [
                {
                    "sender": {
                        "user_ref": "USER-REFERENCE-ID"
                    },
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": 1559598623749,
                    "postback":{
                        "title": "TITLE-FOR-THE-CTA",  
                        "payload": "PAYLOAD-DEFINED-BY-CTA",
                        "referral": {
                            "ref": "ADDITIONAL-INFORMATION",
                            "source": "CUSTOMER_CHAT_PLUGIN",
                            "type": "OPEN_THREAD",
                    }
                }
            ]
        }
    ]
}

Запросы согласия на получение маркетинговых сообщений

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

Ограничения

Для маркетинговых сообщений в плагине чата поддерживается только тема Новости и акции.

Уведомление о согласии на получение сообщений

Когда человек дает согласие на получение маркетинговых сообщений от вашей компании, на ваш сервер отправляется уведомление Webhooks messaging_optins.

"object": "page",
    "entry": [
        {
            "id": "PAGE-ID",
            "time": TIMESTAMP,
            "messaging": [
                {
                    "recipient": {
                        "id": "PAGE-ID"
                    },
                    "timestamp": TIMESTAMP,
                    "optin": {
                        "type": "notification_messages",
                        "payload": "empty_payload",
                        "notification_messages_token": "NOTIFICATION-MESSAGE-TOKEN",
                        "notification_messages_frequency": "MESSAGE-FREQUENCY",
                        "topic": "NOTIFICATION-MESSAGE-TOPIC",
                        "token_expiry_timestamp": EXPIRATION-DATE-TIMESTAMP,
                        "ref": "ADDITIONAL-INFORMATION",
                        "user_token_status": "NOT_REFRESHED",
                        "notification_messages_status": "RESUME_NOTIFICATIONS"
                    }
                }
            ]
        }
    ]
}

Чтобы отправлять маркетинговые сообщения пользователю, можно указать для параметра notification_messages_token в объекте recipient значение ID.

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

• Не отображается…

  • Убедитесь в том, что домен внесен в белый список.
  • Задайте заголовок Referrer-Policy, чтобы отправлялся реферальный URL.

• Плагин чата не отображается в Firefox

  • Удалите расширение Facebook Container для Firefox.
  • Выключите блокировку контента (нажмите значок щита на панели поиска), чтобы отобразить плагин.

Дальнейшие действия

• Отправка ответа
• Отправка маркетинговых сообщений

Дополнительная информация

• Отключение постоянного меню
• Facebook SDK для JavaScript
• Гостевой режим — позволяет пользователям начинать переписки без входа на Facebook.
• Вводные фразы — позволяют пользователям начинать переписки с компаниями с помощью списка часто задаваемых вопросов.
• Постоянное меню — обеспечивает пользователям простой и удобный доступ к реализованным вами функциям во время переписки.