Mensagem RCS

Esta documentação oferece uma visão geral dos tipos de mensagens e ações suportados pela nossa API de mensagens. Cada tipo é apresentado com uma descrição e um exemplo em JSON para facilitar a integração e o uso.

Esta descrição abrangente e os exemplos em JSON oferecem uma visão profunda das possibilidades da API RCS. Usando esses diferentes tipos de mensagens e ações, os desenvolvedores podem criar uma experiência de usuário rica e interativa que melhora a comunicação entre empresas e clientes.

Estrutura da Mensagem

Basicamente, cada mensagem pode consistir em exatamente um tipo de conteúdo (text, carousel, richcard ou file) e opcionalmente conter respostas sugeridas.

Propriedades

Name
suggestions
Type
array
Optional
Optional
Description
Uma lista de sugestões de resposta e sugestões de ação que são exibidas como uma lista abaixo da última mensagem do agente. Máximo de 11 sugestões.
Name
text
Type
string
Union
Description
Uma mensagem de texto simples. Faz sentido aqui apenas em conjunto com respostas sugeridas, pois caso contrário, você pode simplesmente enviar o texto diretamente como uma string simples para nossa API.
carousel
objectUnion
Um carrossel é uma coleção de vários Richcards.
Name
richcard
Type
object
Union
Description
Uma Richcard é uma mensagem enriquecida com Rich Content. Ela pode conter texto, vídeos, uma localização e muito mais. Também são possíveis botões com os quais o destinatário pode interagir diretamente, por exemplo, para confirmar uma reserva ou fazer uma compra.
Name
file
Type
object
Union
Description
Envie um arquivo, como por exemplo uma imagem, um arquivo de áudio ou um documento, para o destinatário.

{
    "suggestions": [
    // ...
    ],

    // Só podem ser especificadas as seguintes propriedades
    // Ou...
    "text": "Ihr Code lautet 1234",

    // ...ou...
    "carousel": {
        "width": "SMALL",
        "richcards": [
            {
                // richcard Objekt...
            },
            // ...
        ]
    },

    // ...ou...
    "richcard": {
        "orientation": "horizontal",
        "thumbnailImageAlignment": "right",
        // ...
    },

    // ...ou...
    "file": {
        "fileUrl": "https://acme.inc/images/image.png",
        "thumbnailUrl": "https://acme.inc/images/thumbnail.png",
        "forceRefresh": false
    }
}

Richcard

Name
title
Type
string
Description
Título da Richcard
Name
description
Type
string
Description
Descrição da Richcard
Name
orientation
Type
enum
Optional
Optional
Description
Esta propriedade deve ser especificada apenas ao enviar Richcards individuais. Pode conter horizontal ou vertical.
Name
thumbnailImageAlignment
Type
enum
Optional
Optional
Description
Esta propriedade deve ser especificada apenas ao enviar Richcards individuais no layout horizontal. Pode conter left ou right.
Name
file
Type
object
Optional
Optional
Description
Um objeto de arquivo.
Name
suggestions
Type
array
Optional
Optional
Description
Uma lista de sugestões de resposta e sugestões de ação que serão exibidas no respectivo cartão. Máximo de 4 sugestões.

{
    "title": "Titel der Richcard",
    "description": "Beschreibung der Richcard",
    "orientation": "horizontal",
    "thumbnailImageAlignment": "left",
    "file": {
        // objeto de ficheiro
        // ...
    },
    "suggestions": [
        // Lista de respostas sugeridas
    ]
}

Enviar arquivo

Nossa API armazena automaticamente arquivos e miniaturas em cache. Se você quiser que nossa API recarregue a imagem, basta alterá-la ligeiramente. Você pode adicionar um parâmetro de consulta como ?timestamp=12345 ou uma hashtag.

Os tipos MIME permitidos são: image/jpeg, image/jpg, image/gif, image/png, video/h263, video/m4v, video/mp4, video/mpeg, video/mpeg4, video/webm

Se o arquivo não fizer parte de um Richcard, mas for especificado no elemento raiz, o tipo MIME application/pdf também é permitido.

Propriedades

Name
height
Type
enum
Optional
Optional
Description
Deve ser especificado apenas ao usar em um Richcard no layout vertical. Pode ser short, medium ou tall.
Name
fileUrl
Type
string
Union
Description
URL pública acessível do arquivo. A plataforma RBM determina o tipo MIME do arquivo a partir do cabeçalho HTTP Content-Type quando o arquivo é recuperado. Tamanho máximo de arquivo recomendado de 100 MB.
Name
fileContents
Type
string
Union
Description
Conteúdo do arquivo codificado em base64.
Name
thumbnailUrl
Type
string
Optional
Optional
Union
Description
Apenas para arquivos de imagem e vídeo. URL da miniatura. Tamanho máximo de 100 kB.
Name
thumbnailContents
Type
string
Optional
Optional
Union
Description
Apenas para arquivos de imagem e vídeo. Conteúdo da miniatura codificado em base64. Tamanho máximo de 100 kB.

Se você não fornecer uma miniatura para a visualização, uma miniatura de espaço reservado vazia será exibida até que o dispositivo do usuário baixe o arquivo. Dependendo das configurações do usuário, o arquivo pode não ser baixado automaticamente, e o usuário pode precisar tocar em um botão para baixar.

{
    "height": "medium",
    "fileUrl": "https://example.com/bild.jpg",
    "thumbnailUrl": "https://example.com/thumbnail.jpg"
}

Respostas e Ações

As sugestões são exibidas apenas quando a mensagem do agente correspondente é a mensagem mais recente dentro da conversa (incluindo mensagens de agentes e de usuários). O usuário pode tocar em uma resposta sugerida para enviar a resposta de texto de volta ao agente ou em uma ação sugerida para iniciar uma ação própria no dispositivo.

Propriedades

Name
type
Type
enum
Description
O tipo de resposta ou ação sugerida. Pode ter um dos seguintes valores:
- reply
- dial
- viewLocation
- createCalendarEvent
- openUrl
- shareLocation
Name
text
Type
string
Description
Texto a ser exibido no botão.
Name
postbackData
Type
string
Description
Dados retornados quando uma ação é acionada.
Name
phoneNumber
Type
string
Optional
Optional
Description
Apenas para o tipo dial. O número de telefone a ser chamado.
location
objectOptional
Apenas para viewLocation. Inclui os dados da localização.
- Name
  latitude
  Type
  string
  Description
  latitude
- Name
  longitude
  Type
  string
  Description
  longitude
- Name
  label
  Type
  string
  Description
  label
calendarEvent
objectOptional
Apenas para createCalendarEvent. Inclui os dados do evento.
- Name
  startTime
  Type
  timestamp
  Description
  O horário de início do evento. Formatos comuns como 19.06.2024 17:23 ou 2024-06-19 17:23 são aceitos.
- Name
  endTime
  Type
  timestamp
  Description
  O horário de término do evento. Formatos comuns como 19.06.2024 17:23 ou 2024-06-19 17:23 são aceitos.
- Name
  title
  Type
  string
  Description
  O título do evento no calendário.
- Name
  description
  Type
  string
  Description
  A descrição do evento no calendário.
Name
url
Type
string
Optional
Optional
Description
Apenas para o tipo openUrl. A URL que deve ser aberta.
Name
webviewMode
Type
string
Optional
Optional
Description
Apenas para o tipo openUrl. Pode ser tall, half ou full. full abre a URL na visualização da web em tela cheia, half ocupa metade da tela e tall ocupa dois quartos da tela.

A propriedade webviewMode atualmente não é suportada por todos os dispositivos. Se não for suportada, a URL será aberta em um navegador externo.

[
    // Resposta sugerida
    {
        "type": "reply",
        "text": "Sim",
        "postbackData": "clicked_yes"
    },

    // Chamada sugerida
    {
        "type": "dial",
        "text": "Ligar",
        "postbackData": "clicked_call_button",
        "phoneNumber": "49176123456789"
    },

    // Ver localização
    {
        "type": "viewLocation",
        "text": "Mostrar localização",
        "postbackData": "clicked_view_location_button",
        "location": {
            "latitude": 54.3233,
            "longitude": 10.1228,
            "label": "Kiel"
        }
    },

    // Criar evento no calendário
    {
        "type": "createCalendarEvent",
        "text": "Marcar uma consulta",
        "postbackData": "clicked_call_button",
        "calendarEvent": {
            "startTime": "",
            "endTime": "",
            "title": "Um compromisso importante",
            "description": "Aguardamos a sua visita."
        }
    },

    // Abrir URL
    {
        "type": "openUrl",
        "text": "Abrir",
        "postbackData": "clicked_url_button",
        "url": "https://www.example.com"
    },

    // Partilhar localização
    {
        "type": "shareLocation",
        "text": "Partilhar localização",
        "postbackData": "clicked_share_location_button"
    }
]

Exemplos

Mensagem de texto com respostas sugeridas

Envia uma mensagem de texto simples com três respostas sugeridas para o destinatário. Mensagens de texto são os tipos de mensagem mais básicos, que podem ser usados para comunicação direta de informações, perguntas ou instruções. Você receberá no webhook o valor de postbackData da resposta escolhida.

Tecnicamente, duas mensagens RCS são enviadas aqui e cobradas de acordo.

{
  "text": "Olá, gostaria de clicar num botão?",
  "suggestions": [
    {
      "type": "reply",
      "text": "Sim",
      "postbackData": "clicked_yes"
    },
    {
      "type": "reply",
      "text": "Não",
      "postbackData": "clicked_no"
    },
    {
      "type": "reply",
      "text": "Não sei",
      "postbackData": "clicked_dont_know"
    }
  ]
}

Ver pré-visualização RCS

Richcard simples com uma imagem

Este exemplo envia uma imagem com a ação sugerida de visualizar a imagem no navegador. Por favor, note que as suggestions aqui estão na Richcard em vez de no nível principal. Se estivessem no nível principal, a mensagem RCS contaria como duas mensagens e seria mais cara.

{
  "richcard": {
    "title": "Cão",
    "description": "Aqui está a foto de um cão.",
    "orientation": "vertical",
    "file": {
      "height": "tall",
      "fileUrl": "https://picsum.photos/id/237/200/300",
      "thumbnailUrl": "https://picsum.photos/id/237/50"
    },
    "suggestions": [
      {
        "type": "openUrl",
        "text": "Mostrar imagem",
        "postbackData": "clicked_url",
        "url": "https://picsum.photos/id/237/800"
      }
    ]
  }
}

Ver pré-visualização RCS

Um carrossel vertical

Este exemplo mostra um carrossel de três cartões individuais e estreitos no layout horizontal, cada um com alturas diferentes.

Cada um dos três cartões tem uma ação sugerida. Por razões de espaço, no primeiro cartão o texto da resposta sugerida não é exibido completamente e no último cartão a ação sugerida não é exibida.

{
    "carousel":
    {
        "width": "SMALL",
        "richcards": [
            {
                "title": "Cão",
                "description": "Foto curta de um cão.",
                "file":
                {
                    "height": "short",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Sim, isto é um cão.",
                      "postbackData": "yes_this_is_a_dog_clicked"
                  }
                ]
            },
             {
                "title": "Cão",
                "description": "Imagem média de um cão.",
                "file":
                {
                    "height": "medium",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Doce",
                      "postbackData": "sweet_dog_clicked"
                  }
                ]
            },
            {
                "title": "Cão",
                "description": "Imagem alta de um cão.",
                "file":
                {
                    "height": "tall",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Sim",
                      "postbackData": "yes_clicked"
                  }
                ]
            }
        ]
    }
}

Ver pré-visualização RCS