Fichas de sugestões do RCS

As sugestões do RCS permitem que você utilize respostas e ações sugeridas em suas mensagens RCS. Elas podem ser incluídas em vários tipos de mensagens, como Cartões, Carrosséis e mensagens de texto, e são definidas na carga JSON dessas mensagens como uma matriz de objetos de sugestão.

Esses objetos de sugestão podem ser respostas sugeridas, ações sugeridas ou uma combinação de ambas. A estrutura exata dos objetos varia de acordo com o tipo de sugestão.

Sugestões

As sugestões são elementos interativos da interface do usuário exibidos como botões ou “chips” nos aplicativos de mensagens compatíveis com RCS. Cada sugestão representa uma resposta rápida ou uma ação na qual o usuário pode tocar. Esses chips aparecem abaixo do corpo principal da mensagem e desaparecem assim que o usuário interage com eles ou quando uma mensagem mais recente é recebida.

Existem dois tipos de sugestões:

Respostas sugeridas: Respostas predefinidas do usuário que acionam uma mensagem recebida do tipo reply para a URL definida para o seu webhook de mensagens recebidas.
Ações sugeridas: Botões que executam uma ação, por exemplo, abrir uma URL ou ligar para um número, e acionam uma mensagem recebida do tipo button para a URL definida para o seu webhook de mensagens recebidas.

Observação: também é possível incluir um array de sugestões em uma mensagem de cartão avançado. Como um carrossel é uma coleção de cartões, cada cartão do carrossel também pode conter seu próprio array de sugestões. Consulte Cartões enriquecidos e carrosséis para mais informações.

Respostas sugeridas

Utilize as respostas sugeridas quando esperar uma resposta que possa ser processada programaticamente. Cada resposta inclui:

text: Exibido no chip.
postback_data: Um identificador retornado na entrada reply carga útil da mensagem como o id parâmetro.

Aqui está um exemplo de uma mensagem RCS do tipo text com duas sugestões de respostas:

{
   "to": "447700900000",
   "from": "Vonage",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello, world!",
   "suggestions": [
       {
           "type": "reply",
           "text": "Suggestion #1",
           "postback_data": "suggestion_1"
       },
       {
           "type": "reply",
           "text": "Suggestion #2",
           "postback_data": "suggestion_2"
       }
   ]
}

Se o destinatário tocasse em uma das sugestões, isso acionaria uma mensagem recebida do tipo reply; aqui, o valor de id variaria dependendo do chip de sugestão que o usuário selecionasse:

{
  "to": "Vonage",
  "from": "447900000000",
  "channel": "rcs",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2024-02-08T10:12:44Z",
  "message_type": "reply",
  "reply": {
    "id": "suggestion_1",
    "title": "Suggestion #1"
  }
}

Ações sugeridas

As ações sugeridas executam uma função e retornam dados estruturados por meio de uma mensagem de botão. Todas as ações exigem:

type: Define o tipo de ação
text: Nome do chip (máx. 25 caracteres)
postback_data: Um identificador retornado na entrada button carga útil da mensagem como o payload parâmetro.

A maioria dos tipos de ação também requer um ou mais parâmetros adicionais para suportar a ação específica. Alguns tipos também possuem outros parâmetros opcionais. Esses parâmetros são detalhados nas descrições dos tipos específicos a seguir:

Abrir um URL
Abrir uma URL no Webview
Disque um número
Ver um local
Compartilhar uma localização
Criar um evento no calendário

Abrir um URL

Este objeto de ação possui um type de open_url e possui as seguintes propriedades adicionais:

url: A URL a ser aberta. Observação: os únicos esquemas permitidos são http:// e https://; outros tipos de esquemas, como tel, mailto, etc. não são permitidos.
description: Uma descrição opcional da URL para fins de acessibilidade.
url (String): esta é a URL a ser aberta.

Se esse botão de ação for tocado, o dispositivo do destinatário abre a URL especificada no navegador padrão do dispositivo ou em um aplicativo instalado (caso haja um aplicativo registrado como manipulador para o domínio da URL).

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description"
   }
  ]
 }

Abrir uma URL no Webview

Este objeto de ação possui um type de open_url_in_webview e possui as seguintes propriedades adicionais:

url: A URL a ser aberta. Observação: os únicos esquemas permitidos são http:// e https://; outros tipos de esquemas, como tel, mailto, etc. não são permitidos.
description: Uma descrição opcional da URL para fins de acessibilidade.
view_mode: O modo de exibição da URL na janela do webview. Pode ser FULL, TALL, ou HALF.

Se esse botão de ação for tocado, o dispositivo do destinatário abre a URL especificada dentro do próprio aplicativo de mensagens, sendo que o tamanho da página da web na interface do aplicativo é determinado pelo valor do view_mode parâmetro.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url_in_webview",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description",
     "view_mode": "FULL"
   }
  ]
 }

Discar um número

Este objeto de ação possui um type de dial e possui as seguintes propriedades adicionais:

phone_number (String): este é o número de telefone a ser discado. Ele deve estar no formato E.164, incluir o código do país e ser precedido por um +, por exemplo +447900000000
fallback_url (String): esta é uma URL a ser aberta caso não seja possível iniciar a ação de discagem.

Se este botão de ação for clicado, o destinatário será direcionado para ligar para o número de telefone indicado.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "dial",
     "text": "Call",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/contact/",
     "phone_number": "+15556667777"
   }
 ]
}

Ver um local

Este objeto de ação possui um type de view_location e possui as seguintes propriedades adicionais:

latitude (String): A latitude em graus. Deve estar no intervalo [-90,0; +90,0]
longitude (String): A longitude em graus. Deve estar no intervalo [-180,0; +180,0].
pin_label (String): uma propriedade opcional que adiciona um rótulo ao marcador exibido no mapa.
fallback_url (String): esta é uma URL a ser aberta caso não seja possível iniciar a ação de localização da visualização.

Se esse chip de ação for tocado, o dispositivo do destinatário exibirá o local especificado no aplicativo de mapas padrão do dispositivo.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "view_location",
     "text": "View map",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
     "latitude": "37.4220188",
     "longitude": "-122.0844786",
     "pin_label": "Googleplex"
   }
 ]
}

Compartilhar uma localização

Este objeto de ação possui um type de share_location e possui apenas três parâmetros obrigatórios: type, text, e postback_data.

Se esse botão de ação for tocado, o dispositivo do destinatário abrirá o seletor de localização padrão para que ele possa escolher um local para enviar de volta.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "share_location",
     "text": "Share your location",
     "postback_data": "postback_data_1234"
   }
 ]
}

Criar um evento no calendário

Este objeto de ação possui um type de create_calendar_event e possui as seguintes propriedades adicionais:

start_time (String no formato de carimbo de data/hora): define a hora de início do evento. Um carimbo de data/hora em RFC3339 Formato UTC “Zulu”, por exemplo 2024-06-28T19:00:00Z
end_time (String no formato de carimbo de data/hora): define a hora de término do evento. Um carimbo de data/hora no formato RFC3339 Formato UTC “Zulu”, por exemplo 2024-06-28T19:00:00Z.
title (String): define o título do evento.
description (String): define a descrição do evento.
fallback_url (String): esta é uma URL a ser aberta caso não seja possível iniciar a ação de criação de evento no calendário.

Se esse chip de ação for tocado, o dispositivo do destinatário abre o aplicativo de calendário padrão e começa a criar um novo evento no calendário com os dados definidos no objeto de ação.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
         {
     "type": "create_calendar_event",
     "text": "Save to calendar",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/calendar",
     "start_time": "2020-06-30T19:00:00Z",
     "end_time": "2020-06-30T20:00:00Z",
     "title": "My calendar event",
     "description": "Description of the calendar event"
   }
 ]
}

Trechos de código

A seguir, apresentamos uma lista de trechos de código para o envio de solicitações de mensagens de diferentes tipos: