Enviar e abrir arquivos RCS usando o GitHub Codespaces

Introdução

Este tutorial mostra como enviar e abrir um arquivo via RCS com a Messages API for Vonage. Ao contrário do SMS ou do MMS, o RCS suporta arquivos de melhor qualidade sem limites rígidos de tamanho, tornando-o uma opção adequada para documentos como bilhetes, faturas ou PDFs. Nesta postagem, enviaremos um arquivo PDF via RCS usando o GitHub Codespaces.

open RCS message containing PDF

Pré-requisitos

• A Account no GitHub

• Um agente registrado do RCS Business Messaging (RBM)

• Um celular com recursos de RCS para testes

GitHub Codespaces

Visão geral

Tenho explorado o GitHub Codespaces ultimamente. Trata-se de um ambiente de desenvolvimento hospedado em um contêiner Docker, rodando em uma máquina virtual. Eu costumo usá-lo acessando um repositório do GitHub e acrescentando /codespaces à URL, para poder acessá-lo no Visual Studio Code pelo meu navegador preferido. Como alternativa, é possível criar uma instância do Codespaces a partir de um modelo ou de qualquer branch ou commit em um repositório do GitHub.

Abrir o projeto no Codespaces

Você pode começar acessar o repositório que criei para esta postagem do blog e acrescentando /codespaces. A URL ficaria assim: https://github.com/Vonage-Community/blog-messages-nodejs-rcs-file/codespaces 

Clique em “Criar codespace no main”, no canto superior direito da página. O GitHub começará a configurar um novo ambiente para você. 

Click “Create codespace on main” to start your environmentAssim que carregar, você estará dentro de um editor VS Code baseado em navegador, onde poderá executar e editar o projeto imediatamente. Use isso para executar sua instância. No entanto, fique à vontade para executar o código que vou mostrar nesta postagem do blog no seu IDE ou ambiente preferido.

Para mais detalhes, consulte o guia oficial do GitHub: Introdução rápida ao GitHub Codespaces.

Aprenda alguns comandos no Codespaces

Se você já tem experiência com o Visual Studio Code, vai conseguir se orientar usando o Codespaces. É sempre possível navegar e encontrar os itens abaixo nos menus, mas aqui estão alguns comandos para ajudar você a navegar com mais facilidade:

• Abrir arquivos: Control + ` no Mac ou no Windows/Linux.

• Abra o terminal: Command + Shift + P no Mac ou Ctrl + Shift + P no Windows/Linux.

Instalação usando o npm

Execute npm install no terminal do Codespaces para instalar os seguintes pacotes, que podem ser encontrados no arquivo `package.json`.

• dotenv: carrega suas variáveis de ambiente a partir de um arquivo .env, mantendo em sigilo informações confidenciais, como chaves de API.

• @vonage/server-sdk: o SDK principal do Vonage para Node.js. Ele ajuda você a autenticar e inicializar o cliente Vonage.

• @vonage/messages: uma biblioteca dedicada ao envio de mensagens por meio da Messages API do Vonage. Nós a utilizamos para enviar mensagens RCS (texto, imagens, arquivos etc.).

npm install dotenv @vonage/server-sdk @vonage/messages

Adicionar as variáveis de ambiente

Algumas variáveis contêm informações confidenciais; por isso, não gostaria de adicionar publicamente chaves de API, segredos ou mesmo o número de telefone que vou usar para os testes. Portanto, vamos adicioná-las a um arquivo .env. Veja aqui mais informações sobre como usar variáveis de ambiente no Node.

Criar um arquivo .env

Copie o arquivo .env.example para um novo arquivo .env que você deve criar agora. No terminal do Codespaces:

touch .env

No trecho de código abaixo, listo todas as variáveis de ambiente de que precisaremos. Vou explicá-las uma a uma e indicar onde encontrá-las.

VONAGE_APPLICATION_ID=000000-0000-0000-0000-0000000000

VONAGE_PRIVATE_KEY=./private.key

RCS_SENDER_ID=NameOfYourAgent

MESSAGES_FILE_URL=https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf

• Faça login no seu Account da Vonage e prossiga com a criação de um novo aplicativo.

  • Para criar um aplicativo, acesse a página “Criar um aplicativo” no Painel da Vonage e defina um Nome para a sua Application.

    

  • Se você pretende usar uma API que utilize Webhooks, precisará de uma chave privada. Clique em “Gerar chave pública e privada”; o download deve iniciar automaticamente. Guarde-a em local seguro; essa chave não poderá ser baixada novamente em caso de perda. Ela seguirá a convenção de nomenclatura private_<seu ID de aplicativo>.key. Agora, essa chave pode ser usada para autenticar chamadas de API. Observação: sua chave não funcionará até que seu aplicativo seja salvo.

  • Escolha os recursos de que você precisa (por exemplo, Voice, Mensagens, RTC etc.) e forneça os webhooks necessários (por exemplo, URLs de eventos, URLs de resposta ou URLs de mensagens recebidas). Esses itens serão descritos no tutorial.

  • Para salvar e implantar, clique em “Gerar novo aplicativo” para finalizar a configuração. Seu aplicativo já está pronto para ser usado com as APIs da Vonage.

• Na visualização do aplicativo, cada aplicativo contém um ID de aplicativo. Copie essa sequência de caracteres e cole-a na sua VONAGE_APPLICATION_ID variável.

• Clique para gerar uma chave privada. Um arquivo será baixado para a sua pasta de downloads. Adicione-o à raiz do seu arquivo no GitHub Codespaces. Nomeie-o como private.key.

• As mensagens RCS são enviadas por um agente, que pode ser encontrado na aba “vincular contas externas” depois que você o criar. Entendendo as mensagens RCS.

• O MESSAGES_FILE_URL contém uma URL para um arquivo a ser enviado por meio de uma mensagem RCS. Tenho usado esse caminho de um arquivo PDF público para testes.

Entenda a lógica

Abra o index.js arquivo JavaScript, que pode ser encontrado no menu à esquerda no GitHub Codespaces.

Importar dependências

No início do seu arquivo, você verá a importação dos dois pacotes da Vonage: @vonage/server-sdk e @vonage/messages, que foram explicados anteriormente na seção “Instalação usando o npm”.

import "dotenv/config";

const { Vonage } = require('@vonage/server-sdk');

const { Channels } = require('@vonage/messages');

Inicializar o cliente Vonage

Inicialize o cliente Vonage passando o ID do aplicativo e chave privada.

const vonage = new Vonage({

  applicationId: process.env.VONAGE_APPLICATION_ID,

  privateKey: process.env.VONAGE_PRIVATE_KEY,

});

Enviar a mensagem RCS

Para enviar uma mensagem RCS com a Messages API, vamos usar o vonage.messages.send método da biblioteca Vonage para Node.js, especificando o ‘RCS’ canal. Esse método aceita objetos como parâmetros, contendo informações sobre o destinatário, o remetente e o conteúdo.

Eu configurei o MessageType como um file. Você pode verificar todos os tipos de mídia compatíveis.

vonage.messages.send({

  messageType: 'file',

  channel: Channels.RCS,

  file: {

    url: process.env.MESSAGES_FILE_URL,

  },

  to: process.env.PHONE_NUMBER,

  from: process.env.RCS_SENDER_ID,

})

  .then(({ messageUUID }) => console.log(messageUUID))

  .catch((error) => {

  console.error("Error sending RCS message:", error);

});

Execute seu código

No terminal do GitHub Codespaces, execute o arquivo index.js. Ao executarmos esse arquivo, uma mensagem RCS será enviada para o número de telefone especificado. Você verá uma mensagem chamada “anexo” no dispositivo especificado e, ao clicar nela, poderá ver o arquivo que você especificou na MESSAGES_FILE_URL.

node index.js

Melhores práticas e possíveis ampliações

Se quiser se aprofundar no assunto, considere instalar e executar o ngrok para expor seu servidor local e permitir que a Vonage envie solicitações de webhook diretamente para seu ambiente de desenvolvimento. Isso facilita o teste de interações em tempo real, como mensagens recebidas e confirmações de entrega. Você também pode implementar a verificação JWT para validar os webhooks recebidos e garantir que eles venham de fontes confiáveis.

Conclusão

Agora que você aprendeu a enviar arquivos via RCS, considere ampliar sua solução implementando respostas sugeridas ou carrosséis de cartões avançados. Atualmente, o sistema simplesmente envia um anexo com o nome do arquivo. Você pode usar soluções de cartões avançados para tornar a mensagem e os arquivos compartilhados ainda mais descritivos e fáceis de visualizar.