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
        width
        Type
        enum
        Description

        Tamanho do carrossel. Pode ser SMALL ou MEDIUM.

      • Name
        richcards
        Type
        enum
        Description

        Uma lista de 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.

  • Name
    contentDescription
    Type
    string
    Optional
    Optional
    Description

    Apenas para arquivos dentro de uma richcard ou de um carrossel. Texto alternativo da imagem ou do vídeo, lido em voz alta por leitores de tela como o TalkBack. Texto simples, no máximo 200 caracteres. Descreva o conteúdo de forma objetiva e evite URLs. Não é suportado para um arquivo no elemento raiz.

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",
    "contentDescription": "Foto de um filhote de labrador preto sobre um piso de madeira"
}

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.

[
    // 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.

Um carrossel vertical
{
  "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.

Um carrossel vertical
{
  "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",
      "contentDescription": "Foto de um filhote de labrador preto sobre um piso de madeira"
    },
    "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.

Um carrossel vertical
{
    "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
Última atualização: Há 2 semanas