Агенты RCS for Business общаются с пользователями, отправляя и получая сообщения. Чтобы отправлять сообщения пользователям, ваш агент отправляет запросы сообщений в API RCS Business Messaging. Один запрос может включать текст, расширенные карточки, медиа- и PDF-файлы, предложенные ответы и предложенные действия.
Платформа RCS for Business возвращает ошибки в определенных ситуациях, чтобы помочь вам управлять доставкой сообщений:
- Если вы отправите сообщение пользователю, чье устройство не поддерживает RCS или на котором не включен RCS, платформа RCS for Business вернет ошибку
404 NOT_FOUND. В этом случае вы можете попытаться связаться с пользователем, используя резервные методы, определенные в вашей инфраструктуре. - Если вы отправите сообщение пользователю RCS в сети, где ваш агент ещё не запущен или где не включен трафик RCS, платформа RCS для бизнеса вернет ошибку
404 NOT_FOUND. - Если вы отправите сообщение с функциями, которые не поддерживаются на устройстве пользователя, платформа RCS for Business вернет ошибку
400 INVALID_ARGUMENTи не доставит ваше сообщение.
В рамках многоканальной стратегии обмена сообщениями рекомендуется отзывать сообщения, которые не были доставлены в течение разумного времени, и отправлять их по другому каналу. Чтобы сообщения автоматически отзывались в заданное время, настройте срок действия сообщений.
Получатель не в Сети
Платформа RCS for Business принимает сообщения для доставки, даже если получатель не в сети. Вы получаете ответ 200 OK, и платформа RCS для бизнеса удерживает сообщение и пытается повторно отправить его в течение 30 дней. Не нужно просить RCS for Business отправить сообщение ещё раз.
RCS for Business удаляет все недоставленные сообщения через 30 дней после их отправки.
В зависимости от варианта использования вашего агента, вы можете отозвать недоставленное сообщение до истечения 30-дневного срока. Отзыв может предотвратить получение пользователями, работающими в офлайн-режиме, устаревшего сообщения, когда они снова подключатся к интернету. Отменить отправку сообщения можно несколькими способами:
- Отправьте запрос на отзыв, чтобы запустить отзыв.
- Установите срок действия письма, чтобы оно автоматически было отозвано в нужный момент.
ограничить срок доступа к письму;
Сообщение агента срочное? Например, одноразовые коды действуют только в течение короткого периода времени. Срок действия временных предложений истекает. Напоминания о встречах теряют актуальность после даты встречи. Чтобы сообщения были актуальными, установите срок их действия. Это позволит избежать ситуации, когда пользователи, вернувшиеся в онлайн, получают устаревший контент. Истечение срока действия – хороший повод для того, чтобы применить резервную стратегию обмена сообщениями и своевременно предоставить пользователям нужную информацию.
Чтобы задать срок действия сообщения, укажите одно из следующих полей в сообщении агента:
expireTime– точное время в UTC, когда срок действия сообщения истекает.ttl(время жизни) – время, по истечении которого срок действия сообщения истекает.
Варианты форматирования и значений приведены в разделе AgentMessage.
Максимальное значение для ttl и expireTime – 15 дней после отправки письма.
Минимальные значения ttl и expireTime не заданы, но мы рекомендуем устанавливать значение не менее 10 секунд после отправки сообщения, чтобы значительно снизить вероятность получения уведомлений об отзыве и доставке.
Время жизни сообщения (TTL)
Когда вы задаете TTL для сообщения RCS for Business, вы указываете, как долго сообщение должно считаться действительным и доставляемым. Если сообщение не будет доставлено на устройство пользователя в течение этого периода, платформа RCS для бизнеса автоматически попытается отозвать его.
Когда вы отзываете сообщение, вы просите платформу RCS for Business прекратить попытки его доставки. Однако это действие повлияет только на будущие попытки доставки. Если устройство пользователя уже успешно получило сообщение, оно обрабатывается, и платформа RCS для бизнеса не может отозвать сообщение с устройства пользователя.
Вот что нужно знать об уведомлениях:
Сообщение доставлено до истечения срока жизни (TTL). Если устройство пользователя подключится к сети и получит сообщение до истечения срока жизни, вы получите уведомление
DELIVERED. Уведомление об отзыве не будет отправлено, так как письмо было успешно доставлено. Это самый распространенный и ожидаемый сценарий.Сообщение не доставлено до истечения срока жизни. Если срок жизни истекает до того, как сообщение достигает устройства пользователя (например, устройство находится в офлайн-режиме), платформа RCS для бизнеса пытается отозвать сообщение. Вы получите уведомление
TTL_EXPIRATION_REVOKEDо том, что письмо успешно удалено из очереди доставки. В этом случае пользователь не получит письмо.
Рекомендации по обработке пограничных случаев
Наша система обрабатывает доставку сообщений RCS for Business и истечение срока жизни параллельно. Поэтому в редких случаях вы можете получать уведомления в неожиданное время. Например, вы можете получить уведомление о доставке и уведомление о времени жизни или не получить ни одного из них.
Вот наши рекомендации по обработке уведомлений о сообщениях RCS for Business:
Уведомление
DELIVEREDподтверждает, чтоDELIVEREDписьмо было доставлено пользователю. Вы можете проигнорировать все последующие уведомления о TTL для этого письма.Уведомление
TTL_EXPIRATION_REVOKED. Если вы получили уведомление о времени жизни со статусомTTL_EXPIRATION_REVOKED, это означает, что система RCS для бизнеса прекратила попытки доставить определенное сообщение. В этом случае сообщение следует считать недоставленным и при необходимости использовать резервную стратегию.Уведомление 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 для бизнеса, составляет 100 МиБ, а общий размер всех медиафайлов и PDF-документов, прикрепленных к одному сообщению RCS для бизнеса, не должен превышать 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 сайта с тегами Open Graph, клиент может сгенерировать предварительный просмотр (изображение, заголовок и т. д.), чтобы сделать сообщение более привлекательным. Например, посмотрите простое сообщение с предпросмотром URL.
Учитывайте, что клиент RCS может позволять пользователю отключать предпросмотр ссылок.
Одноразовые пароли для подтверждения личности пользователя
С помощью RCS for Business можно отправлять одноразовые коды (OTP) для автоматической проверки пользователей с помощью SMS Retriever API. Отдельного API для чтения одноразовых паролей, полученных через RCS для бизнеса, нет.
Как это работает на устройствах Android
Приложения Android, зарегистрированные в SMS Retriever API, отслеживают сообщения RCS for Business в правильном формате. В этом сообщении должны быть одноразовый код и уникальный хеш, идентифицирующий ваше приложение.
Если сообщение RCS for Business имеет правильный формат, API SMS Retriever обрабатывает его так же, как и 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 для бизнеса, как и одноразовые коды SMS. Для того чтобы приложение для iOS могло считывать одноразовые пароли, не требуется специальная интеграция API.
медиафайлы и PDF-файлы;
Если вы отправляете сообщение с изображением, видео, аудио или PDF-файлом, ваш агент должен предоставить общедоступный URL для контента или напрямую загрузить файл.
Максимальный размер отправляемого файла – 100 МиБ. Общий размер всех медиафайлов и PDF-документов, прикрепленных к одному письму, не должен превышать 100 МиБ.
Сжатие и перекодирование медиафайлов
Платформа RCS для бизнеса автоматически перекодирует и сжимает медиафайлы (например, изображения и видео) перед отправкой, чтобы они быстро загружались и хорошо работали в разных сетях и на разных устройствах.
Сжатие выполняется с учетом качества исходного медиаконтента, а не только ограничений на размер файла. Это означает, что файл можно сжать, даже если его размер значительно меньше максимального ограничения в 100 МиБ. Стандарты транскодирования постоянно меняются, поэтому нет фиксированного ограничения на размер файла, при котором транскодирование не выполняется. Экспериментируйте с разными форматами, размерами и уровнями сжатия медиаконтента, чтобы найти оптимальный баланс для своих полезных нагрузок.
Требования к значкам
Для медиафайлов можно также указать изображение, которое будет показываться пользователям в качестве значка. Для аудиофайлов в качестве плейсхолдера используется виджет audio по умолчанию.
- Максимальный размер файла эскиза – 100 КБ. Для оптимального удобства пользователей рекомендуем, чтобы размер файла был не более 50 КБ.
- Соотношение сторон значка должно совпадать с соотношением сторон исходного файла.
Кэширование и управление URL
Платформа RCS для бизнеса кеширует файлы в течение 60 дней, а API возвращает идентификатор файла, который ваш агент может включить в сообщения пользователям. Через 60 дней RCS для бизнеса удаляет файлы из кеша.
Если вы указываете файлы по 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.
| MIME-тип | Тип документа | Расширение | Поддержка полезных подсказок |
|---|---|---|---|
| application/ogg | Аудио OGG | OGX | Нет |
| application/pdf | Да (только для Google Сообщений в Индии) | ||
| audio/aac | Аудио в формате AAC | AAC | Нет |
| audio/mp3 | Звук в формате MP3 | MP3 | Нет |
| audio/mpeg | Аудио MPEG | 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.
Набрать номер
Действие 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. Чтобы повысить прозрачность обмена сообщениями между приложениями и пользователями, в Google Сообщениях исходный URL-адрес показывается в рекомендуемых действиях "Открыть URL". Это изменение касается предлагаемых действий в стандартных полезных подсказках и каруселях полезных подсказок.
Значок приложения для веб-ссылок. Если для веб-страницы задано приложение по умолчанию, оно откроется вместо браузера или веб-представления, а на кнопке подсказки будет показан значок приложения. Чтобы значок приложения показывался в 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-чат с компанией. Если устройство пользователя не поддерживает встроенные браузеры, веб-страница откроется в браузере. Чтобы включить веб-представления, следуйте инструкциям в статье OpenURLApplication.
У встроенных браузеров есть три режима показа. Варианты форматирования и значений приведены в разделе 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-файлы или видео)
- Текст названия
- Текст описания
- Быстрые ответы и рекомендуемые действия (до четырех).
Каждое из этих полей необязательно, но хотя бы одно из полей 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);