Отправка сообщений

Агенты RCS for Business общаются с пользователями, отправляя и получая сообщения. Чтобы отправлять сообщения пользователям, агент отправляет запросы в RCS Business Messaging API. Один запрос может содержать текст, полезные подсказки, медиафайлы и PDF-файлы, готовые ответы и рекомендуемые действия.

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

  • Если вы отправите сообщение пользователю, устройство которого не поддерживает RCS или на котором RCS не включен, платформа RCS for Business вернет ошибку 404 NOT_FOUND. В этом случае вы можете попытаться связаться с пользователем с помощью резервных методов, определенных в вашей инфраструктуре.
  • Если вы отправите сообщение пользователю RCS в сети, где ваш агент ещё не запущен или где не включен трафик RCS, платформа RCS for Business вернет ошибку 404 NOT_FOUND.
  • Если вы отправите сообщение с функциями, которые не поддерживаются на устройстве пользователя, платформа RCS for Business вернет ошибку 400 INVALID_ARGUMENT и не доставит сообщение.

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

Получатель не в Сети

Платформа RCS for Business принимает сообщение для доставки, даже если получатель офлайн. Вы получите ответ 200 OK, а платформа RCS for Business сохранит сообщение и будет пытаться повторно отправить его в течение 30 дней. Запрашивать повторную отправку сообщения в RCS for Business не нужно.

RCS for Business удаляет все недоставленные сообщения через 30 дней после их отправки.

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

ограничить срок доступа к письму;

Сообщение агента срочное? Например, одноразовые пароли действительны только в течение короткого периода времени. Срок действия временных предложений истекает. А напоминания о встречах неактуальны после даты встречи. Чтобы сообщения оставались актуальными, задайте срок их действия. Это позволяет избежать ситуации, когда пользователи, работающие в офлайн-режиме, получают устаревший контент, когда снова подключаются к интернету. Истечение срока действия – это также хороший повод задействовать резервную стратегию обмена сообщениями, чтобы пользователи вовремя получали нужную информацию.

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

  • expireTime – точное время по UTC, когда истекает срок действия сообщения.
  • ttl(время жизни) – время, по истечении которого сообщение удаляется.

Подробнее о форматировании и вариантах значенийAgentMessage…

Максимальное значение для ttl и expireTime – 15 дней после отправки сообщения.

Минимальное значение для ttl и expireTime – шесть секунд после отправки сообщения.

Рекомендации по настройке срока действия сообщений

  • Для сообщений аутентификации (одноразовых кодов) установите для параметра ttl значение 15 секунд или больше после отправки сообщения, чтобы значительно снизить вероятность состояния гонки при доставке и отзыве.

  • Для транзакционных и рекламных сообщений задайте более длительный срок действия (не менее 60 секунд, а в зависимости от ситуации – от нескольких минут до нескольких часов). Это связано с тем, что устройствам требуется дополнительное время для сканирования сообщений и скачивания или обработки мультимедийного контента, а у пользователей могут возникать кратковременные перебои со связью (например, в лифте или туннеле).

Время жизни (TTL) сообщения

Когда вы задаете TTL для сообщения RCS for Business, вы указываете, как долго сообщение должно считаться действительным и доступным для доставки. Если сообщение не будет доставлено на устройство пользователя в течение этого времени, платформа RCS for Business автоматически попытается его отозвать.

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

Вот что нужно знать об уведомлениях:

  • Сообщение доставлено в течение TTL. Если устройство пользователя подключится к интернету и получит сообщение до истечения TTL, вы получите уведомление DELIVERED. Уведомление об отзыве не будет отправлено, поскольку сообщение было успешно доставлено. Это самый распространенный и ожидаемый сценарий.

  • Сообщение не доставлено до истечения TTL. Если TTL истекает до того, как сообщение доходит до устройства пользователя (например, устройство находится в офлайн-режиме), платформа RCS Business Messaging пытается отозвать сообщение. Вы получите уведомление TTL_EXPIRATION_REVOKED, которое означает, что письмо было удалено из очереди доставки. В этом случае пользователь не получит сообщение.

Рекомендации по обработке пограничных случаев

Наша система обрабатывает доставку сообщений RCS for Business и истечение срока TTL параллельно. Поэтому в редких случаях уведомления могут приходить в неожиданное время. Например, вы можете получить уведомление о доставке и TTL или не получить ни одного.

Вот наши рекомендации по обработке уведомлений о сообщениях RCS for Business:

  • Уведомление DELIVERED. Если вы получили уведомление DELIVERED, значит сообщение доставлено пользователю. Вы можете игнорировать все последующие уведомления TTL для этого сообщения.

  • Уведомление TTL_EXPIRATION_REVOKED. Если вы получили уведомление TTL со статусом TTL_EXPIRATION_REVOKED, это означает, что система RCS for Business прекратила попытки доставки этого сообщения. Вам следует считать это сообщение недоставленным и при необходимости перейти к резервной стратегии.

  • Уведомление TTL с любым другим статусом. Если вы получили уведомление TTL с любым другим статусом, это означает, что попытка отзыва не дала результатов.

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

Как задать тип трафика сообщений

В RBM API есть поле messageTrafficType, которое позволяет классифицировать сообщения. Варианты использования агента по-прежнему определяют его поведение и применяемые бизнес-правила, но messageTrafficType позволяет более детально классифицировать контент сообщений. В конечном итоге это позволяет одному агенту обрабатывать несколько вариантов использования. В настоящее время это не влияет на существующие сценарии использования агентов или бизнес-правила.

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

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

Тип трафика Текст сообщения Рекомендуемый пример использования агента
AUTHENTICATION Для сообщений аутентификации. Одноразовый код
TRANSACTION Сообщения о существующих сервисах или продуктах пользователя. Например, это могут быть подтверждения, квитанции об оплате или сведения о бронировании. Транзакция или несколько вариантов использования
PROMOTION Для рекламных сообщений, например предложений, скидок, объявлений и другого рекламного контента. Рекламные или многоцелевые
SERVICEREQUEST Для сообщений об услугах, которые пользователь явно запросил. Одноразовый код, транзакции, реклама или многоцелевое использование
ACKNOWLEDGEMENT Для сообщений, подтверждающих действие пользователя, в частности запрос на отмену подписки. Это подтверждает, что запрос пользователя получен и обрабатывается. Одноразовый код, транзакции, реклама или многоцелевое использование

Если тип трафика не задан, система назначает тип по умолчанию для сценария использования агента.

Пример использования агентом Тип трафика по умолчанию
OTP AUTHENTICATION
Транзакционные TRANSACTION
Рекламные PROMOTION
Многоразовые MESSAGE_TRAFFIC_TYPE_UNSPECIFIED

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

Ограничения на размер писем

Максимальный размер всего сериализованного объекта AgentMessage составляет 250 КБ. Текстовая часть сообщения не должна превышать 3072 символа.

Чтобы избежать непредвиденного расхода трафика у пользователей, максимальный размер файла, который можно отправить через RCS for Business, составляет 100 МиБ. Общий размер всех медиафайлов и PDF-файлов, прикрепленных к одному сообщению RCS for Business, не должен превышать 100 МиБ. (1 МиБ = 1 048 576 байт). Подробнее о медиафайлах и PDF-файлах…

Текст

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

Пример

Следующий код отправляет обычное текстовое сообщение. Варианты форматирования и значений описаны в статье phones.agentMessages.create.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!"
  },
  "messageTrafficType": "PROMOTION"
}'

Node.js

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

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
};

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

C#

using RCSBusinessMessaging;
…

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

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "+12223334444",
);
Этот код взят из примера агента RBM.

Содержимое базового сообщения – преобразование SMS

Операторы ввели модели оплаты, чтобы поддержать переход с SMS на RCS for Business. Сообщение RCS for Business, содержащее до 160 символов UTF-8, называется базовым.

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

Введите текст в поле, чтобы проверить его длину:

В RCS-клиентах может быть реализован предпросмотр ссылок. Если текстовое сообщение RCS for Business содержит URL сайта с тегами openGraph, клиент может сгенерировать предпросмотр (изображение, заголовок и т. д.), чтобы сделать сообщение более привлекательным. Например, посмотрите простое сообщение с предпросмотром URL.

Учтите, что RCS-клиент может позволять пользователю отключать предпросмотр ссылок.

Одноразовые коды для подтверждения личности пользователя

Вы можете использовать RCS for Business, чтобы отправлять одноразовые коды для автоматической проверки пользователей с помощью SMS Retriever API. Специального API для чтения одноразовых кодов, полученных через RCS for Business, нет.

Как это работает на устройствах Android

Если приложение Android зарегистрировано в SMS Retriever API, этот API ожидает правильно отформатированное сообщение RCS for Business. В сообщении должен быть одноразовый код и уникальный хеш, который идентифицирует ваше приложение.

Когда сообщение RCS for Business получено в правильном формате, SMS Retriever API обрабатывает его так же, как и одноразовый код из SMS. После того как хеш будет сопоставлен с вашим приложением, одноразовый код будет извлечен и перенаправлен в приложение для автоматической проверки пользователя.

  • Пример текстового сообщения RCS for Business для подтверждения пользователя: Your code is <OTP><app hash>.
  • Пример: Your code is 123456 M8tue43FGT.

Дополнительную информацию об SMS Retriever и связанных API можно найти в документации по SMS Retriever. Подробные сведения об автоматической проверке пользователей в приложениях, зарегистрированных с помощью SMS Retriever API, приведены на блок-схеме.

Как это работает на устройствах iOS

На устройствах iOS встроенная система обработки одноразовых кодов автоматически обнаруживает и предлагает одноразовые коды RCS for Business для автозаполнения, как и одноразовые коды SMS. Для чтения одноразового кода в приложении iOS не требуется интеграция с API.

Медиафайлы и PDF-файлы

При отправке сообщения с изображением, видео, аудио или PDF-файлом агент должен предоставить общедоступный URL контента или загрузить файл напрямую.

Максимальный размер файла, который можно отправить, составляет 100 МиБ, а общий размер всех медиафайлов и PDF-файлов в одном сообщении не должен превышать 100 МиБ.

Сжатие и перекодирование медиафайлов

Платформа RCS for Business автоматически перекодирует и сжимает медиафайлы (например, изображения и видео) перед отправкой, чтобы они быстро загружались и корректно работали в разных сетях и на разных устройствах.

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

Требования к значкам

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

  • Максимальный размер файла значка – 100 КБ. Для оптимального удобства пользователей мы рекомендуем, чтобы он не превышал 50 КБ.
  • Соотношение сторон значка должно соответствовать соотношению сторон исходного файла.

Кеширование и управление URL

Платформа RCS for Business кеширует файлы на 60 дней, а API возвращает идентификатор файла, который агент может включать в сообщения пользователям. Через 60 дней RCS for Business удаляет файлы из кеша.

Если вы указываете файлы по URL, рекомендуем задать для параметра contentMessage.forceRefresh значение false. Если для параметра contentMessage.forceRefresh задано значение true, RCS for Business будет получать новый контент по указанному URL, даже если контент по этому URL кеширован. Это увеличивает время доставки сообщений пользователям.

Пример URL файла

Следующий код отправляет изображение. Варианты форматирования и значений приведены в AgentContentMessage.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "contentInfo": {
      "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif",
      "forceRefresh": false
    }
  }
}'

Node.js

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

let params = {
   fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
   msisdn: '+12223334444',
};

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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");
Этот код взят из примера агента RBM.

Вы также можете загрузить медиафайлы перед отправкой в сообщении с помощью 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 JSON


curl -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 JSON


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": {
    "uploadedRbmFile": {
      "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME",
      "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME"
    }
  }
}'

Поддерживаемые типы медиаконтента

RCS for Business поддерживает следующие типы медиаконтента. Для значков поддерживаются только форматы image/jpeg, image/jpg, image/gif и image/png.

Тип контента Тип документа Расширение Работа с полезными подсказками
application/ogg Аудио OGG .ogx Нет
application/pdf PDF PDF Да (только для Google Сообщений в Индии)
audio/aac AAC; .aac Нет
audio/mp3 Звук в формате MP3 .mp3 Нет
audio/mpeg MPEG audio MPEG Нет
audio/mpg Аудио MPG .mp3 Нет
audio/mp4 Аудио MP4 MP4 Нет
audio/mp4-latm Аудио MP4-latm MP4 Нет
audio/3gpp Аудио 3GPP .3gp Нет
image/jpeg JPEG JPEG, JPG Да
Изображение (GIF) GIF GIF Да
Изображение (PNG) PNG PNG; Да
video/h263 Видео H.263 .h263 Да
video/m4v Видео M4V M4V Да
Видео (MP4) Видео MP4 MP4 Да
video/mpeg4 Видео MPEG-4 .mp4, .m4p Да
video/mpeg Видео MPEG MPEG Да
video/webm Видео в формате WebM .webm Да

Рекомендации

Агент отправляет подсказки (предлагаемые ответы и действия) в списках чипов или полезных подсказках.

готовые ответы;

Готовые ответы помогают пользователям вести диалог, предоставляя ответы, на которые ваш агент знает, как реагировать.

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

Пример

В приведенном ниже коде отправляется текст с двумя предлагаемыми ответами. Подробнее SuggestedReply…

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "reply": {
          "text": "Suggestion #1",
          "postbackData": "suggestion_1"
        }
      },
      {
        "reply": {
          "text": "Suggestion #2",
          "postbackData": "suggestion_2"
        }
      }
    ]
  }
}'

Node.js

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

let suggestions = [
   {
      reply: {
         'text': 'Suggestion #1',
         'postbackData': 'suggestion_1',
      },
   },
   {
      reply: {
         'text': 'Suggestion #2',
         'postbackData': 'suggestion_2',
      },
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Рекомендуемые действия

Рекомендуемые действия помогают пользователям вести беседы, используя встроенные функции устройств. Агент может предложить пользователям набрать номер, открыть местоположение на карте, поделиться местоположением, открыть URL или создать мероприятие в календаре.

Для каждого рекомендуемого действия можно указать резервный URL (не более 2048 символов). Этот URL открывается в новом окне браузера, если устройство пользователя не поддерживает рекомендуемое действие.

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

Подробнее о форматировании и вариантах значенийSuggestedAction…

Показ подсказок

Есть два способа показа подсказок:

  • Persistent Рекомендуемые действия или ответы, которые показываются внутри всплывающего сообщения и остаются неизменными на протяжении всего разговора.
  • Временные. Подсказки, которые показываются за пределами окна сообщения и исчезают, когда беседа продолжается.

Поддерживаемые форматы сообщений

  • Постоянные подсказки работают с отдельными текстовыми сообщениями и полезными подсказками.
  • Временные подсказки работают с отдельными текстовыми сообщениями, мультимедийными сообщениями и полезными подсказками.

Объединить предложения

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

  • Текстовые сообщения. По умолчанию подсказки временные. Чтобы они оставались в пузыре, их нужно настроить как постоянные.
  • Полезные подсказки. По умолчанию поддерживается до четырех постоянных подсказок. Затем вы можете добавить временные подсказки в виде списка чипов под карточкой.

Ограничения на подсказки

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

Тип предложения Ограничение Где показываются объекты
Стабильное До 4 Внутри всплывающего сообщения
Временные До 11 Вне всплывающей подсказки (в виде чипов)

Ограничение на количество символов

Максимальная длина каждого варианта – 25 символов.

Прозрачность URL в рекомендуемых действиях

Чтобы повысить доверие пользователей, URL, на который ведет ссылка, показывается во второй строке текста на кнопке рекомендуемого действия "Открыть URL". Это правило действует для отдельных текстовых сообщений, полезных подсказок и каруселей.

Клиенты, поддерживающие постоянные подсказки

  • Поддерживается: Google Сообщения (версия 20260225.00 или более поздняя).
  • Не поддерживается: Google Сообщения версий ранее 20260225.00, iOS и Samsung Messages.

Подсказки в системных уведомлениях

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

При разработке сообщений учитывайте следующее:

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

Набрать номер

Действие Dial позволяет пользователю набрать номер телефона, указанный агентом. Номер телефона может содержать только цифры (0-9), знак плюса (+), звездочку (*) и знак решетки (#). Международный формат E.164 (например, +14155555555) поддерживается, но не является обязательным. То есть можно использовать как +14155555555, так и 1011.

Пример

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

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Call",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/contact/",
          "dialAction": {
            "phoneNumber": "+15556667777"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define a dial suggested action
let suggestions = [
   {
      action: {
         text: 'Call',
         postbackData: 'postback_data_1234',
         dialAction: {
            phoneNumber: '+15556667777'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Как посмотреть местоположение

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

Пример

В следующем коде отправляется действие "Посмотреть местоположение". Варианты форматирования и значений описаны в статье 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);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Передача геоданных

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

Пример

Следующий код отправляет действие по передаче геоданных. Варианты форматирования и значений описаны в статье 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);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Открыть URL

Действие "Открыть URL" позволяет направлять пользователей на веб-страницу, указанную агентом. По умолчанию веб-страница открывается в браузере пользователя. Вы также можете настроить открытие веб-страницы в компоненте WebView. Подробнее о том, как открыть URL с помощью компонента WebView…

Только в Google Сообщениях

Показ URL. Чтобы повысить прозрачность сообщений A2P, Google Сообщения показывают URL в рекомендуемых действиях "Открыть URL". Это изменение касается рекомендуемых действий в стандартных полезных подсказках и каруселях полезных подсказок.

Полезная подсказка с предложением &quot;Перейти на сайт&quot; и URL под ним.
Видимый базовый URL

Показ значка приложения для веб-ссылок. Если у пользователя есть приложение по умолчанию, настроенное для веб-страницы, то вместо браузера или компонента WebView откроется это приложение, а на кнопке подсказки будет показан его значок. Чтобы значок приложения показывался в Google Сообщениях, укажите полный прямой URL. Если вы используете сокращенный URL, вместо него будет показан значок "Открыть URL" по умолчанию.

Значок приложения на кнопке подсказки.
Значок приложения на кнопке с подсказкой
Пример

В следующем примере кода отправляется действие по открытию URL. Подробнее о форматировании и значенияхOpenUrlAction…

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Open Google",
          "postbackData": "postback_data_1234",
          "openUrlAction": {
            "url": "https://www.google.com"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define an open URL suggested action
let suggestions = [
   {
      action: {
         text: 'Open Google',
         postbackData: 'postback_data_1234',
         openUrlAction: {
            url: 'https://www.google.com'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Как открыть URL с помощью компонента WebView

Действие "Открыть URL в WebView" загружает указанную веб-страницу в мессенджере с помощью механизма визуализации браузера по умолчанию. Это позволяет пользователю взаимодействовать с веб-страницей, не покидая чат RCS for Business. Если устройство пользователя не поддерживает компоненты WebView, веб-страница откроется в браузере. Инструкции по включению WebView приведены в статье OpenURLApplication.

У компонентов WebView есть три режима отображения. Варианты форматирования и значений приведены в WebviewViewMode.

  • Полный. Веб-страница занимает весь экран.
  • Половина экрана. Веб-страница занимает половину экрана.
  • Высокий. Веб-страница занимает три четверти экрана.
Пример

В примере ниже показано, как отправить действие "Открыть URL в WebView". Подробнее OpenURLAction…

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
 "contentMessage": {
   "text": "Hello, world!",
   "suggestions": [
     {
       "action": {
         "text": "Open Google",
         "postbackData": "postback_data_1234",
         "openUrlAction": {
           "url": "https://www.google.com",
           "application": "WEBVIEW",
           "webviewViewMode": "FULL",
           "description": "Accessibility description"
         }
       }
     }
   ]
 }
}'

Java

import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction;
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion;
import com.google.rbm.RbmApiHelper;
…
  
try {
  
   String URL = "https://www.google.com";
  
   // Create an instance of the RBM API helper
   RbmApiHelper rbmApiHelper = new RbmApiHelper();
  
   // Create suggestions for chip list
   List<Suggestion> suggestions = new ArrayList<Suggestion>();

   // Create suggestion to view webpage in full mode
   Suggestion viewInFullMode =  getUrlActionInWebview(URL, "FULL")
   suggestions.add(viewInFullMode);
  
   // create suggestion to view webpage in half mode
   Suggestion viewInHalfMode =  getUrlActionInWebview(URL, "HALF")
   suggestions.add(viewInHalfMode);
     
   // create suggestion to view webpage in tall mode
   Suggestion viewInTallMode =  getUrlActionInWebview(URL, "TALL")
   suggestions.add(viewInTallMode);
     
   // Send simple text message with the suggested action
   rbmApiHelper.sendTextMessage(
      "Hello, world!",
      "+12223334444",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

  /**
    * Creates a suggested action to open URL in webview.
    *
    * @return a suggestion object for an open URL in webview action .
    */
    private Suggestion getUrlActionInWebview(String url,
                                             String viewMode) {
      // create an open url action
      OpenUrlAction openUrlAction = new OpenUrlAction();
      openUrlAction.setUrl(url);
      openUrlAction.setApplication("WEBVIEW");
      openUrlAction.setWebviewViewMode(viewMode);
      openUrlAction.setDescription("Accessibility description");
     
      // attach the open url action to a suggested action
      SuggestedAction suggestedAction = new SuggestedAction();
      suggestedAction.setOpenUrlAction(openUrlAction);
      suggestedAction.setText('display_text');
      suggestedAction.setPostbackData('postback_data_123');
     
      // attach the action to a suggestion object
      Suggestion suggestion = new Suggestion();
      suggestion.setAction(suggestedAction);
     
      return suggestion;
    }

Как создать мероприятие в календаре

Действие "Создать мероприятие в календаре" открывает приложение календаря пользователя и начинает создавать новое мероприятие с указанной информацией.

Укажите название мероприятия из календаря. Максимальная длина – 100 символов. Описание мероприятия в календаре необязательно и может содержать не более 500 символов.

Пример

В следующем примере кода отправляется действие по созданию мероприятия в календаре. Подробнее CreateCalendarEventAction…

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d '{
  "contentMessage": {
    "text": "Hello, world!",
    "suggestions": [
      {
        "action": {
          "text": "Save to calendar",
          "postbackData": "postback_data_1234",
          "fallbackUrl": "https://www.google.com/calendar",
          "createCalendarEventAction": {
            "startTime": "2020-06-30T19:00:00Z",
            "endTime": "2020-06-30T20:00:00Z",
            "title": "My calendar event",
            "description": "Description of the calendar event"
          }
        }
      }
    ]
  }
}'

Node.js

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

// Define a create calendar event suggested action
let suggestions = [
   {
      action: {
         text: 'Save to calendar',
         postbackData: 'postback_data_1234',
         createCalendarEventAction: {
            startTime: '2020-06-30T19:00:00Z',
            endTime: '2020-06-30T20:00:00Z',
            title: 'My calendar event',
            description: 'Description of the calendar event',
         },
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '+12223334444',
   suggestions: suggestions,
};

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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
);
Этот код взят из примера агента RBM.

Список вариантов запросов

Агент отправляет списки вариантов запроса/вариантов действия вместе с сообщениями, чтобы направлять последующие действия пользователей. Список чипов показывается, только если связанное с ним сообщение находится внизу цепочки. Любые последующие сообщения в разговоре (от пользователя или агента) перезаписывают список чипов.

Чипы в списке – это готовые ответы и рекомендуемые действия.

В списке вариантов запроса может быть не более 11 чипов, а в каждом чипе – не более 25 символов.

Подробнее о форматировании и вариантах значенийAgentContentMessage…

Полезные подсказки

Полезные подсказки объединяют медиаконтент, текст и интерактивные предложения в одном сообщении. Они идеально подходят для представления связанной информации (например, товара с его изображением, названием и ценой) и подсказки пользователям четкого следующего шага, такого как предложение "Посмотреть подробности".

В полезной подсказке может быть следующее:

Все эти поля необязательны, но в полезной подсказке должно быть заполнено хотя бы одно из полей 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);
});
Этот код взят из примера агента RBM.

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();
}
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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");
Этот код взят из примера агента 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/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);
});
Этот код взят из примера агента RBM.

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();
        }
Этот код взят из примера агента RBM.

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')
Этот код взят из примера агента RBM.

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);
Этот код взят из примера агента RBM.