Агенты RCS for Business общаются с пользователями, отправляя и получая сообщения. Чтобы отправлять сообщения пользователям, агент отправляет запросы в RCS Business Messaging API. Один запрос может содержать текст, полезные подсказки, медиафайлы и PDF-файлы, готовые ответы и рекомендуемые действия.
В некоторых ситуациях платформа RCS for Business возвращает ошибки, чтобы помочь вам управлять доставкой сообщений.
- Если вы отправите сообщение пользователю, устройство которого не поддерживает RCS или на котором RCS не включен, платформа RCS for Business вернет ошибку
404 NOT_FOUND. В этом случае вы можете попытаться связаться с пользователем с помощью резервных методов, определенных в вашей инфраструктуре. - Если вы отправите сообщение пользователю RCS в сети, где ваш агент ещё не запущен или где не включен трафик RCS, платформа RCS for Business вернет ошибку
404 NOT_FOUND. - Если вы отправите сообщение с функциями, которые не поддерживаются на устройстве пользователя, платформа RCS for Business вернет ошибку
400 INVALID_ARGUMENTи не доставит сообщение.
В рамках многоканальной стратегии обмена сообщениями лучше всего отзывать сообщения, которые не были доставлены в течение разумного времени, и отправлять их по другому каналу. Чтобы сообщения автоматически отзывались в определенное время, задайте срок действия сообщения.
Получатель не в Сети
Платформа RCS for Business принимает сообщение для доставки, даже если получатель офлайн. Вы получите ответ 200 OK, а платформа RCS for Business сохранит сообщение и будет пытаться повторно отправить его в течение 30 дней. Запрашивать повторную отправку сообщения в RCS for Business не нужно.
RCS for Business удаляет все недоставленные сообщения через 30 дней после их отправки.
В зависимости от того, как используется агент, вы можете отозвать недоставленное сообщение до истечения 30-дневного срока. Это позволяет предотвратить получение устаревших сообщений пользователями, которые были офлайн. Есть несколько способов отозвать сообщение:
- Отправьте запрос на отзыв, чтобы инициировать отзыв.
- Установите срок действия сообщения, чтобы оно автоматически перестало показываться в нужное время.
ограничить срок доступа к письму;
Сообщение агента срочное? Например, одноразовые пароли действительны только в течение короткого периода времени. Срок действия временных предложений истекает. А напоминания о встречах неактуальны после даты встречи. Чтобы сообщения оставались актуальными, задайте срок их действия. Это позволяет избежать ситуации, когда пользователи, работающие в офлайн-режиме, получают устаревший контент, когда снова подключаются к интернету. Истечение срока действия – это также хороший повод задействовать резервную стратегию обмена сообщениями, чтобы пользователи вовремя получали нужную информацию.
Чтобы задать срок действия сообщения, укажите одно из следующих полей в сообщении агента:
expireTime– точное время по UTC, когда истекает срок действия сообщения.ttl(время жизни) – время, по истечении которого сообщение удаляется.
Подробнее о форматировании и вариантах значенийAgentMessage…
Максимальное значение для ttl и expireTime – 15 дней после отправки сообщения.
Минимальное значение для ttl и expireTime – шесть секунд после отправки сообщения.
Рекомендации по настройке срока действия сообщений
Для сообщений аутентификации (одноразовых кодов) установите для параметра
ttlзначение 15 секунд или больше после отправки сообщения, чтобы значительно снизить вероятность состояния гонки при доставке и отзыве.Для транзакционных и рекламных сообщений задайте более длительный срок действия (не менее 60 секунд, а в зависимости от ситуации – от нескольких минут до нескольких часов). Это связано с тем, что устройствам требуется дополнительное время для сканирования сообщений и скачивания или обработки мультимедийного контента, а у пользователей могут возникать кратковременные перебои со связью (например, в лифте или туннеле).
Время жизни (TTL) сообщения
Когда вы задаете TTL для сообщения RCS for Business, вы указываете, как долго сообщение должно считаться действительным и доступным для доставки. Если сообщение не будет доставлено на устройство пользователя в течение этого времени, платформа RCS for Business автоматически попытается его отозвать.
Когда вы инициируете отзыв сообщения, вы запрашиваете у платформы RCS for Business прекращение попыток доставки этого конкретного сообщения. Однако это действие повлияет только на будущие попытки доставки. Если устройство пользователя уже успешно получило сообщение, оно обрабатывается, и платформа RCS for Business не может отозвать его с устройства пользователя.
Вот что нужно знать об уведомлениях:
Сообщение доставлено в течение TTL. Если устройство пользователя подключится к интернету и получит сообщение до истечения TTL, вы получите уведомление
DELIVERED. Уведомление об отзыве не будет отправлено, поскольку сообщение было успешно доставлено. Это самый распространенный и ожидаемый сценарий.Сообщение не доставлено до истечения TTL. Если TTL истекает до того, как сообщение доходит до устройства пользователя (например, устройство находится в офлайн-режиме), платформа RCS Business Messaging пытается отозвать сообщение. Вы получите уведомление
TTL_EXPIRATION_REVOKED, которое означает, что письмо было удалено из очереди доставки. В этом случае пользователь не получит сообщение.
Рекомендации по обработке пограничных случаев
Наша система обрабатывает доставку сообщений RCS for Business и истечение срока TTL параллельно. Поэтому в редких случаях уведомления могут приходить в неожиданное время. Например, вы можете получить уведомление о доставке и TTL или не получить ни одного.
Вот наши рекомендации по обработке уведомлений о сообщениях RCS for Business:
Уведомление
DELIVERED. Если вы получили уведомлениеDELIVERED, значит сообщение доставлено пользователю. Вы можете игнорировать все последующие уведомления TTL для этого сообщения.Уведомление
TTL_EXPIRATION_REVOKED. Если вы получили уведомление TTL со статусомTTL_EXPIRATION_REVOKED, это означает, что система RCS for Business прекратила попытки доставки этого сообщения. Вам следует считать это сообщение недоставленным и при необходимости перейти к резервной стратегии.Уведомление TTL с любым другим статусом. Если вы получили уведомление TTL с любым другим статусом, это означает, что попытка отзыва не дала результатов.
- Для критически важных сообщений, например одноразовых кодов, используйте резервный метод.
- Для некритичных сообщений вы можете решить, нужно ли инициировать резервный вариант.
- Уведомления не отправляются. В редких случаях система может не отправить уведомление TTL, а клиент – не создать уведомление о доставке. Это крайне редкий случай.
Как задать тип трафика сообщений
В RBM API есть поле messageTrafficType, которое позволяет классифицировать сообщения.
Варианты использования агента по-прежнему определяют его поведение и применяемые бизнес-правила, но messageTrafficType позволяет более детально классифицировать контент сообщений. В конечном итоге это позволяет одному агенту обрабатывать несколько вариантов использования. В настоящее время это не влияет на существующие сценарии использования агентов или бизнес-правила.
Это поле необязательно, но мы рекомендуем заполнить его сейчас, чтобы не получить ошибку, когда оно станет обязательным.
Чтобы задать тип трафика сообщений, назначьте каждому сообщению соответствующий messageTrafficType в зависимости от его содержания. В таблице ниже перечислены поддерживаемые типы трафика и ожидаемые варианты использования агентов. Это сопоставление является рекомендуемым руководством по ожидаемому использованию, а не ограничением, применяемым API в настоящее время.
| Тип трафика | Текст сообщения | Рекомендуемый пример использования агента |
|---|---|---|
AUTHENTICATION |
Для сообщений аутентификации. | Одноразовый код |
TRANSACTION |
Сообщения о существующих сервисах или продуктах пользователя. Например, это могут быть подтверждения, квитанции об оплате или сведения о бронировании. | Транзакция или несколько вариантов использования |
PROMOTION |
Для рекламных сообщений, например предложений, скидок, объявлений и другого рекламного контента. | Рекламные или многоцелевые |
SERVICEREQUEST |
Для сообщений об услугах, которые пользователь явно запросил. | Одноразовый код, транзакции, реклама или многоцелевое использование |
ACKNOWLEDGEMENT |
Для сообщений, подтверждающих действие пользователя, в частности запрос на отмену подписки. Это подтверждает, что запрос пользователя получен и обрабатывается. | Одноразовый код, транзакции, реклама или многоцелевое использование |
Если тип трафика не задан, система назначает тип по умолчанию для сценария использования агента.
| Пример использования агентом | Тип трафика по умолчанию |
|---|---|
| OTP | AUTHENTICATION |
| Транзакционные | TRANSACTION |
| Рекламные | PROMOTION |
| Многоразовые | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
У агентов многоцелевого назначения нет типа трафика по умолчанию. Тип трафика следует задавать явным образом для каждого сообщения в зависимости от его содержания. Если вы не замените значение MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, сообщение все равно будет принято и доставлено без классификации по типу трафика.
Ограничения на размер писем
Максимальный размер всего сериализованного объекта AgentMessage составляет 250 КБ. Текстовая часть сообщения не должна превышать 3072 символа.
Чтобы избежать непредвиденного расхода трафика у пользователей, максимальный размер файла, который можно отправить через RCS for Business, составляет 100 МиБ. Общий размер всех медиафайлов и PDF-файлов, прикрепленных к одному сообщению RCS for Business, не должен превышать 100 МиБ. (1 МиБ = 1 048 576 байт). Подробнее о медиафайлах и PDF-файлах…
Текст
Самые простые сообщения состоят из текста. Текстовые сообщения лучше всего подходят для передачи информации, не требующей визуальных эффектов, сложного взаимодействия или ответа.
Пример
Следующий код отправляет обычное текстовое сообщение. Варианты форматирования и значений описаны в статье phones.agentMessages.create.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Содержимое базового сообщения – преобразование SMS
Операторы ввели модели оплаты, чтобы поддержать переход с SMS на RCS for Business. Сообщение RCS for Business, содержащее до 160 символов UTF-8, называется базовым.
При создании запроса на отправку простого сообщения помните, что символы считаются как 1 байт (UTF-8). Если вы отправляете сообщение, содержащее специальные символы, например эмодзи или многобайтовый набор символов, каждый символ считается за 2–4 символа UTF-8 или больше.
Введите текст в поле, чтобы проверить его длину:
Содержимое текстовых сообщений и предпросмотр ссылок.
В RCS-клиентах может быть реализован предпросмотр ссылок. Если текстовое сообщение RCS for Business содержит URL сайта с тегами openGraph, клиент может сгенерировать предпросмотр (изображение, заголовок и т. д.), чтобы сделать сообщение более привлекательным. Например, посмотрите простое сообщение с предпросмотром URL.
Учтите, что RCS-клиент может позволять пользователю отключать предпросмотр ссылок.
Одноразовые коды для подтверждения личности пользователя
Вы можете использовать RCS for Business, чтобы отправлять одноразовые коды для автоматической проверки пользователей с помощью SMS Retriever API. Специального API для чтения одноразовых кодов, полученных через RCS for Business, нет.
Как это работает на устройствах Android
Если приложение Android зарегистрировано в SMS Retriever API, этот API ожидает правильно отформатированное сообщение RCS for Business. В сообщении должен быть одноразовый код и уникальный хеш, который идентифицирует ваше приложение.
Когда сообщение RCS for Business получено в правильном формате, SMS Retriever API обрабатывает его так же, как и одноразовый код из SMS. После того как хеш будет сопоставлен с вашим приложением, одноразовый код будет извлечен и перенаправлен в приложение для автоматической проверки пользователя.
- Пример текстового сообщения RCS for Business для подтверждения пользователя:
Your code is <OTP><app hash>. - Пример:
Your code is 123456 M8tue43FGT.
Дополнительную информацию об SMS Retriever и связанных API можно найти в документации по SMS Retriever. Подробные сведения об автоматической проверке пользователей в приложениях, зарегистрированных с помощью SMS Retriever API, приведены на блок-схеме.
Как это работает на устройствах iOS
На устройствах iOS встроенная система обработки одноразовых кодов автоматически обнаруживает и предлагает одноразовые коды RCS for Business для автозаполнения, как и одноразовые коды SMS. Для чтения одноразового кода в приложении iOS не требуется интеграция с API.
Медиафайлы и PDF-файлы
При отправке сообщения с изображением, видео, аудио или PDF-файлом агент должен предоставить общедоступный URL контента или загрузить файл напрямую.
Максимальный размер файла, который можно отправить, составляет 100 МиБ, а общий размер всех медиафайлов и PDF-файлов в одном сообщении не должен превышать 100 МиБ.
Сжатие и перекодирование медиафайлов
Платформа RCS for Business автоматически перекодирует и сжимает медиафайлы (например, изображения и видео) перед отправкой, чтобы они быстро загружались и корректно работали в разных сетях и на разных устройствах.
Сжатие зависит от качества исходного медиафайла, а не от ограничений на размер файла. Это означает, что файл может быть сжат, даже если его размер значительно меньше максимального ограничения в 100 МиБ. Стандарты перекодирования постоянно меняются, поэтому фиксированного ограничения на размер файла, при котором перекодирование не выполняется, нет. Экспериментируйте с разными форматами, размерами и степенью сжатия медиафайлов, чтобы найти оптимальный баланс для полезной нагрузки.
Требования к значкам
Для медиафайлов можно также указать значок, который позволит пользователям предварительно просматривать контент, прежде чем нажимать на него. Для аудиофайлов в качестве плейсхолдера используется виджет аудио по умолчанию.
- Максимальный размер файла значка – 100 КБ. Для оптимального удобства пользователей мы рекомендуем, чтобы он не превышал 50 КБ.
- Соотношение сторон значка должно соответствовать соотношению сторон исходного файла.
Кеширование и управление URL
Платформа RCS for Business кеширует файлы на 60 дней, а API возвращает идентификатор файла, который агент может включать в сообщения пользователям. Через 60 дней RCS for Business удаляет файлы из кеша.
Если вы указываете файлы по URL, рекомендуем задать для параметра contentMessage.forceRefresh значение false. Если для параметра contentMessage.forceRefresh задано значение true, RCS for Business будет получать новый контент по указанному URL, даже если контент по этому URL кеширован. Это увеличивает время доставки сообщений пользователям.
Пример URL файла
Следующий код отправляет изображение. Варианты форматирования и значений приведены в AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
Вы также можете загрузить медиафайлы перед отправкой в сообщении с помощью files.create.
Пример загрузки файла
Приведенный ниже код загружает видеофайл и файл значка, а затем отправляет оба файла в сообщении. Информацию о форматировании и значениях можно найти в статьях files.create и AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: video/mp4" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"# Capture server-specified video file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: image/jpeg" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"# Capture server-specified image file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "uploadedRbmFile": { "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME", "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME" } } }'
Поддерживаемые типы медиаконтента
RCS for Business поддерживает следующие типы медиаконтента. Для значков поддерживаются только форматы image/jpeg, image/jpg, image/gif и image/png.
| Тип контента | Тип документа | Расширение | Работа с полезными подсказками |
|---|---|---|---|
| application/ogg | Аудио OGG | .ogx | Нет |
| application/pdf | Да (только для Google Сообщений в Индии) | ||
| audio/aac | AAC; | .aac | Нет |
| audio/mp3 | Звук в формате MP3 | .mp3 | Нет |
| audio/mpeg | MPEG audio | MPEG | Нет |
| audio/mpg | Аудио MPG | .mp3 | Нет |
| audio/mp4 | Аудио MP4 | MP4 | Нет |
| audio/mp4-latm | Аудио MP4-latm | MP4 | Нет |
| audio/3gpp | Аудио 3GPP | .3gp | Нет |
| image/jpeg | JPEG | JPEG, JPG | Да |
| Изображение (GIF) | GIF | GIF | Да |
| Изображение (PNG) | PNG | PNG; | Да |
| video/h263 | Видео H.263 | .h263 | Да |
| video/m4v | Видео M4V | M4V | Да |
| Видео (MP4) | Видео MP4 | MP4 | Да |
| video/mpeg4 | Видео MPEG-4 | .mp4, .m4p | Да |
| video/mpeg | Видео MPEG | MPEG | Да |
| video/webm | Видео в формате WebM | .webm | Да |
Рекомендации
Агент отправляет подсказки (предлагаемые ответы и действия) в списках чипов или полезных подсказках.
готовые ответы;
Готовые ответы помогают пользователям вести диалог, предоставляя ответы, на которые ваш агент знает, как реагировать.
Когда пользователь нажимает на предложенный ответ, ваш агент получает событие, содержащее текст ответа и данные обратной передачи. Максимальная длина полезной нагрузки – 2048 символов.
Пример
В приведенном ниже коде отправляется текст с двумя предлагаемыми ответами. Подробнее SuggestedReply…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Рекомендуемые действия
Рекомендуемые действия помогают пользователям вести беседы, используя встроенные функции устройств. Агент может предложить пользователям набрать номер, открыть местоположение на карте, поделиться местоположением, открыть URL или создать мероприятие в календаре.
Для каждого рекомендуемого действия можно указать резервный URL (не более 2048 символов). Этот URL открывается в новом окне браузера, если устройство пользователя не поддерживает рекомендуемое действие.
Когда пользователь нажимает на рекомендуемое действие, агент получает событие, содержащее данные обратной передачи действия.
Подробнее о форматировании и вариантах значенийSuggestedAction…
Показ подсказок
Есть два способа показа подсказок:
- Persistent Рекомендуемые действия или ответы, которые показываются внутри всплывающего сообщения и остаются неизменными на протяжении всего разговора.
- Временные. Подсказки, которые показываются за пределами окна сообщения и исчезают, когда беседа продолжается.
Поддерживаемые форматы сообщений
- Постоянные подсказки работают с отдельными текстовыми сообщениями и полезными подсказками.
- Временные подсказки работают с отдельными текстовыми сообщениями, мультимедийными сообщениями и полезными подсказками.
Объединить предложения
В одном сообщении или на одной карточке можно использовать как постоянные, так и временные подсказки.
- Текстовые сообщения. По умолчанию подсказки временные. Чтобы они оставались в пузыре, их нужно настроить как постоянные.
- Полезные подсказки. По умолчанию поддерживается до четырех постоянных подсказок. Затем вы можете добавить временные подсказки в виде списка чипов под карточкой.
Ограничения на подсказки
В одном текстовом сообщении может быть не более 11 подсказок. Все добавленные вами постоянные подсказки учитываются в этом общем ограничении. Например, если вы добавите четыре постоянных подсказки, то сможете добавить до семи временных.
| Тип предложения | Ограничение | Где показываются объекты |
|---|---|---|
| Стабильное | До 4 | Внутри всплывающего сообщения |
| Временные | До 11 | Вне всплывающей подсказки (в виде чипов) |
Ограничение на количество символов
Максимальная длина каждого варианта – 25 символов.
Прозрачность URL в рекомендуемых действиях
Чтобы повысить доверие пользователей, URL, на который ведет ссылка, показывается во второй строке текста на кнопке рекомендуемого действия "Открыть URL". Это правило действует для отдельных текстовых сообщений, полезных подсказок и каруселей.
Клиенты, поддерживающие постоянные подсказки
- Поддерживается: Google Сообщения (версия
20260225.00или более поздняя). - Не поддерживается: Google Сообщения версий ранее
20260225.00, iOS и Samsung Messages.
Подсказки в системных уведомлениях
Когда пользователь получает сообщение, Google Сообщения показывают первую подходящую подсказку прямо в системном уведомлении Android. Пользователи могут нажать на подсказку, чтобы отправить ответ или запустить действие, не открывая приложение.
При разработке сообщений учитывайте следующее:
- Порядок имеет значение. В уведомлении показывается только одна подсказка. Чтобы повысить вовлеченность, поместите наиболее приоритетный готовый ответ или действие в начало списка.
- Исключенные действия. Действие Поделиться местоположением никогда не показывается в системных уведомлениях. Чтобы поделиться местоположением, пользователю нужно открыть чат.
Набрать номер
Действие Dial позволяет пользователю набрать номер телефона, указанный агентом.
Номер телефона может содержать только цифры (0-9), знак плюса (+), звездочку (*) и знак решетки (#). Международный формат E.164 (например, +14155555555) поддерживается, но не является обязательным. То есть можно использовать как +14155555555, так и 1011.
Пример
В следующем примере кода показано, как отправить действие набора номера. Варианты форматирования и значений приведены в DialAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Как посмотреть местоположение
Действие "Показать местоположение" открывает местоположение в приложении, которое пользователь использует для просмотра карт по умолчанию. Вы можете указать местоположение с помощью широты и долготы или запроса, основанного на текущем местоположении пользователя. Вы также можете задать собственный ярлык для маркера, который будет показываться в приложении с картой.
Пример
В следующем коде отправляется действие "Посмотреть местоположение". Варианты форматирования и значений описаны в статье ViewLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Передача геоданных
Действие "Поделиться местоположением" позволяет пользователю поделиться местоположением с вашим агентом. Пользователь может поделиться своим текущим местоположением или вручную выбрать местоположение в приложении "Карты".
Пример
Следующий код отправляет действие по передаче геоданных. Варианты форматирования и значений описаны в статье ShareLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Открыть URL
Действие "Открыть URL" позволяет направлять пользователей на веб-страницу, указанную агентом. По умолчанию веб-страница открывается в браузере пользователя. Вы также можете настроить открытие веб-страницы в компоненте WebView. Подробнее о том, как открыть URL с помощью компонента WebView…
Только в Google Сообщениях
Показ URL. Чтобы повысить прозрачность сообщений A2P, Google Сообщения показывают URL в рекомендуемых действиях "Открыть URL". Это изменение касается рекомендуемых действий в стандартных полезных подсказках и каруселях полезных подсказок.
Показ значка приложения для веб-ссылок. Если у пользователя есть приложение по умолчанию, настроенное для веб-страницы, то вместо браузера или компонента WebView откроется это приложение, а на кнопке подсказки будет показан его значок. Чтобы значок приложения показывался в Google Сообщениях, укажите полный прямой URL. Если вы используете сокращенный URL, вместо него будет показан значок "Открыть URL" по умолчанию.
Пример
В следующем примере кода отправляется действие по открытию URL. Подробнее
о форматировании и значенияхOpenUrlAction…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Как открыть URL с помощью компонента WebView
Действие "Открыть URL в WebView" загружает указанную веб-страницу в мессенджере с помощью механизма визуализации браузера по умолчанию. Это позволяет пользователю взаимодействовать с веб-страницей, не покидая чат RCS for Business. Если устройство пользователя не поддерживает компоненты WebView, веб-страница откроется в браузере. Инструкции по включению WebView приведены в статье OpenURLApplication.
У компонентов WebView есть три режима отображения. Варианты форматирования и значений приведены в WebviewViewMode.
- Полный. Веб-страница занимает весь экран.
- Половина экрана. Веб-страница занимает половину экрана.
- Высокий. Веб-страница занимает три четверти экрана.
Пример
В примере ниже показано, как отправить действие "Открыть URL в WebView". Подробнее OpenURLAction…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com", "application": "WEBVIEW", "webviewViewMode": "FULL", "description": "Accessibility description" } } } ] } }'
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { String URL = "https://www.google.com"; // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // Create suggestion to view webpage in full mode Suggestion viewInFullMode = getUrlActionInWebview(URL, "FULL") suggestions.add(viewInFullMode); // create suggestion to view webpage in half mode Suggestion viewInHalfMode = getUrlActionInWebview(URL, "HALF") suggestions.add(viewInHalfMode); // create suggestion to view webpage in tall mode Suggestion viewInTallMode = getUrlActionInWebview(URL, "TALL") suggestions.add(viewInTallMode); // Send simple text message with the suggested action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); } /** * Creates a suggested action to open URL in webview. * * @return a suggestion object for an open URL in webview action . */ private Suggestion getUrlActionInWebview(String url, String viewMode) { // create an open url action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl(url); openUrlAction.setApplication("WEBVIEW"); openUrlAction.setWebviewViewMode(viewMode); openUrlAction.setDescription("Accessibility description"); // attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setOpenUrlAction(openUrlAction); suggestedAction.setText('display_text'); suggestedAction.setPostbackData('postback_data_123'); // attach the action to a suggestion object Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); return suggestion; }
Как создать мероприятие в календаре
Действие "Создать мероприятие в календаре" открывает приложение календаря пользователя и начинает создавать новое мероприятие с указанной информацией.
Укажите название мероприятия из календаря. Максимальная длина – 100 символов. Описание мероприятия в календаре необязательно и может содержать не более 500 символов.
Пример
В следующем примере кода отправляется действие по созданию мероприятия в календаре. Подробнее CreateCalendarEventAction…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Список вариантов запросов
Агент отправляет списки вариантов запроса/вариантов действия вместе с сообщениями, чтобы направлять последующие действия пользователей. Список чипов показывается, только если связанное с ним сообщение находится внизу цепочки. Любые последующие сообщения в разговоре (от пользователя или агента) перезаписывают список чипов.
Чипы в списке – это готовые ответы и рекомендуемые действия.
В списке вариантов запроса может быть не более 11 чипов, а в каждом чипе – не более 25 символов.
Подробнее о форматировании и вариантах значенийAgentContentMessage…
Полезные подсказки
Полезные подсказки объединяют медиаконтент, текст и интерактивные предложения в одном сообщении. Они идеально подходят для представления связанной информации (например, товара с его изображением, названием и ценой) и подсказки пользователям четкого следующего шага, такого как предложение "Посмотреть подробности".
В полезной подсказке может быть следующее:
- Медиаконтент (изображение, GIF-файл или видео)
- Текст названия
- Текст описания
- Готовые ответы и рекомендуемые действия (максимум 4).
Все эти поля необязательны, но в полезной подсказке должно быть заполнено хотя бы одно из полей 1–3.
Несколько карточек можно отправить вместе в виде карусели с горизонтальной прокруткой.
Обратите внимание, что общий размер полезной нагрузки для карточки составляет 250 КБ.
Полную техническую информацию можно найти в документации по расширенным карточкам.
Высота полезной подсказки
Полезные подсказки расширяются по вертикали, чтобы вместить весь контент. Их минимальная высота составляет 112 dp, а максимальная – 344 dp. Если контент карточки не заполняет ее минимальную высоту, карточка расширяется, а дополнительная высота заполняется пробелами.
Для медиаконтента в полезных подсказках предусмотрено три варианта высоты:
- Короткое видео: 112 dp
- Средний: 168 DP
- Высокая: 264 dp
Если медиаконтент не соответствует размерам карточки с учетом выбранной высоты, он будет обрезан и масштабирован.
Пример
Следующий код отправляет карточку с изображением и предлагаемыми ответами. Подробнее о форматировании и вариантах значенийRichCard…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
Карусели полезных подсказок
Карусели объединяют несколько насыщенных карточек, позволяя пользователям сравнивать элементы и реагировать на каждый из них по отдельности.
В карусели может быть от двух до десяти карточек. Полезные подсказки в каруселях должны соответствовать общим требованиям к контенту и высоте, описанным в документации по полезным подсказкам. Подробную информацию о макете и спецификациях карусели можно найти в документации по каруселям.
Пример
Следующий код отправляет карусель полезных подсказок. Подробнее RichCardо форматировании и значениях
…
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "richCard": { "carouselCard": { "cardWidth": "MEDIUM", "cardContents": [ { "title": "Card #1", "description": "The description for card #1", "suggestions": [ { "reply": { "text": "Card #1", "postbackData": "card_1" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg", "forceRefresh": false } } }, { "title": "Card #2", "description": "The description for card #2", "suggestions": [ { "reply": { "text": "Card #2", "postbackData": "card_2" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg", "forceRefresh": false } } } ] } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Images for the carousel cards let card1Image = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; // Define the card contents for a carousel with two cards, each with one suggested reply let cardContents = [ { title: 'Card #1', description: 'The description for card #1', suggestions: [ { reply: { text: 'Card #1', postbackData: 'card_1', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card1Image, forceRefresh: false, }, }, }, { title: 'Card #2', description: 'The description for card #2', suggestions: [ { reply: { text: 'Card #2', postbackData: 'card_2', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card2Image, forceRefresh: false, }, }, }, ]; // Definition of carousel card let params = { msisdn: '+12223334444', cardContents: cardContents, }; // Send the device the carousel card defined above rbmApiHelper.sendCarouselCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.CardWidth; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); List cardContents = new ArrayList(); // Images for the carousel cards String card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; // Create suggestions for first carousel card List card1Suggestions = new ArrayList(); card1Suggestions.add( new SuggestionHelper("Card #1", "card_1")); cardContents.add( new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, card1Suggestions) .getCardContent(MediaHeight.SHORT) ); // Images for the carousel cards String card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Create suggestions for second carousel card List card2Suggestions = new ArrayList(); card2Suggestions.add( new SuggestionHelper("Card #2", "card_2")); cardContents.add( new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, card2Suggestions) .getCardContent(MediaHeight.SHORT) ); // Send the carousel to the user rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Images for the carousel cards card_image_1 = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; # Suggested replies to be used in the cards suggestions1 = [ messages.SuggestedReply('Card #1', 'reply:card_1') ] suggestions2 = [ messages.SuggestedReply('Card #2', 'reply:card_2') ] # Define the card contents for a carousel with two cards, # each with one suggested reply card_contents = [] card_contents.append(messages.CardContent('Card #1', 'The description for card #1', card_image_1, 'MEDIUM', suggestions1)) card_contents.append(messages.CardContent('Card #2', 'The description for card #2', card_image_2, 'MEDIUM', suggestions2)) # Send the device the carousel card defined above carousel_card = messages.CarouselCard('MEDIUM', card_contents) cluster = messages.MessageCluster().append_message(carousel_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Image references to be used in the carousel cards string card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Suggestion chip lists to be used in carousel cards List<Suggestion> suggestions1 = new List<Suggestion> { new SuggestionHelper("Card #1", "card_1").SuggestedReply() }; List<Suggestion> suggestions2 = new List<Suggestion> { new SuggestionHelper("Card #2", "card_2").SuggestedReply() }; // Create the card content for the carousel List<CardContent> cardContents = new List<CardContent> { // Add items as card content new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, suggestions1).GetCardContent(), new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, suggestions2).GetCardContent() }; // Send the carousel to the user rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);