Introdução

Sabe aquela sensação de olhar para o guarda-roupa e pensar: “Não tenho nada para vestir”? Isso acontece com a maioria de nós. A gente acaba usando sempre as mesmas poucas peças, enquanto as outras ficam esquecidas. E se você pudesse mandar uma mensagem para o seu guarda-roupa e ele mostrasse o que você tem?

Então, nesta postagem do blog, vamos criar um assistente digital de guarda-roupa. É um projeto divertido que permite que você use Serviços de Comunicação Avançada (RCS) para enviar mensagens de texto a um bot. Ele mostrará fotos das suas roupas. Usaremos a Messages API da Vonage e a API do Google Gemini para torná-lo inteligente. Trata-se de transformar um problema simples em uma solução tecnológica bacana.

Você pode encontrar o código completo no repositório do GitHub.

RCS Conversation

Pré-requisitos

Para acompanhar, você vai precisar de:

• Um agente registrado do RCS Business Messaging (RBM)

• Um celular com recursos de RCS para testes

• Node.js 18+

• Account da API da Vonage

Obter o código

git clone https://github.com/Vonage-Community/blog-messages-nodejs-rcs_wardrobe

cd blog-messages-nodejs-rcs_wardrobe

npm install

Dependências

Este projeto utiliza as dependências incluídas no arquivo package.json.

Express. Você pode clicar em cada um deles para ver suas definições no npm: dotenv, @vonage/server-sdk, @vonage/messages, @vonage/jwte @google/genai.

Estrutura do projeto

Você pode encontrar a estrutura do projeto no repositório do GitHub que acompanha a postagem do blog.

src/index.js       server, wardrobe endpoint, webhook handlers

src/vonage.js      Vonage client setup with your private key

wardrobe.json      sample items that reference image filenames

Photos/            images used by wardrobe.json

private.key        your Vonage application private key (add this file)

.env               environment variables (create this)

Criar uma aplicação da Vonage

As etapas a seguir mostram como criar uma nova aplicação da Vonage a partir do painel de controle. Como alternativa, você pode usar a CLI para criar um aplicativo.

Criar um novo aplicativo

Acesse “Seus Applications” no painel da Vonage e clique para criar um novo aplicativo.

Gerar credenciais

Crie um par de chaves pública/privada para autenticação na API. Clique em “Gerar chave pública e privada” para obter a chave privada. O arquivo será baixado para o local definido no seu navegador para arquivos baixados. Certifique-se de adicionar esse arquivo à pasta do projeto.

Recursos da Messages API

Iniciar uma instância de tunelamento do ngrok

Execute o comando a seguir para iniciar um instância de tunelamento do ngrok .

ngrok http 3000

Na saída, você encontrará uma URL que começa com https:// e termina em .ngrok.app/. Anote-a, pois você precisará dela na próxima etapa para configurar seus webhooks.

Forwarding https://94cd51b63460.ngrok.app/ -> http://localhost:8000         

Messages Webhooks

Configurar Webhooks

De volta ao Painel da API da Vonage, na seção “Aplicativos”, ative a opção “Mensagens” em “Recursos” e defina a URL pública do seu servidor do ngrok como o ponto de extremidade para mensagens e eventos recebidos. Deve ficar assim: https://94cd51b63460.ngrok.app/webhooks/inbound para mensagens recebidas e https://94cd51b63460.ngrok.app/webhooks/status para status. Se você quiser saber mais sobre webhooks, você pode encontrar informações em nossa documentação da Vonage.

Variáveis de ambiente

As variáveis de ambiente permitem manter as credenciais e a configuração fora do seu código. Crie um arquivo .env na raiz do repositório e adicione as seguintes variáveis de ambiente:

VONAGE_APPLICATION_ID=your-app-id

VONAGE_PRIVATE_KEY_PATH=./private.key

RCS_SENDER_ID=your-rcs-sender-id

GEMINI_API_KEY=your-gemini-api-key

VONAGE_API_SIGNATURE_SECRET=your-signature-secret

PUBLIC_BASE_URL=https://your-ngrok-subdomain.ngrok-free.app

PHONE_NUMBER=+<your_e164_number>

PORT=3000

Como funciona

O servidor fornece /photos a partir de Photos, Verify os webhooks da Vonage com sua chave secreta de assinatura, lê a mensagem de texto RCS do usuário, carrega o arquivo wardrobe.json e solicita ao Gemini { TextResponse, ReferencedImages }. Ele retorna o texto e, em seguida, envia imagens; se houver várias, envia um carrossel. As URLs das imagens usam PUBLIC_BASE_URL/photos/<filename>.

src/index.js contém as rotas, a verificação de webhooks, a chamada Gemini e a lógica de envio RCS. src/vonage.js carrega os valores do ambiente, lê o arquivo private.key e cria o cliente Vonage.

const verifyJWT = (req) => {
  // Verify if the incoming request came from Vonage
  const jwtToken = req.headers.authorization.split(" ")[1];
  if(!verifySignature(jwtToken, process.env.VONAGE_API_SIGNATURE_SECRET)) {
    console.error("Signature does not match");
    throw new Error("Not a Vonage API request");
  }

  console.log("JWT verified");
}

npm install @vonage/jwt

Execute node src/index.jse, em seguida, acesse http://localhost:3000/wardrobe uma vez para enviar a primeira mensagem para PHONE_NUMBER. Depois que a conversa aparecer no seu aparelho, responda com suas dúvidas.

Execute o arquivo JavaScript

Na raiz do repositório, execute o seguinte comando no terminal. Certifique-se de que sua instância do ngrok ainda esteja em execução.

node src/index.js

Comece a conversa

Para enviar a primeira mensagem de agente para PHONE_NUMBER para abrir um tópico do RCS no seu dispositivo, acesse esta URL no seu navegador: http://localhost:3000/wardrobe.

Teste no RCS

Você pode conversar com seu guarda-roupa digital, que lê as informações do arquivo wardrobe.json. Você pode fazer perguntas sobre as roupas, por exemplo: “Quantas calças skinny eu tenho?”. Em seguida, ele envia uma mensagem RCS Rich Card Carousel contendo as roupas que atendem aos critérios que você especificou, e as imagens são obtidas de PUBLIC_BASE_URL/photos/<filename>. 

Observação: Para este projeto, utilizei um arquivo JSON já preenchido; no entanto, também seria possível ler os dados de um banco de dados. O Gemini não utiliza visão computacional neste caso; em vez disso, ele ajuda a filtrar o arquivo JSON com base na sua consulta de texto, e a mensagem RCS, então, utiliza os links de imagem contidos nesse arquivo. Você pode ver como é a interação na imagem que adicionei bem no início desta postagem do blog.

Conclusão

Hoje, você aprendeu a criar um guarda-roupa digital com IA usando o Gemini e a enviar mensagens com carrossel de Rich Cards via RCS. Experimente agora os outros tipos de mensagens RCS, além do texto, como: rich cards, carrosséis de Rich Cards, respostas sugeridas, ações sugeridas.

Para saber mais sobre como você pode usar esses recursos, confira este tutorial sobre como Criar um serviço de narrativa com Rich Cards do RCS e o Gemini. Você pode usar os Rich Cards para criar uma narrativa, em que cada cartão representa um capítulo ou uma escolha diferente em uma história interativa. Aqui vai uma recomendação de post de blog: Como enviar carrosséis de Rich Cards do RCS com Node.js.