Como enviar carrosséis de cartões avançados (RCS) com o Node.js

Introdução

Serviços de Comunicação Avançada (RCS) oferecem as ferramentas necessárias para criar experiências de marca modernas e interativas diretamente no aplicativo de mensagens padrão do usuário. Entre seus recursos mais poderosos está o carrossel de cartões avançados: um conjunto de cartões com rolagem horizontal que pode incluir Videos, imagens, texto e ações acionáveis por toque.

Neste tutorial, você aprenderá a enviar um carrossel RCS usando o Node.js e a Messages API da Vonage. Você combinará cartões de vídeo e imagem com ações para aumentar o engajamento.

>> Resumo: Veja o código completo em funcionamento no GitHub

Caso de uso: Anúncio de loja pop-up de moda

Digamos que sua marca esteja lançando uma loja pop-up de moda por tempo limitado. Você quer gerar interesse e destacar os principais itens. Com um carrossel RCS, você pode reunir tudo isso em uma única mensagem clara e interativa.

Seu carrossel do RCS incluirá mídias e ações sugeridas:

1. Cartão 1: Video de lançamento do evento

   • Video trailer da loja pop-up

   • 2 ações: “Reserve a data” e “Veja o local”

2. Cartão 2: Imagem de camisetas:

   • Uma imagem da camiseta em destaque

   • ação: “Ver todas as camisetas”

3. Cartão 3: Imagem de chapéus:

   • Uma foto da sua coleção de chapéus

   • ação: “Ver todos os chapéus”

O que é um carrossel RCS?

Um carrossel RCS é um conjunto de cartões ricos que podem ser percorridos com um deslize, cada um com:

• Um título (máximo de 200 caracteres)

• Uma descrição (máximo de 2.000 caracteres)

• Mídia: imagem ou Video

• Até quatro sugestões de respostas ou ações

Os cartões são exibidos na horizontal, permitindo que os usuários os percam com o dedo.

Illustration of an RCS carousel message in the Android Messages app, annotated to show benefits like trusted branding, verified sender ID, richer media cards, time-saving action buttons, and quick-reply suggestions.

Observações importantes:

• Todos os cartões em um carrossel devem usar o mesmo tipo de sugestão.

• Os arquivos de mídia devem estar disponíveis ao público e ter menos de 100 MB.

• Você pode incluir de 2 a 10 cartões.

Pré-requisitos

Antes de começar, você vai precisar de:

• Node.js instalado no seu computador.

• O ngrok está instalado para expor seu servidor local à internet.

• Um account da API da Vonage.

• Um agente registrado do RCS Business Messaging (RBM); consulte a seção sobre contas gerenciadas abaixo.

• Um celular com recursos de RCS para testes.

Como entrar em contato com o seu gerente de account da Vonage

Para enviar e receber mensagens com recursos RCS no seu aplicativo da Vonage, você precisará ter um agente Rich Business Messaging (RBM) registrado e um telefone com recursos RCS.

Atualmente, o serviço de mensagens RCS via Vonage está disponível apenas para contas gerenciadas. Você precisará entrar em contato com seu gerente de conta para solicitar a ativação do Modo Desenvolvedor para o seu agente RBM. O Modo Desenvolvedor permite que você teste o envio de mensagens RCS para números incluídos na lista de permissões antes de concluir o processo de verificação do agente e iniciar a operação em produção.

Por favor, entre em contato com nossa equipe de vendas caso você não tenha um account gerenciado. 

>> Entenda a diferença entre RCS e RBM.

Como configurar seu projeto Node.js

Este guia pressupõe que você esteja familiarizado com os conceitos básicos de JavaScript e Node.js. 

Inicializar o projeto

Crie um novo diretório e inicialize um projeto Node.js:

mkdir rcs-carousel-node
cd rcs-carousel-node
npm init -y

Instalar os pacotes NPM necessários

Instale os pacotes necessários do Node com Node Package Manager (NPM):

npm install express dotenv @vonage/server-sdk

• express: Cria o servidor web

• dotenv: Carrega suas variáveis de ambiente

• @vonage/server-sdk: Envia mensagens por meio da Messages API do Vonage

Crie os arquivos do seu projeto

Crie o arquivo principal do aplicativo e o arquivo de configuração do ambiente:

touch index.js .env

Como configurar seu ambiente

No arquivo arquivo .env , adicione suas credenciais e configuração da Vonage:

VONAGE_APPLICATION_ID=your_application_id
VONAGE_API_SIGNATURE_SECRET=your_api_secret
VONAGE_PRIVATE_KEY=./private.key
RCS_SENDER_ID=your_rbm_agent_id
PORT=3000

• VONAGE_APPLICATION_ID: Seu ID de aplicativo da Vonage.

• VONAGE_API_SIGNATURE_SECRET= Sua chave secreta da API da Vonage

• VONAGE_PRIVATE_KEY: O arquivo da chave privada do seu aplicativo Vonage.

• RCS_SENDER_ID: Seu RBM SenderID (o nome da marca). O SenderID exige uma formatação específica, como, por exemplo, não conter espaços. Consulte seu gerente de Account caso tenha dúvidas.

• PORTA: Número da porta do servidor Express.

Você obterá seu ID do aplicativo Vonage e o arquivo private.key a seguir, na seção seção “Como criar e configurar o aplicativo Vonage” . Encontre sua chave secreta da API na página inicial do painel do desenvolvedor.

Como enviar um carrossel RCS

Agora que seu ambiente está configurado, vamos escrever o código que realmente envia seu carrossel de cartões rich cards do RCS.

Nesta etapa, você criará um servidor Express que envia uma mensagem RCS personalizada usando a Messages API do Vonage. O carrossel conterá três cartões de produto que podem ser deslizados, cada um com mídia (vídeo ou imagem), um título e uma descrição, além de botões interativos nos quais seus usuários podem tocar.

Carregar dependências e inicializar o cliente Vonage

Vamos começar importando os pacotes necessários, carregando suas variáveis de ambiente e inicializando o cliente Vonage. Adicione o código a seguir ao seu arquivo arquivo index.js para dar início ao processo:

const express = require('express');
const fs = require('fs');
const dotenv = require('dotenv');
const { Vonage } = require('@vonage/server-sdk');
const { verifySignature } = require('@vonage/jwt');

dotenv.config();

const app = express();
app.use(express.json());

const PORT = process.env.PORT || 3000;

const VONAGE_API_SIGNATURE_SECRET = process.env.VONAGE_API_SIGNATURE_SECRET;

const privateKey = fs.readFileSync(process.env.VONAGE_PRIVATE_KEY);

const vonage = new Vonage({
  applicationId: process.env.VONAGE_APPLICATION_ID,
  privateKey: privateKey
});

Definir um endpoint Express para enviar um carrossel RCS

Vale a pena conhecer alguns detalhes pequenos, mas importantes, antes de enviarmos o carrossel. Todos os arquivos de mídia devem estar acessíveis publicamente via HTTPS, de preferência hospedados em uma CDN ou em um serviço de armazenamento em nuvem. Neste exemplo, estamos usando recursos hospedados no GitHub por uma questão de simplicidade, mas, em ambiente de produção, é recomendável utilizar uma hospedagem de mídia mais rápida e confiável. 

>> Mantenha os arquivos de mídia individuais com menos de 100 MB para atender às restrições do RCS.

Cada cartão inclui um ou mais botões de ação que utilizam postbackData, openUrlActionou createCalendarEventAction. O postbackData é uma string curta (máximo de 50 caracteres) que seu servidor pode usar para rastrear o que os usuários selecionam. Você também pode criar links diretos para mapas ou eventos de calendário pré-preenchidos para aumentar a interatividade, fazendo com que o carrossel pareça mais um mini-aplicativo do que apenas uma mensagem.

app.post('/send-rcs-carousel', async (req, res) => {
  const toNumber = req.body.to;

  const message = {
    to: toNumber,
    from: process.env.RCS_SENDER_ID,
    channel: 'rcs',
    message_type: 'custom',
    custom: {
      contentMessage: {
        richCard: {
          carouselCard: {
            cardWidth: "MEDIUM",
            cardContents: [
              {
                title: "Fashion Popup Launch 🎉",
                description: "Join us this weekend for limited drops & exclusive looks.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-video.gif",
                    thumbnailUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-thumbnail.png",
                    forceRefresh: true
                  }
                },
                suggestions: [
                  {
                    "action": {
                      "text": "Save the Date",
                      "postbackData": "save_event",
                      "fallbackUrl": "https://www.google.com/calendar",
                      "createCalendarEventAction": {
                        "startTime": "2024-06-28T19:00:00Z",
                        "endTime": "2024-06-28T20:00:00Z",
                        "title": "Fashion Popup Launch",
                        "description": "Join us this weekend for limited drops & exclusive looks."
                      }
                    }
                  },
                  {
                    action: {
                      text: "See Location",
                      postbackData: "view_location",
                      openUrlAction: {
                        url: "https://maps.google.com/?q=Galleria+Vittorio+Emanuele+II,+Milan,+Italy"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 01: T-Shirts",
                description: "Bold graphics. Oversized fit. Designed to stand out.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-tshirt.png"
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_tshirts",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-tshirt.png"
                      }
                    }
                  }
                ]
              },
              {
                title: "Drop 02: Hats",
                description: "Top off your look. Fresh colors, bold logos.",
                media: {
                  height: "TALL",
                  contentInfo: {
                    fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/main/rcs-fashion-hat.png",
                  }
                },
                suggestions: [
                  {
                    action: {
                      text: "See All",
                      postbackData: "see_hats",
                      openUrlAction: {
                        url: "https://github.com/Vonage-Community/tutorial-messages-node-rcs_carousel-rich-card/blob/main/rcs-fashion-hat.png"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  };

  try {
    const response = await vonage.messages.send(message);
    console.log("Carousel sent:", response);
    res.status(200).json({ message: "Carousel sent successfully." });
    console.log("Vonage API response:", JSON.stringify(response, null, 2));
  } catch (error) {
    console.error("Error sending carousel:", error);
    res.status(500).json({ error: "Failed to send carousel." });
  }
});

Como receber sugestões de ações do RCS por meio de webhooks

Exibir um carrossel é ótimo! Mas não seria legal saber se o usuário interagiu com o seu carrossel? Com os webhooks da Vonage, você pode fazer exatamente isso.

Crie o seguinte endpoint, que irá processar as solicitações RCS recebidas do nosso aplicativo da Vonage. Este código:

• Verifica se a solicitação é proveniente da Vonage por meio de uma assinatura JWT

• Procura o botão , já que você está esperando uma ação em vez de uma resposta , e armazena a carga útil em userAction

• Registra a userAction em nosso servidor Node para verificar o que o usuário selecionou

app.post('/inbound_rcs', async (req, res) => {
  const token = req.headers.authorization?.split(' ')[1];

  if (!verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    res.status(401).end();
    return;
  }

  const inboundMessage = req.body;

  if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'button') {
    const userAction = inboundMessage.button.payload;
    const userNumber = inboundMessage.from;

    console.log(`User ${userNumber} tapped action: ${userAction}`);
  }

  res.status(200).end();
});

Como definir seu servidor Express

Na parte inferior do seu arquivo arquivo index.js, adicione este código para criar seu servidor Express.

app.listen(PORT, () => {
  console.log(`Server is running on port ${PORT}`);
});

E, por fim, execute seu servidor a partir da linha de comando:

node index.js

>> Veja o arquivo index.js completo.

Como expor seu servidor com o ngrok

Para receber webhooks da Vonage, seu servidor local deve estar acessível pela internet. Use o ngrok para expor seu servidor executando o seguinte comando em uma aba separada aba do seu servidor Express:

ngrok http 3000

Anote a URL HTTPS fornecida pelo ngrok (por exemplo, https://your-ngrok-subdomain.ngrok.io).

Você pode ler mais sobre testes com o ngrok nas ferramentas do nosso portal para desenvolvedores.

Como criar e configurar seu aplicativo da Vonage

Agora que seu aplicativo Node está pronto, você também precisará criar e configurar seu aplicativo Vonage. Primeiro, crie seu aplicativo no Painel da Vonage. Dê um nome ao aplicativo e ative o recurso “Mensagens”. 

Vonage dashboard showing the creation of a new application configured for RCS messaging.

Nas configurações do seu aplicativo Vonage:

1. Defina a URL de entrada como https://YOUR_NGROK_URL/inbound_rcs.

2. Defina a URL de status como https://example.com/rcs_status.
   ** Os status das mensagens serão abordados em um artigo futuro.

3. Gere uma chave pública e uma chave privada clicando no botão. Certifique-se de mover sua private.key para o diretório raiz do projeto (rcs-carousel-node).

4. Salve as alterações.

Em seguida, vincule seu RCS Agent clicando no guia “Vincular contas externas” :

Dashboard view showing the Vonage-Node-RCS application linked to the Vonage RoR RCS external account, with voice and message capabilities enabled.

Como testar seu aplicativo Node

Use isto curl para acionar seu endpoint (substitua os espaços reservados):

curl -X POST https://YOUR_NGROK_URL/send-rcs-carousel \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

No celular do destinatário, o Carrossel de Rich Cards será exibido, e ele poderá selecionar uma ação!

Observações finais

Você acabou de criar um carrossel interativo de produtos RCS usando o Node.js e a Messages API do Vonage. Essa é uma ótima maneira de apresentar produtos, promover eventos ou oferecer opções dinâmicas em uma única mensagem.

Quer ir mais longe?

• Responder a toques e seleções por meio de postbackData

• Carregar fichas de produtos dinamicamente a partir de uma API

• Adicionar filtros ou categorias baseados na localização

Venha mostrar o que você está desenvolvendo na Slack da Comunidade Vonage ou marque a gente no X (antigo Twitter). Adoraríamos ver seus carrosséis em ação!