){kind=small}
Crie um serviço de narrativa com os Rich Cards do RCS e o Gemini
Este tutorial mostra como criar um serviço de narrativa com IA generativa usando a Messages API da Vonage para RCS e Gemini do Google . Você aprenderá o que é o RCS, como enviar e receber mensagens RCS Rich Card e como integrar o Gemini para gerar pequenas histórias para dormir.
Inspirado pelas rotinas de hora de dormir do meu filho pequeno, quis criar algo útil. Por isso, combinei mensagens RCS com a IA Gemini para desenvolver um serviço simples de contação de histórias.
RCS Story Demonstration
Você pode encontrar o código-fonte completo no repositório GitHub da Comunidade Vonage.
O Node.js está instalado no seu computador.
Um serviço de tunelamento de API, como ngrok.
Um agente registrado agente do RCS Business Messaging (RBM).
Para enviar e receber mensagens RCS no seu aplicativo da Vonage, você precisa de um agente RBM registrado e de um telefone compatível com RCS.
Atualmente, o RCS via Vonage está disponível apenas para contas gerenciadas. Você precisará entrar em contato com seu gerente de conta para ativar o Modo Desenvolvedor, que permite realizar testes com números incluídos na lista de permissões.
Caso você não tenha um account gerenciado, entre em contato com a Equipe de Vendas da Vonage para obter suporte.
RCS (Rich Communication Services): Um padrão do setor que aprimora as mensagens tradicionais com mídia avançada, conteúdo de marca e confirmações de leitura. Se o dispositivo ou a rede do destinatário não for compatível com RCS, as mensagens são automaticamente redirecionadas para SMS para garantir que ainda sejam entregues.
Saiba mais em nossa documentação do RCS.
SMS (Serviço de Mensagens Curtas): O SMS tradicional suporta apenas texto simples. O RCS permite botões com a marca, imagens e atualizações de status das mensagens. Aprenda a enviar mensagens SMS com o Node.js.
MMS (Serviço de Mensagens Multimídia): Ao contrário do MMS, que geralmente apresenta qualidade de mídia inferior e limites de tamanho de arquivo, o RCS oferece suporte a mídia de alta qualidade e recursos como indicadores de digitação e atualizações do status de entrega. Saiba o que você pode fazer com o MMS e como enviar MMS com Node.js.
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.
Se você ainda não usou o ngrok, pode começar por aqui. Adicionei as etapas para executar uma instância abaixo da imagem na próxima seção.
Execute o comando a seguir para iniciar uma instância de tunelamento do ngrok.
ngrok http 3000Na 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
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.
webhooks
Clone o repositório da Comunidade Vonage no GitHub para este projeto e npm install as dependências.
npm install express debug @vonage/messages @vonage/server-sdk dotenv
Crie um arquivo .env na raiz do seu projeto.
VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID, can be found within the application you’ve created
VONAGE_PRIVATE_KEY=./private.key, is the path to the private.key file that was generated when you created your application
RCS_SENDER_ID=YOUR_RCS_SENDER_ID
PHONE_NUMBER=YOUR_PHONE_NUMBER_E164 that will receive the RCS messages
PORT=3000
VONAGE_API_SIGNATURE_SECRET= is the secret used to sign the request that corresponds to the signature secret associated with the api_key included in the JWT claims. You can identify your signature secret on the Dashboard settingsNo seu projeto, você também encontrará um arquivo vonage.js que contém o Dotenv e a configuração do cliente Vonage.
Adicione uma função de verificação de JWT para verificar se a solicitação recebida (por exemplo, mensagem ou chamada) veio da Vonage.
A variável VONAGE_API_SIGNATURE_SECRET é o segredo usado para assinar a solicitação, correspondente ao segredo de assinatura associado à chave de API incluída nas reivindicações do JWT. Você pode identificar seu segredo de assinatura na configurações do painel.
Você pode saber mais sobre como verificar a solicitação.
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");
}Certifique-se de instalar a dependência @vonage/jwt.
npm install @vonage/jwt
No seu arquivo server.js, você encontrará o código finalizado com a integração do Gemini, mas eu queria lhe dar um ponto de partida sobre como enviar uma mensagem Rich Card no RCS com um texto pré-definido, para que você possa ter uma primeira experiência com isso e vê-la funcionando antes de qualquer configuração mais complexa, com tudo o que configuramos até agora.
Comece adicionando as importações e definindo suas variáveis.
import Express from "express";
import { RCSCustom, RCSText } from "@vonage/messages";
import { vonage } from "./vonage.js";
import "dotenv/config";
const app = new Express();
const port = process.env.PORT || 3000;
const recipientNumber = process.env.PHONE_NUMBER;
if (!recipientNumber) {
process.exit(1);
}
if (!process.env.RCS_SENDER_ID) {
process.exit(1);
}Também usaremos um wrapper assíncrono para o tratamento de erros nas rotas.
const catchAsync = (fn) => (req, res, next) => {
fn(req, res, next).catch(next);
};
app.use(Express.json());
app.get(
"/send-story-request",
catchAsync(async (req, res) => {
await sendBedtimeStoryRequest(recipientNumber);
res.status(200).json({ message: "Bedtime story request sent!" });
})
);Crie o /webhooks/status ponto de extremidade.
app.post(
"/webhooks/status",
catchAsync(async (req, res) => {
res.status(200).json({ ok: true });
})
);
Crie o /webhooks/inbound ponto de extremidade.
app.post(
"/webhooks/inbound",
catchAsync(async (req, res) => {
const { channel, message_type, reply, from } = req.body;
if (channel === 'rcs' && message_type === 'reply' && reply) {
const receivedId = reply.id;
const receivedTitle = reply.title;
if (receivedId === 'GENERATE_STORY_REQUEST' || receivedTitle === 'Generate Story') {
const replyToNumber = from;
const helloWorldMessage = "Hello world!";
await sendRCSGreeting(replyToNumber, helloWorldMessage);
} else {
// Unhandled reply
}
} else if (channel === 'rcs' && message_type === 'text') {
if (req.body.text && req.body.text.toLowerCase() === 'generate story') {
await sendRCSGreeting(from, "Hello world!");
} else {
await sendRCSGreeting(from, "I received your message: " + req.body.text);
}
}
res.status(200).json({ ok: true });
})
);Adicione algumas mensagens de tratamento de erros, e o aplicativo ficará à escuta na porta definida (3000).
app.all("*", (req, res) => {
res.status(404).json({
status: 404,
title: "Not Found",
});
});
app.use((err, req, res, next) => {
res.status(500).json({
status: 500,
title: "Internal Server Error",
detail: err.message,
});
});
app.listen(port);Crie o sendBedtimeStoryRequest que envie uma nova mensagem personalizada do RCS com o texto “Gerador de histórias para dormir”, contendo um botão para gerar uma nova história.
const sendBedtimeStoryRequest = async (number) => {
const message = new RCSCustom({
to: number,
from: process.env.RCS_SENDER_ID,
custom: {
contentMessage: {
richCard: {
standaloneCard: {
cardOrientation: "VERTICAL",
cardContent: {
title: "Bedtime Story Generator",
description: 'Tap "Generate Story" for a magical tale!',
media: {
height: "MEDIUM",
contentInfo: {
fileUrl:
"https://cdn-icons-png.flaticon.com/512/2917/2917637.png",
},
},
suggestions: [
{
reply: {
text: "Generate Story",
postbackData: "GENERATE_STORY_REQUEST",
},
},
],
},
},
},
},
},
});
try {
await vonage.messages.send(message);
} catch (err) {
if (err.response) {
err.response.text().catch(() => {});
}
}
};
Crie o sendRCSGreeting que envia uma mensagem RCS usando a Messages API do Vonage.
const sendRCSGreeting = async (to, messageText) => {
const message = new RCSText({
to: to,
from: process.env.RCS_SENDER_ID,
text: messageText,
});
try {
await vonage.messages.send(message);
} catch (err) {
if (err.response) {
err.response.text().catch(() => {});
}
}
};Para executar o aplicativo, inicie o servidor:
node server.jsEm seguida, acesse o URL a seguir no seu navegador, o que aciona o envio da primeira mensagem para o celular do usuário, convidando-o a criar uma história. A confirmação em formato JSON exibida no seu navegador, juntamente com a mensagem RCS recebida no seu celular, são sinais de que o sistema está funcionando.
http://localhost:3000/send-story-request
Agora que já temos as mensagens RCS e o webhook funcionando, vamos adicionar o Google Gemini ao nosso serviço de storytelling.
Ao acessar AI Studio, fizer login e criar um novo chat, você verá “<\>Obter código” no canto superior direito e poderá selecionar a linguagem de programação de sua preferência. Escolha o modelo. Eu usei o “Gemini 1.5 Flash Experimental”, mas você pode escolher aquele que fizer mais sentido para o seu projeto.
Para saber mais, acesse a página de documentação da API para desenvolvedores do Gemini.
npm install @google/generative-aiAdicione sua chave de API do Gemini ao arquivo .env.
GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
import { GoogleGenerativeAI } from "@google/generative-ai";
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const geminiModel = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });
Com o Gemini inicializado, atualizamos nosso /webhooks/inbound handler. Quando o usuário clica em “Gerar história”, em vez de responder “Olá, mundo!”, agora chamamos geminiModel.generateContent com uma solicitação específica para uma história para dormir.
O texto gerado é então enviado de volta ao usuário usando sendGeneratedStory. Também adicionamos um recurso para lidar com usuários que possam digitar “Gerar história” manualmente.
A sendGeneratedStory função agora pega o texto da história gerado e usa o RCSText para reenviá-lo como uma mensagem de texto RCS comum.
Para executar o aplicativo, (re)inicie o servidor:
node server.jsEm seguida, acesse o seguinte URL no seu navegador: http://localhost:3000/send-story-request
Você receberá uma mensagem RCS no seu dispositivo. Toque em “Gerar história” para receber uma história para dormir criada pelo Gemini.
RCS Project
Conclusão
Este tutorial mostrou como criar um serviço de storytelling com tecnologia Gemini usando a API RCS da Vonage. A última vez que trabalhei com RCS foi em 2020. Participei de um workshop em que cada participante recebeu um cartão SIM compatível com RCS. Foi bom voltar a trabalhar com RCS, e mal posso esperar para escrever mais posts no blog sobre esse assunto.
Tem alguma dúvida ou quer compartilhar o que está criando?
Inscreva-se no Boletim Informativo para Desenvolvedores
Siga-nos no X (antigo Twitter) para ficar por dentro das novidades
Assista aos tutoriais no nosso canal do YouTube
Conecte-se conosco na página de desenvolvedores da Vonage no LinkedIn
Fique conectado e acompanhe as últimas notícias, dicas e eventos para desenvolvedores.