Os agentes do RBM se comunicam com os usuários enviando e recebendo mensagens. Para enviar mensagens aos usuários, seu agente envia solicitações de mensagens à API RCS Business Messaging. Uma única solicitação pode incluir texto, cards avançados, arquivos de mídia e PDF, além de respostas sugeridas e ações sugeridas.
A plataforma RBM retorna erros em determinadas situações para ajudar você a gerenciar a entrega de mensagens:
- Se você enviar uma mensagem para um usuário cujo dispositivo não seja compatível com o RCS ou não tenha o RCS ativado, a plataforma RBM vai retornar um erro 404 NOT_FOUND. Nesse caso, tente entrar em contato com o usuário usando os métodos de substituição definidos na sua infraestrutura.
- Se você enviar uma mensagem para um usuário do RCS em uma rede em que seu agente ainda não foi lançado ou em uma rede que não ativou o tráfego do RCS, a plataforma RBM vai retornar um erro 404 NOT_FOUND.
- Se você enviar uma mensagem com recursos que o dispositivo de um usuário não oferece suporte, a plataforma RBM vai retornar o erro 400 INVALID_ARGUMENT e não vai entregar sua mensagem.
Como parte da sua estratégia de mensagens multicanal, é melhor revogar mensagens que não são entregues após um período razoável e enviá-las por um canal diferente. Para revogar mensagens automaticamente em um horário predefinido, defina uma validade da mensagem.
O destinatário está off-line
A plataforma RBM ainda aceita uma mensagem para entrega se o destinatário estiver off-line. Você recebe uma resposta 200 OK, e a plataforma RBM retém a mensagem e tenta reenviar por 30 dias. Não é necessário pedir para o RBM enviar a mensagem de novo.
O RBM exclui as mensagens não entregues 30 dias após o envio.
Dependendo do caso de uso do seu agente, talvez seja necessário revogar uma mensagem não entregue antes desse tempo limite de 30 dias. A revogação pode impedir que usuários off-line recebam uma mensagem desatualizada quando voltarem a ficar on-line. Há várias maneiras de revogar uma mensagem:
- Envie um pedido de revogação para acionar o processo.
- Defina uma validade para a mensagem e revogue automaticamente a mensagem no momento adequado.
Definir uma data de validade para a mensagem
A mensagem do seu agente é sensível ao tempo? Por exemplo, os OTPs são válidos apenas por um período breve. As ofertas por tempo limitado expiram. Além disso, os lembretes de agendamento não são relevantes após a data do agendamento. Para manter as mensagens atualizadas e relevantes, defina uma data de expiração. Isso pode impedir que os usuários off-line recebam conteúdo desatualizado quando voltarem a ficar on-line. A expiração também é uma boa dica para invocar sua estratégia de mensagens de substituição para que os usuários recebam as informações necessárias a tempo.
Para definir uma expiração de mensagem, especifique um dos seguintes campos na mensagem do agente:
expireTime
: o horário exato em UTC em que a mensagem expira.ttl
(tempo de vida): o tempo antes da mensagem expirar.
Para opções de formatação e valores, consulte AgentMessage
.
Quando a mensagem expira, a plataforma RBM para de tentar entregar a mensagem, e ela é revogada automaticamente. No entanto, isso pode falhar em raras ocasiões. Por exemplo, a API pode acionar a revogação enquanto a plataforma RBM estava no processo de entrega da mensagem. Para confirmar se a mensagem expirada foi revogada, o RBM vai enviar uma notificação de evento para seu webhook.
O valor máximo para ttl
e expireTime
é 15 dias após o envio da mensagem.
Embora não haja um valor mínimo para ttl
e expireTime
, recomendamos aguardar pelo menos 10 segundos após o envio da mensagem para reduzir significativamente a chance de receber notificações de revogação e entrega.
Definir o tipo de tráfego de mensagens
A API RBM inclui um campo messageTrafficType
para categorizar mensagens.
Embora os casos de uso do agente ainda definam o comportamento do agente e quais regras de negócios se aplicam, o messageTrafficType
permite uma categorização mais detalhada do conteúdo da mensagem. Isso vai permitir que um único agente lide com vários casos de uso. No momento, não há impacto nos casos de uso de agentes ou nas regras de negócios atuais.
Esse campo é opcional, mas recomendamos que você o defina agora para não receber um erro quando ele se tornar obrigatório.
Para definir o tipo de tráfego de mensagens, atribua o
messageTrafficType
adequado a cada mensagem com base no conteúdo dela. A RBM é compatível com os seguintes tipos de tráfego.
Tipo de tráfego | Conteúdo da mensagem | Caso de uso do agente |
---|---|---|
AUTHENTICATION |
Para mensagens de autenticação. | OTP |
TRANSACTION |
Para mensagens sobre produtos ou serviços atuais de um usuário. Por exemplo: confirmações, recibos de pagamento ou detalhes da reserva. | Transacional ou de uso variado |
PROMOTION |
Para mensagens promocionais, como ofertas, descontos, anúncios ou outros conteúdos promocionais. | Promocional ou multiuso |
SERVICEREQUEST |
Para mensagens sobre serviços que o usuário solicitou explicitamente. | OTP, transacional, promocional ou multiuso |
ACKNOWLEDGEMENT |
Para mensagens usadas para confirmar uma ação do usuário, especificamente um pedido de cancelamento da inscrição. Isso confirma que o pedido do usuário foi recebido e está sendo processado. | OTP, transacional, promocional ou multiuso |
Se nenhum tipo de tráfego for definido, o sistema vai atribuir o tipo padrão para o caso de uso do agente.
Caso de uso do agente | Tipo de tráfego padrão |
---|---|
OTP | AUTHENTICATION |
Transacional | TRANSACTION |
Promocional | PROMOTION |
Multiúso | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Os agentes multiuso não têm um tipo de tráfego padrão. É necessário definir o tipo de tráfego explicitamente para cada mensagem com base no conteúdo dela. Se você não substituir o valor MESSAGE_TRAFFIC_TYPE_UNSPECIFIED
, um erro vai ocorrer.
Limites de tamanho da mensagem
O tamanho máximo de toda a stringificada AgentMessage é de 250 KB. A parte de texto da mensagem tem um limite de 3.072 caracteres.
O tamanho máximo de um arquivo que pode ser enviado pelo RBM é de 100 MB. Consulte Arquivos de mídia e PDF para mais informações.
Texto
As mensagens mais simples são feitas de texto. As mensagens de texto são mais adequadas para comunicar informações sem a necessidade de recursos visuais, interação complexa ou resposta.
Exemplo
O código a seguir envia uma mensagem de texto simples. Para opções de formatação e valor, consulte phones.agentMessages.create
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Conteúdo da mensagem básica: conversão de SMS
As operadoras introduziram modelos de faturamento para apoiar a migração de mensagens SMS para o RBM. Uma mensagem do RBM com até 160 caracteres UTF-8 é chamada de mensagem básica.
Ao criar uma solicitação para enviar uma mensagem básica, lembre-se de que os caracteres são contados como 1 byte (UTF-8). Se você enviar uma mensagem com caracteres especiais, como emojis ou um conjunto de caracteres multibyte, cada caractere vai contar como 2 a 4 caracteres UTF-8 ou mais.
Digite um texto na caixa para verificar o tamanho:
Conteúdo da mensagem básica e visualizações de link
Os clientes RCS podem implementar visualizações de link. Se uma mensagem do RBM somente texto incluir um URL de um site com tags openGraph, uma imagem de visualização poderá ser exibida, a impressão de um conteúdo mais rico.
O cliente RCS pode permitir que o usuário desative as prévias de link.
Senhas únicas para verificação de usuários
É possível usar o RBM para enviar senhas únicas (OTPs) para verificação automática do usuário com a API SMS Retriever. Não há uma API dedicada para ler senhas únicas que chegam pelo RBM.
Como funciona no Android
Para apps Android registrados na API SMS Retriever, a API aguarda uma mensagem RBM formatada corretamente. Essa mensagem precisa conter o OTP e um hash exclusivo que identifique seu app.
Quando uma mensagem do RBM é recebida no formato correto, a API SMS Retriever a processa como se fosse um OTP por SMS. Depois que o hash é correspondido ao seu app, a senha única é extraída e encaminhada para o app para verificação automática do usuário.
- Exemplo de mensagem de texto do RBM para verificação do usuário:
Your code is <OTP> <app hash>.
- Exemplo:
Your code is 123456 M8tue43FGT.
Para saber mais sobre o SMS Retriever e as APIs relacionadas, consulte a documentação do SMS Retriever. Para detalhes sobre a verificação automática de usuários em apps registrados na API SMS Retriever, consulte este diagrama de fluxo.
Como funciona no iOS
No iOS, o processamento de OTP integrado do sistema detecta e sugere automaticamente OTPs do RBM para preenchimento automático, assim como os OTPs por SMS. Não é necessária uma integração de API específica para que o app iOS leia o OTP.
Arquivos de mídia e PDF
Ao enviar uma mensagem com uma imagem, um vídeo, um áudio ou um arquivo PDF, seu agente precisa fornecer um URL acessível publicamente para o conteúdo ou fazer upload direto do arquivo. Para arquivos de mídia, também é possível especificar uma imagem em miniatura que permite aos usuários visualizar o conteúdo antes de clicar nele. Para arquivos de áudio, o widget de áudio padrão é usado como marcador de posição.
A plataforma RBM armazena arquivos em cache por 60 dias, e a API retorna um ID de arquivo que seu agente pode incluir em mensagens para os usuários. Após 60 dias, o RBM remove os arquivos do cache.
Ao especificar arquivos por URL, é recomendável definir
contentMessage.forceRefresh
como false
. Definir contentMessage.forceRefresh
como true
força o RBM a buscar novo conteúdo no URL especificado, mesmo que o conteúdo do URL esteja em cache, o que aumenta os tempos de entrega de mensagens para os usuários.
Confira as práticas recomendadas para recomendações e limites de tamanho de arquivo.
Exemplo de URL de arquivo
O código a seguir envia uma imagem. Para opções de formatação e valores, consulte
AgentContentMessage
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
Também é possível fazer upload da mídia antes de enviar em uma mensagem com
files.create
.
Exemplo de upload de arquivo
O código a seguir faz upload de um arquivo de vídeo e de miniatura e envia os dois
arquivos em uma mensagem. Para opções de formatação e valores, consulte
files.create
e 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" } } }'
Tipos de mídia compatíveis
O RBM é compatível com os seguintes tipos de mídia. Para miniaturas, apenas image/jpeg, image/jpg, image/gif e image/png são aceitos.
Tipo de mídia | Tipo de documento | Extensão | Funciona com Rich Cards |
---|---|---|---|
application/ogg | Áudio OGG | .ogx | Não |
application/pdf | Não | ||
audio/aac | Áudio AAC | .aac | Não |
audio/mp3 | Áudio MP3 | .mp3 | Não |
audio/mpeg | Áudio MPEG | .mpeg | Não |
audio/mpg | Áudio MPG | .mp3 | Não |
audio/mp4 | MP4 | .mp4 | Não |
audio/mp4-latm | Áudio MP4-latm | .mp4 | Não |
audio/3gpp | Áudio 3GPP | .3gp | Não |
image/jpeg | JPEG | .jpeg, .jpg | Sim |
image/gif | GIF | .gif | Sim |
image/png | PNG | .png | Sim |
video/h263 | Vídeo H263 | .h263 | Sim |
video/m4v | Vídeo M4V | .m4v | Sim |
video/mp4 | Vídeo MP4 | .mp4 | Sim |
video/mpeg4 | Vídeo MPEG-4 | .mp4, .m4p | Sim |
video/mpeg | Vídeo MPEG | .mpeg | Sim |
video/webm | Vídeo WEBM | .webm | Sim |
Sugestões
O agente envia sugestões (respostas e ações sugeridas) em listas de ícones de sugestão (máximo de 11 sugestões) ou em cards avançados (máximo de quatro sugestões).
Cada sugestão tem um máximo de 25 caracteres.
Respostas sugeridas
As respostas sugeridas orientam os usuários nas conversas, fornecendo respostas que seu agente sabe como reagir.
Quando um usuário toca em uma resposta sugerida, seu agente recebe um evento que contém o texto da resposta e os dados de postback. O payload tem um máximo de 2048 caracteres.
Exemplo
O código a seguir envia texto com duas respostas sugeridas. Para opções de formatação e valores, consulte SuggestedReply
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Ações sugeridas
As ações sugeridas orientam os usuários nas conversas usando a funcionalidade integrada dos dispositivos. Seu agente pode sugerir que os usuários façam uma ligação, abram um local em um mapa, compartilhem um local, abram um URL ou criem um evento na agenda.
Para cada ação sugerida, você pode fornecer um URL alternativo (máximo de 2.048 caracteres). Esse URL será aberto em uma nova janela do navegador se o dispositivo do usuário não for compatível com a ação sugerida.
Quando um usuário toca em uma ação sugerida, seu agente recebe um evento que contém os dados de postback da ação.
Para opções de formatação e valores, consulte
SuggestedAction
.
Digite o número de telefone
A ação de discagem orienta o usuário a discar um número de telefone especificado pelo seu agente.
Os números de telefone só podem incluir dígitos (0-9
), sinal de adição (+
), asterisco (*
) e cerquilha (#
). O formato internacional E.164 (por exemplo, +14155555555
) é aceito, mas não obrigatório. Ou seja, +14155555555
e 1011
são entradas válidas.
Exemplo
O código a seguir envia uma ação de discagem. Para opções de formatação e valores, consulte
DialAction
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Ver um local
A ação "Ver local" mostra um local no app de mapa padrão do usuário. Você pode especificar o local por latitude e longitude ou com uma consulta baseada na localização atual do usuário. Também é possível definir um rótulo personalizado para o alfinete que aparece no app de mapas.
Exemplo
O código a seguir envia uma ação de visualização de local. Para opções de formatação e valor, consulte ViewLocationAction
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Compartilhar um local
A ação "Compartilhar local" permite que o usuário compartilhe um local com seu agente. O usuário pode compartilhar o local atual ou um local selecionado manualmente no app Maps.
Exemplo
O código a seguir envia uma ação de compartilhamento de local. Para opções de formatação e valor, consulte ShareLocationAction
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Abrir um URL
A ação "Abrir URL" permite direcionar os usuários para uma página da Web especificada pelo seu agente. Por padrão, a página da Web é aberta no navegador do usuário. Se um usuário tiver um app padrão configurado para a página da Web, esse app será aberto. Nesse caso, o ícone no botão de ação sugerida será o do app.
A ação "Abrir URL" também é compatível com webviews integradas. Consulte Abrir URL com WebView.
Exemplo
O código a seguir envia uma ação de abrir URL. Para opções de formatação e valores,
consulte
OpenUrlAction
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Abrir um URL com webview
A ação "Abrir URL com visualização da Web" carrega a página da Web especificada no app de mensagens com o mecanismo de renderização do seu navegador padrão. Isso permite que o usuário interaja com a página da Web sem sair da conversa do RBM. Se o dispositivo do usuário não for compatível com webviews, a página da Web será aberta no navegador. Para ativar as webviews, consulte
OpenURLApplication
.
As webviews têm três modos de exibição. Para opções de formatação e valores, consulte
WebviewViewMode
.
- Completa:a página da Web ocupa a tela inteira.
- Metade:a página da Web ocupa metade da tela.
- Alta:a página da Web ocupa três quartos da tela.
Exemplo
O código a seguir envia uma ação "Abrir URL com webview". Para opções de formatação e valores, consulte 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; }
Criar um evento na agenda
A ação "Criar evento da agenda" abre o app de agenda do usuário e começa a criar um evento com as informações especificadas.
É necessário inserir um título para o evento da agenda. Ele tem no máximo 100 caracteres. A descrição do evento da agenda é opcional e tem um máximo de 500 caracteres.
Exemplo
O código a seguir envia uma ação para criar um evento da agenda. Para opções de formatação e valores, consulte CreateCalendarEventAction
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Lista de chips de sugestão de resposta
Seu agente envia listas de ícones de sugestão com mensagens para orientar as ações seguintes dos usuários. A lista de chips só aparece quando a mensagem associada está na parte de baixo da conversa. Todas as mensagens subsequentes na conversa (de um usuário ou do seu agente) substituem a lista de chips.
Os ícones na lista são respostas sugeridas e ações sugeridas.
As listas de chips contêm no máximo 11 chips de sugestão, e cada rótulo pode ter no máximo 25 caracteres.
Para opções de formatação e valores, consulte
AgentContentMessage
.
Rich Cards
Quando você precisar enviar um conjunto de informações, mídia ou sugestões relacionadas, envie um Rich Card. Com os cards avançados, seu agente pode enviar várias unidades de informação em uma única mensagem.
Os rich cards podem conter os seguintes itens:
- Uma imagem ou um vídeo
- Texto do título
- Texto da descrição
- Respostas e ações sugeridas (máximo de quatro)
Um rich card pode conter todos os itens listados, mas precisa ter pelo menos uma imagem, um vídeo ou um título para ser válido. Um card avançado pode conter no máximo quatro ações sugeridas e respostas sugeridas.
Seu agente pode enviar vários rich cards juntos em um carrossel de rich cards.
O tamanho máximo de um payload de card avançado é de 250 KB. Confira as práticas recomendadas para recomendações e limites de tamanho de arquivos de mídia.
Você pode encontrar as especificações dos Rich Cards em Rich Cards.
Altura do card
Os cards se expandem verticalmente para se ajustar ao conteúdo. Os cards avançados têm uma altura mínima de 112 DP e uma altura máxima de 344 DP. Se o conteúdo de um card não for grande o suficiente para preencher a altura mínima, ele será expandido e preencherá a altura extra com espaço em branco.
A mídia em rich cards precisa se encaixar em uma destas três alturas:
- Curta: 112 DP
- Média: 168 DP
- Grande: 264 DP
Se a mídia não se ajustar às dimensões do card devido à altura selecionada, a prévia será escolhida com zoom e corte.
Exemplo
O código a seguir envia um Rich Card com uma imagem e respostas
sugeridas. Para opções de formatação e valores, consulte
RichCard
.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
Carrosséis de Rich Cards
Quando você precisar apresentar várias opções para um usuário escolher, use um carrossel de card avançado. Os carrosséis juntam vários cartões avançados, permitindo que os usuários comparem itens e reajam a cada um individualmente.
Os carrosséis podem conter de dois a dez rich cards. Os rich cards em carrosséis precisam obedecer aos requisitos gerais de conteúdo e altura. Confira as especificações do carrossel em Cards avançados.
O tamanho máximo de um payload de carrossel de card avançado é de 250 KB. Confira as práticas recomendadas para recomendações e limites de tamanho de arquivos de mídia.
Truncamento
Assim como os cartões avançados, muitos fatores (como resolução da tela, densidade de pixels e preferências do usuário) afetam a forma como os cartões aparecem para os usuários finais. Em um carrossel, a altura dos primeiros cards define a altura de todos os cards, e a altura do card afeta o truncamento do título, da descrição e da sugestão.
Se um dispositivo não puder mostrar todos os elementos de um card devido a restrições de exibição ou altura do card, o RBM vai truncar o card até que ele possa ser exibido no dispositivo, usando a seguinte lógica:
- Reduza a descrição para uma linha.
- Reduza o título para uma linha.
- Omita as sugestões que não cabem no card, começando pelo final da lista definida.
- Omitir a descrição.
- Omitir o título.
Para evitar o truncamento, mantenha os títulos e as descrições o mais curtos possível. Para mídia alta, use um título e uma descrição ou uma sugestão. Para mídia média, use até duas sugestões. Para mídias curtas, use até três sugestões. Para incluir quatro sugestões, não inclua mídia no card.
Mantenha os cards aproximadamente equivalentes em termos de tamanho e comprimento do conteúdo e, se necessário, coloque os cards maiores na frente do carrossel para evitar o truncamento nos cards seguintes.
Exemplo
O código a seguir envia um carrossel de Rich Cards. Para opções de formatação e valores,
consulte
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); });
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/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(); }
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/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')
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/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);