Como enviar Rich Cards autônomos do RCS com o Node.js

Serviços de Comunicação Avançada (RCS) estão transformando a forma como as empresas se conectam com os clientes, permitindo que você adicione imagens, vídeos e elementos interativos às mensagens que aparecem nativamente nos aplicativos de mensagens padrão dos usuários. Um recurso poderoso do RCS é o cartão avançado, que combina texto, imagens ou Video e respostas sugeridas em uma única mensagem interativa.

Com a adoção global do RCS se expandindo no Android e no iOS, agora é o momento perfeito para integrar mensagens avançadas aos seus aplicativos. Neste tutorial, você aprenderá a enviar um cartão avançado independente usando a Messages API do Vonage em um aplicativo Node.js.

>> Resumo: Veja o código funcional no GitHub

O que é um Rich Card RCS independente?

Um cartão rico independente combina vários componentes de mensagem, como mídia, um título, texto descritivo e até quatro respostas sugeridas, em uma única mensagem rica. Essas mensagens são visualmente atraentes e oferecem aos usuários opções de interação imediata, sem a necessidade de digitar uma resposta.

Um rich card autônomo válido deve incluir, no mínimo, um título ou um elemento de mídia . Também pode conter:

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

• Uma imagem ou um Video (até 100 MB)

• Até quatro respostas sugeridas ou ações sugeridas (não ambas)

Pré-requisitos

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

• Node.js instalado no seu computador. Versão 22 ou superior do Node

• 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-standalone-richcard-node
cd rcs-standalone-richcard-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= Seu segredo de assinatura 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 de aplicativo da Vonage e o arquivo private.key abaixo, na seção “Como criar e configurar um aplicativo da Vonage”. Encontre seu segredo de assinatura da API no seu configurações do painel do desenvolvedor.

Como enviar um Rich Card RCS independente

O arquivo index.js conterá a funcionalidade do seu servidor Express para enviar Rich Cards do RCS com respostas sugeridas.

Carregar dependências e inicializar o cliente Vonage

Adicione este código ao seu arquivo index.js :

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 cartões RCS Rich independentes

Em seguida, crie o /send-standalone-rich-card . Essa rota irá criar e enviar uma mensagem de rich card usando a Messages API do Vonage. Nessa implementação, tudo o que você precisa passar na sua solicitação é o número de telefone do destinatário.

Os cartões enriquecidos são compostos por vários elementos: mídia, título, descrição e respostas sugeridas ou ações sugeridas. Neste exemplo, estamos enviando um único cartão com um GIF do Oscar, nosso cachorrinho do escritório, acompanhado de botões interativos. Eles permitem que os usuários respondam rapidamente com opções como “Faça carinho no cachorrinho” ou “Adote-me!”

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

  const message = {
    to: toNumber,
    from: process.env.RCS_SENDER_ID,
    channel: 'rcs',
    message_type: 'custom', // Required for sending rich cards
    custom: {
      contentMessage: {
        richCard: {
          standaloneCard: {
            thumbnailImageAlignment: "RIGHT", // Aligns image on the right in horizontal layouts
            cardOrientation: "VERTICAL", // Stack elements vertically
            cardContent: {
              title: "Meet our office puppy!", // Main headline for the card
              description: "What would you like to do next?", // Secondary text to provide context
              media: {
                height: "TALL", // Height options: SHORT, MEDIUM, TALL
                contentInfo: {
                  fileUrl: "https://raw.githubusercontent.com/Vonage-Community/tutorial-messages-node-rcs_standalone-rich-card/refs/heads/main/puppy_dev.gif",
                  forceRefresh: false // Set to true if media changes often
                }
              },
              suggestions: [
                { reply: { text: "Pet the puppy", postbackData: "pet_puppy" }},
                { reply: { text: "Give a treat", postbackData: "give_treat" }},
                { reply: { text: "Take a selfie", postbackData: "take_selfie" }},
                { reply: { text: "Adopt me!", postbackData: "adopt_puppy" }}
              ]
            }
          }
        }
      }
    }
  };

  try {
    const response = await vonage.messages.send(message);
    console.log('Standalone rich card sent:', response);
    res.status(200).json({ message: 'Standalone rich card sent successfully.' });
  } catch (error) {
    console.error('Error sending standalone rich card:', error);
    res.status(500).json({ error: 'Failed to send standalone rich card.' });
  }
});

Você pode personalizar esse endpoint passando valores dinâmicos, como o título do cartão, a descrição ou a lista de respostas sugeridas, no corpo da solicitação POST. Isso permite que você envie cartões enriquecidos personalizados, adaptados a diferentes usuários ou casos de uso.

Como receber respostas RCS por meio de webhooks

Quando um usuário toca em uma das respostas sugeridas no seu rich card, a Vonage envia um webhook de entrada para o seu aplicativo. Esse webhook contém dados estruturados sobre a interação do usuário, incluindo o reply.id, que corresponde ao postbackData que você definiu anteriormente.

Crie um /inbound_rcs para lidar com essas respostas e responder com uma mensagem personalizada.

app.post('/inbound_rcs', async (req, res) => {
  // Step 1: Extract and verify the JWT signature
  const token = req.headers.authorization?.split(' ')[1];

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

  // Step 2: Parse the inbound message payload
  const inboundMessage = req.body;

  if (inboundMessage.channel === 'rcs' && inboundMessage.message_type === 'reply') {
    const userSelection = inboundMessage.reply.id;
    const userNumber = inboundMessage.from;

    console.log(`User ${userNumber} selected: ${userSelection}`);

    // Step 3: Map each reply ID to a personalized confirmation
    const responseMessages = {
      pet_puppy: "🐶 Oscar loves pets!",
      give_treat: "🍪 Treat accepted! Oscar is wagging his tail.",
      take_selfie: "📸 Smile! Oscar’s photogenic and ready.",
      adopt_puppy: "Wow! Oscar is so lucky! You're a real hero 🦸"
    };

    const confirmationText =
      responseMessages[userSelection] || "Oscar appreciates the love! 🐾";

    // Step 4: Send a confirmation message back to the user
    const confirmationMessage = {
      to: userNumber,
      from: process.env.RCS_SENDER_ID,
      channel: 'rcs',
      message_type: 'text',
      text: confirmationText
    };

    try {
      const response = await vonage.messages.send(confirmationMessage);
      console.log('Confirmation sent:', response);
    } catch (error) {
      console.error('Error sending confirmation:', error);
    }
  }

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

O que está acontecendo neste código?

Primeiro, a solicitação do webhook é verificada por meio do token JWT para garantir que ela realmente veio da Vonage. Em seguida, obtemos a escolha do usuário usando reply.id, que corresponde ao postbackData do rich card. Com base nesse ID, selecionamos uma mensagem correspondente da responseMessages . Este é um exemplo simples de como você pode personalizar a experiência do usuário com base no botão em que ele clica.

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 arquivo index.js.

Terminal output from a Node.js application sending an RCS standalone rich card, showing server activity and user interaction response with message UUIDs.

Como expor seu servidor com o ngrok

Para receber webhooks da Vonage, seu servidor local precisa estar acessível pela internet. Use o ngrok para expor seu servidor executando o seguinte comando em uma 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-standalone-richcard-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-standalone-rich-card \
  -H "Content-Type: application/json" \
  -d '{"to": "YOUR_RCS_TEST_NUMBER"}'

No celular do destinatário, deve aparecer o rich card independente com o GIF e os botões de resposta.

Interactive RCS chat showcasing Vonage bot's playful engagement with users through options like petting, feeding, or adopting a virtual office puppy.

Conclusão

Você enviou com sucesso um “rich card” autônomo do RCS com mídia, título, descrição e respostas sugeridas usando o Node.js e a Messages API do Vonage.

Os cartões avançados são uma ótima maneira de oferecer experiências interativas e atraentes diretamente nos aplicativos de mensagens. Em tutoriais futuros, você aprenderá a usar carrosséis, acompanhar o status das mensagens e combinar cartões avançados com a lógica dos bots.

Mostre o que você está criando com o RCS e solicite conteúdos futuros na Slack da Comunidade Vonage. Você também pode entrar em contato pelo X (antigo Twitter). Adoraríamos ver seus projetos com RCS!