Мероприятия

События — это уведомления, которые ваш агент может отправлять и получать. Существует три типа событий:

События, генерируемые сервером

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

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

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

Платформа RBM отправляет событие AgentLaunchEvent при каждом изменении статуса запуска вашего агента. Например, когда статус вашего агента меняется с PENDING на LAUNCHED после одобрения оператором, вы получаете событие AgentLaunchEvent , уведомляющее об этом изменении. Эти события отправляются всем агентам RBM при всех изменениях статуса запуска оператора.

Конфигурация веб-перехватчика

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

Предпосылки

  • Настройте свой вебхук для обмена сообщениями RBM (это требование для получения пользовательских сообщений и событий, создаваемых пользователями).
  • Чтобы различать события, создаваемые пользователем , и события состояния запуска агента, проверьте путь 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 Запущен прекращенный агент.

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

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

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

Срок действия сообщения истек, но оно не было отозвано.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

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

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

События, создаваемые пользователями

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

Параметры форматирования и значений см. в разделе 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"
  }
}

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

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

Событие UNSUBSCRIBE указывает на то, что пользователь отписался от переписки с вашим агентом и компанией, которую он представляет. Вот пример полезной нагрузки JSON: 

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

Как это работает

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

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

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

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

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

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

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

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

Пример

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

Причины отказа от подписки

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

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

В настоящее время причины отказа от подписки не сообщаются партнерам или операторам связи.

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

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

Событие SUBSCRIBE указывает на то, что пользователь хочет получать сообщения от вашего агента, включая необязательный контент, например, рекламные акции. Вот пример полезной нагрузки JSON: 

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

Как это работает

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

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

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

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

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

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

События, генерируемые агентом

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

Параметры форматирования и значений см. в phones.agentEvents .

Агент отправляет событие READ

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

Следующий код отправляет событие READ для сообщения с соответствующим messageId .

cURL 

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js 

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 Этот код является отрывком из примера агента RBM .

Ява 

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 Этот код является отрывком из примера агента RBM .

Питон 

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 Этот код является отрывком из примера агента RBM .

С# 

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 Этот код является отрывком из примера агента RBM .

Агент отправляет событие IS_TYPING

Для пользователей это событие отображается как индикатор набора текста и информирует их о том, что ваш агент пишет сообщение. Индикатор набора текста сгорает через короткое время (примерно через 20 секунд) или при получении устройством пользователя нового сообщения от вашего агента. Ваш агент может отправлять несколько событий IS_TYPING для сброса таймера истечения срока действия индикатора набора текста.

Следующий код отправляет событие IS_TYPING .

cURL 

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js 

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 Этот код является отрывком из примера агента RBM .

Ява 

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 Этот код является отрывком из примера агента RBM .

Питон 

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 Этот код является отрывком из примера агента RBM .

С# 

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 Этот код является отрывком из примера агента RBM .
Назад
Получать сообщения
Далее
Проверка возможностей