Получать события

Ваш агент получает события веб-перехватчика от платформы RBM, уведомляя вас как о взаимодействиях с пользователями, так и об обновлениях на уровне платформы.

Эти события классифицируются по месту их происхождения:

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

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

События пользователя

Пользовательские события — это уведомления с устройства пользователя, сообщающие о статусе сообщения или изменениях в подписке (например, пользователь отписался или подписался на рассылку Google Messages).

Полный список параметров форматирования и значений см. в справочнике UserEvent .

Пользователь получает сообщение от агента.

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Пользователь читает сообщение агента.

Это событие указывает на то, что сообщение было открыто или подтверждено.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

Пользователь начинает печатать

Это событие указывает на то, что пользователь вводит ответ.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Пользователь отправляет файл 

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Пользователь нажимает на предложенный ответ.

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

Пользователь нажимает на предложенное действие

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

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

Пользователь отписывается от обсуждения

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

Вот пример полезной нагрузки в формате JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Как работает отписка от рассылки

  • В меню чата всегда доступна опция «Отписаться» . Для рекламных и многоразовых агентов эта опция также появляется непосредственно в чате после определенного количества непрочитанных сообщений (конкретные правила различаются в зависимости от страны).

  • Выбор пункта «Отписаться» запускает два одновременных действия: Google Messages отправляет вашему агенту ключевое слово, специфичное для данной страны (например, «СТОП»), а платформа RBM отправляет событие UNSUBSCRIBE на ваш веб-хук.

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

    Страна (код страны) Ключевое слово для отписки
    Соединенные Штаты (США), Индия (ИН), Великобритания (ГБ), Германия (ДЕ) ОСТАНАВЛИВАТЬСЯ
    Испания (ES), Мексика (MX) БАХА
    Франция (FR) ОСТАНАВЛИВАТЬСЯ
    Бразилия (BR) парар

  • После отписки пользователя переписка остается в его почтовом ящике, если только она не помечена как спам, в этом случае она перемещается в папку «Спам и заблокированные» .

  • Для выявления нарушений политики и бизнес-правил Google отслеживает шаблоны сообщений после отписки пользователя.

Бизнес-правила

  • Как партнер RBM, управляющий этим диалогом, вы обязаны выполнить просьбу пользователя об отписке.
  • Если отписка от рассылки невозможна в рамках переписки, необходимо немедленно отправить подтверждающее сообщение со ссылкой на веб-сайт или приложение, где пользователи могут управлять своими настройками подписки.
  • После отписки пользователя отправка несущественных сообщений запрещается.
  • Разрешается отправлять важные сообщения. К ним относятся:
    • Аутентификация, например, с помощью одноразовых паролей (OTP).
    • Уведомления о конкретной услуге, которую пользователь запросил и на которую дал согласие.
    • Подтверждение запроса пользователя на отписку от рассылки с информацией для дальнейшего управления его предпочтениями в отношении коммуникаций.

Пример

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

Причины отписки

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

  • Спам
  • Никогда не регистрировался
  • Слишком много сообщений
  • Больше не заинтересован
  • Другой

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

Пользователь повторно подписывается на беседу.

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

Вот пример полезной нагрузки в формате JSON:

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Как работает повторная подписка

  • Функция «Подписаться» , доступная как в меню чата, так и по ссылке внутри чата, позволяет пользователям повторно подписаться на беседу, от которой они ранее отписались.

  • Выбор пункта «Подписаться» запускает два одновременных действия: Google Messages отправляет вашему агенту ключевое слово, специфичное для данной страны (например, «START»), а платформа RBM отправляет событие SUBSCRIBE на ваш веб-хук. Конкретное ключевое слово определяется двухбуквенным кодом страны в номере телефона пользователя. В следующей таблице перечислены ключевые слова для каждой поддерживаемой страны.

    Страна (код страны) Ключевое слово для подписки
    Соединенные Штаты (США), Индия (ИН), Великобритания (ГБ), Германия (ДЕ) НАЧИНАТЬ
    Испания (ES), Мексика (MX) АЛЬТА
    Франция (FR) Демаррер
    Бразилия (BR) комесар

Бизнес-правила

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

События платформы

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

Состояние запуска агента изменилось.

Платформа RBM отправляет событие AgentLaunchEvent при каждом изменении статуса запуска вашего агента. Например, когда состояние вашего агента меняется с PENDING на LAUNCHED . Событие доставляется в виде сообщения Pub/Sub. Чтобы отличить это от других событий, проверьте путь message.attributes.type и значение agent_launch_event .

Настройка веб-перехватчика

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

Предварительные требования

Структура полезной нагрузки события

Событие AgentLaunchEvent передается в виде сообщения Pub/Sub. Вот пример: 

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

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

Ценить Состояние запуска агента Подробности
UNLAUNCHED Незапущенный Редактирование разрешено.
PENDING В ожидании Запрос отправлен перевозчику для рассмотрения.
LAUNCHED Запущен Сообщения разрешены на данном операторе связи.
REJECTED Отклонено данным перевозчиком. Причина отказа указана в комментарии.
SUSPENDED Приостановлено на данном перевозчике Причина блокировки указана в комментарии.

Поле данных содержит JSON-объект, закодированный в Base64, с подробной информацией о состоянии запуска. Вот пример декодированного JSON: 

    {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
    }

В таблице ниже показаны состояния запуска агента и действия, которые их запускают:

Старое состояние запуска Новое состояние запуска Триггер для перемен
PENDING LAUNCHED Агент, ожидающий одобрения, утвержден.
PENDING REJECTED Заявка агента отклонена.
LAUNCHED SUSPENDED Работа агента, запущенного в систему, приостановлена.
SUSPENDED LAUNCHED Приостановленный агент был повторно активирован.
SUSPENDED TERMINATED Отстраненный от работы сотрудник уволен.
TERMINATED LAUNCHED Агент, с которым был расторгнут контракт, возобновил работу.

Срок действия сообщения истек; аннулирование прошло успешно.

Это событие указывает на то, что время жизни сообщения (TTL) истекло, и сообщение было успешно отозвано. Это хороший триггер для вашей стратегии резервного обмена сообщениями.

Полный список параметров форматирования и значений см. в справочнике ServerEvent . 

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Сообщение устарело; отзыв не удался.

Это событие указывает на то, что время жизни сообщения (TTL) истекло, но оно не было успешно отозвано.

Полный список параметров форматирования и значений см. в справочнике ServerEvent . 

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Доставка сообщений не гарантируется.

  • Если сообщение было доставлено, вы получите событие DELIVERED на свой веб-хук.
  • Если сообщение не было доставлено, используйте API отзыва для отправки запроса на отзыв .

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

Назад
Отправка событий
Далее
Проверка возможностей