Агенты RBM взаимодействуют с пользователями, отправляя и получая сообщения. Для отправки сообщений пользователям ваш агент отправляет запросы на сообщения в API RCS Business Messaging. Один запрос может включать текст , форматированные карточки , медиафайлы и PDF-файлы , а также предлагаемые ответы и действия .
Платформа RBM будет возвращать ошибки в определенных ситуациях, чтобы помочь вам управлять доставкой сообщений:
- Если вы отправляете сообщение пользователю, устройство которого не поддерживает RCS или на котором RCS не включён, платформа RBM возвращает ошибку 404 NOT_FOUND. В этом случае вы можете попытаться связаться с пользователем, используя резервные методы, определённые в вашей инфраструктуре.
- Если вы отправляете сообщение пользователю RCS в сети, где ваш агент еще не запущен, или в сети, в которой не включен трафик RCS, платформа RBM возвращает ошибку 404 NOT_FOUND.
- Если вы отправляете сообщение с функциями, которые устройство пользователя не поддерживает, платформа RBM возвращает ошибку 400 INVALID_ARGUMENT и не доставляет ваше сообщение.
В рамках вашей многоканальной стратегии обмена сообщениями рекомендуется отзывать сообщения , не доставленные по истечении разумного срока, и отправлять их по другому каналу. Чтобы автоматически отзывать сообщения по истечении заданного времени, установите срок действия сообщения .
Получатель не в сети
Платформа RBM по-прежнему принимает сообщения к отправке, даже если получатель не в сети. Вы получаете ответ 200 OK, и платформа RBM удерживает сообщение и пытается доставить его повторно в течение 30 дней. Вам не нужно запрашивать RBM для повторной отправки сообщения.
RBM удаляет все недоставленные сообщения через 30 дней после их отправки.
В зависимости от сценария использования вашего агента, вам может потребоваться отозвать недоставленное сообщение до истечения этого 30-дневного срока. Отзыв может предотвратить получение устаревшего сообщения пользователями, находящимися в автономном режиме, при их возвращении в сеть. Существует несколько способов отозвать сообщение:
- Отправьте запрос на отзыв , чтобы инициировать отзыв.
- Установите срок действия сообщения , чтобы автоматически отозвать его в подходящее время.
Установить срок действия сообщения
Чувствительны ли сообщения вашего агента ко времени? Например, одноразовые пароли действительны только в течение короткого периода времени. Ограниченные по времени предложения истекают. А напоминания о встречах теряют актуальность после назначенной даты. Чтобы сообщения оставались актуальными и актуальными, установите срок действия сообщения. Это поможет предотвратить получение устаревшего контента пользователями, находящимися офлайн, после их возвращения в сеть. Срок действия сообщения также может стать хорошим сигналом для использования вашей резервной стратегии обмена сообщениями, чтобы пользователи своевременно получали необходимую информацию.
Чтобы установить срок действия сообщения, укажите одно из следующих полей в сообщении агента:
-
expireTime: точное время в формате UTC, когда истекает срок действия сообщения. -
ttl(время жизни): время до истечения срока действия сообщения.
Параметры форматирования и значений см. в разделе AgentMessage .
По истечении срока действия сообщения платформа RBM прекращает попытки его доставки, и сообщение автоматически отзывается. Однако в редких случаях это может не сработать. Например, API может инициировать отзыв, пока платформа RBM доставляет сообщение. Чтобы подтвердить, было ли успешно отозвано просроченное сообщение, RBM отправит уведомление на ваш вебхук.
Максимальное значение ttl и expireTime составляет 15 дней после отправки сообщения.
Хотя минимальных значений ttl и expireTime не существует, рекомендуется использовать не менее 10 секунд после отправки сообщения, чтобы существенно снизить вероятность получения уведомлений как об отзыве, так и о доставке.
Установите тип трафика сообщения
API RBM включает поле messageTrafficType для категоризации сообщений. Хотя сценарии использования агента по-прежнему определяют его поведение и применяемые бизнес-правила, messageTrafficType обеспечивает более детальную категоризацию содержимого сообщений. В конечном итоге это позволит одному агенту обрабатывать несколько сценариев использования. На данный момент это не повлияет на существующие сценарии использования агента или бизнес-правила.
Это поле необязательно для заполнения, но рекомендуется задать его сейчас, чтобы не получить сообщение об ошибке, когда поле станет обязательным.
Чтобы задать тип трафика сообщения, назначьте соответствующий messageTrafficType для каждого сообщения в зависимости от его содержания. RBM поддерживает следующие типы трафика.
| Тип трафика | Содержание сообщения | Вариант использования агента |
|---|---|---|
AUTHENTICATION | Для сообщений аутентификации. | ОТП |
TRANSACTION | Для сообщений о существующих услугах или продуктах пользователя. Например: подтверждения, квитанции об оплате или информация о бронировании. | Транзакционный или многоцелевой |
PROMOTION | Для рекламных сообщений, таких как предложения, скидки, объявления или другой рекламный контент. | Рекламные или многоцелевые |
SERVICEREQUEST | Для сообщений об услугах, которые пользователь явно запросил. | Одноразовый, транзакционный, рекламный или многоразовый |
ACKNOWLEDGEMENT | Для сообщений, используемых для подтверждения действия пользователя, в частности, запроса на отмену подписки. Это подтверждает, что запрос пользователя получен и обрабатывается. | Одноразовый, транзакционный, рекламный или многоразовый |
Если тип трафика не установлен, система назначает тип по умолчанию для варианта использования агента .
| Вариант использования агента | Тип трафика по умолчанию |
|---|---|
| ОТП | AUTHENTICATION |
| Транзакционный | TRANSACTION |
| Рекламный | PROMOTION |
| Многоцелевой | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
У многоцелевых агентов нет типа трафика по умолчанию. Тип трафика необходимо задавать явно для каждого сообщения в зависимости от его содержимого. Если не заменить значение MESSAGE_TRAFFIC_TYPE_UNSPECIFIED , возникнет ошибка.
Ограничения на размер сообщения
Максимальный размер всего строкового сообщения AgentMessage составляет 250 КБ. Текстовая часть сообщения имеет ограничение в 3072 символа.
Максимальный размер файла, отправляемого через RBM, составляет 100 МБ. Подробнее см. в разделе «Медиафайлы и 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); });
Ява
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(); }
Питон
# 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')
С#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Содержание базового сообщения - преобразование SMS
Операторы связи внедрили модели биллинга для поддержки переноса SMS-сообщений в RBM. Сообщение RBM, содержащее до 160 символов UTF-8, называется базовым сообщением.
При формировании запроса на отправку базового сообщения помните, что символы считаются за 1 байт (UTF-8). Если вы отправляете сообщение, содержащее специальные символы, такие как эмодзи или многобайтовые наборы символов, каждый символ считается за 2–4 символа UTF-8 или более.
Введите текст в поле, чтобы проверить его длину:
Содержание основного сообщения и предварительный просмотр ссылок
Клиенты RCS могут реализовывать предварительный просмотр ссылок. Если текстовое сообщение RBM содержит URL-адрес веб-сайта с тегами openGraph , может отображаться изображение предварительного просмотра, создающее впечатление более насыщенного контента.
Имейте в виду, что клиент RCS может разрешить пользователю отключать предварительный просмотр ссылок.
Одноразовые пароли для проверки пользователя
Вы можете использовать RBM для отправки одноразовых паролей (OTP) для автоматической верификации пользователей с помощью API SMS Retriever. Специального API для чтения одноразовых паролей, полученных через RBM, не существует.
Как это работает на Android
Для приложений Android, зарегистрированных в API SMS Retriever , API ожидает корректно отформатированное RBM-сообщение. Это сообщение должно содержать как одноразовый пароль (OTP), так и уникальный хеш, идентифицирующий ваше приложение.
При получении RBM-сообщения в правильном формате API SMS Retriever обрабатывает его так же, как одноразовый пароль SMS. После сопоставления хеша с вашим приложением одноразовый пароль извлекается и пересылается в ваше приложение для автоматической проверки пользователя.
- Пример текстового сообщения RBM для проверки пользователя:
Your code is <OTP> <app hash>. - Пример:
Your code is 123456 M8tue43FGT.
Подробнее об SMS Retriever и связанных API см. в документации SMS Retriever . Подробную информацию об автоматической проверке пользователей в приложениях, зарегистрированных с помощью API SMS Retriever, см. на этой схеме .
Как это работает для iOS
В iOS встроенная система обработки одноразовых паролей автоматически распознаёт и предлагает RBM-одноразовые пароли для автозаполнения, как и SMS-одноразовые пароли. Для чтения одноразовых паролей в iOS-приложении не требуется специальной интеграции с API.
Медиа и PDF-файлы
При отправке сообщения с изображением, видео, аудио или PDF-файлом ваш агент должен предоставить общедоступный URL-адрес этого контента или напрямую загрузить файл. Для медиафайлов вы также можете указать миниатюру, которая позволит пользователям предварительно просмотреть контент перед нажатием на него. Для аудиофайлов в качестве заполнителя используется аудиовиджет по умолчанию.
Платформа RBM кэширует файлы на 60 дней, а API возвращает идентификатор файла, который ваш агент может включать в сообщения пользователям. По истечении 60 дней RBM удаляет файлы из кэша.
При указании файлов по URL рекомендуется установить contentMessage.forceRefresh в false . Установка contentMessage.forceRefresh в true заставляет RBM извлекать новый контент с указанного 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); });
Ява
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(); }
Питон
# 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')
С#
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" } } }'
Поддерживаемые типы носителей
RBM поддерживает следующие типы медиафайлов: для миниатюр поддерживаются только форматы image/jpeg, image/jpg, image/gif и image/png.
| Тип носителя | Тип документа | Расширение | Работает с расширенными картами |
|---|---|---|---|
| приложение/ogg | OGG аудио | .ogx | Нет |
| приложение/pdf | Нет | ||
| аудио/aac | AAC-аудио | .aac | Нет |
| аудио/mp3 | MP3-аудио | .mp3 | Нет |
| аудио/mpeg | MPEG-аудио | .mpeg | Нет |
| аудио/миль на галлон | MPG аудио | .mp3 | Нет |
| аудио/mp4 | MP4 аудио | .mp4 | Нет |
| аудио/mp4-latm | MP4-latm аудио | .mp4 | Нет |
| аудио/3gpp | 3GPP аудио | .3gp | Нет |
| изображение/jpeg | JPEG | .jpeg, .jpg | Да |
| изображение/гифка | GIF | .gif | Да |
| изображение/png | PNG | .png | Да |
| видео/h263 | видео H263 | .h263 | Да |
| видео/m4v | видео M4V | .m4v | Да |
| видео/mp4 | видео MP4 | .mp4 | Да |
| видео/mpeg4 | видео MPEG-4 | .mp4, .m4p | Да |
| видео/mpeg | MPEG-видео | .mpeg | Да |
| видео/вебм | WEBM-видео | .webm | Да |
Предложения
Ваш агент отправляет предложения (предлагаемые ответы и предлагаемые действия) в списках фишек предложений (максимум 11 предложений) или в расширенных карточках (максимум четыре предложения).
Каждое предложение может содержать не более 25 символов.
Предлагаемые ответы
Предлагаемые ответы направляют пользователей по беседам, предоставляя ответы, на которые ваш агент знает, как реагировать.
Когда пользователь нажимает на предложенный ответ, ваш агент получает событие , содержащее текст ответа и данные постбэка. Длина полезной нагрузки не должна превышать 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); });
Ява
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(); }
Питон
# 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')
С#
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 .
Набрать номер
Действие «Набрать номер» позволяет пользователю набрать номер телефона, указанный вашим агентом. Номера телефонов могут содержать только цифры ( 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); });
Ява
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(); }
Питон
# 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')
С#
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); });
Ява
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(); }
Питон
# 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')
С#
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); });
Ява
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(); }
Питон
# 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')
С#
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» позволяет направлять пользователей на веб-страницу, указанную вашим агентом. По умолчанию веб-страница открывается в браузере пользователя. Если у пользователя настроено приложение по умолчанию для веб-страницы, откроется это приложение. В этом случае значок на кнопке предлагаемого действия будет соответствовать значку этого приложения.
Действие «Открыть 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); });
Ява
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(); }
Питон
# 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')
С#
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 с помощью веб-просмотра» загружает указанную веб-страницу в приложение обмена сообщениями с помощью движка рендеринга вашего браузера по умолчанию. Это позволяет пользователю взаимодействовать с веб-страницей, не выходя из диалога RBM. Если устройство пользователя не поддерживает веб-просмотры, веб-страница открывается в браузере. Чтобы включить веб-просмотры, см. OpenURLApplication .
Webviews имеют три режима отображения. Параметры форматирования и значений см. в разделе WebviewViewMode .
- Полный: веб-страница занимает весь экран.
- Половина: веб-страница занимает половину экрана.
- Высокий: веб-страница занимает три четверти экрана.
Пример
Следующий код отправляет команду Open 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" } } } ] } }'
Ява
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); });
Ява
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(); }
Питон
# 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')
С#
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 .
Богатые карты
Если вам нужно отправить фрагмент связанной информации, медиафайлов или предложений, отправьте расширенную карточку. Расширенные карточки позволяют вашему агенту отправлять несколько блоков информации в одном сообщении.
Карты с расширенным функционалом могут содержать следующие элементы:
- Изображение или видео
- Текст заголовка
- Текст описания
- Предлагаемые ответы и предлагаемые действия (максимум 4)
Расширенная карточка может содержать все перечисленные элементы, но для того, чтобы считаться действительной, она должна содержать как минимум изображение, видео или заголовок. Расширенная карточка может содержать максимум четыре предлагаемых действия и варианта ответа .
Ваш агент может отправлять несколько расширенных карточек одновременно в карусели расширенных карточек .
Максимальный размер полезной нагрузки расширенной карты составляет 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); });
Ява
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(); }
Питон
# 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')
С#
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");
Карусели с богатыми картами
Если вам нужно предоставить пользователю несколько вариантов выбора, используйте карусель с расширенными карточками. Карусели объединяют несколько расширенных карточек , позволяя пользователям сравнивать элементы и реагировать на каждый из них по отдельности.
Карусели могут содержать от двух до десяти расширений. Расширения в каруселях должны соответствовать общим требованиям к содержанию и высоте расширений. Характеристики каруселей можно найти в разделе «Расширения» .
Максимальный размер полезной нагрузки расширенной карусели карточек составляет 250 КБ. Ознакомьтесь с рекомендациями по размеру медиафайлов и ограничениями.
Усечение
Как и в случае с расширенными карточками , на то, как карточки выглядят для конечных пользователей, влияет множество факторов (например, разрешение экрана, плотность пикселей и пользовательские настройки). Однако в карусели высота первых нескольких карточек определяет высоту всех карточек в карусели, а высота карточки влияет на заголовок, описание и обрезку подсказок.
Если устройство не может отобразить все элементы карты из-за ограничений дисплея или высоты карты, RBM обрезает карту до тех пор, пока она не сможет отобразиться на устройстве, используя следующую логику:
- Сократите описание до одной строки.
- Сократите заголовок до одной строки.
- Исключите предложения, которые не помещаются в карточку, начиная с конца определенного списка.
- Опустить описание.
- Опустить заголовок.
Чтобы избежать усечения, используйте максимально короткие заголовки и описания. Для больших медиа-файлов используйте либо заголовок и описание, либо один вариант. Для средних медиа-файлов используйте до двух вариантов. Для коротких медиа-файлов используйте до трёх вариантов. Чтобы уместить четыре варианта, не включайте медиа-файлы в карточку.
Поддерживайте примерно одинаковый размер и длину содержимого карточек, а при необходимости загружайте в карусель в начале карточки большего размера, чтобы избежать обрезки последующих карточек.
Пример
Следующий код отправляет расширенную карусель карточек. Варианты форматирования и значений см. в 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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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/kitchen-sink-sample-images/cute-dog.jpg'; let card2Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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); });
Ява
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/kitchen-sink-sample-images/cute-dog.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/kitchen-sink-sample-images/elephant.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(); }
Питон
# 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/kitchen-sink-sample-images/cute-dog.jpg'; card_image_2 = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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')
С#
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/kitchen-sink-sample-images/cute-dog.jpg"; string card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.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);