Envie e receba respostas sugeridas do RCS com o ASP.NET Core e a Vonage

Serviços de Comunicação Avançada (RCS) representam a evolução do SMS: trazendo experiências personalizadas com a marca, interativas e semelhantes às de aplicativos para o seu aplicativo de mensagens nativo. Com Messages API da Vonage, você pode enviar mensagens RCS com respostas sugeridas: opções clicáveis que aumentam o engajamento e agilizam o gerenciamento das respostas.

Neste tutorial, você criará do zero uma Web API do ASP.NET Core que utiliza o SDK .NET da Vonage para enviar e receber mensagens de resposta sugeridas do RCS. Você também aprenderá a configurar o aplicativo, definir webhooks seguros e testar o fluxo de ponta a ponta usando o ngrok e seu celular habilitado para RCS.

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

RCS message sent using the Vonage Messages API, prompting the user to select a preferred appointment time with suggested reply buttons.

Pré-requisitos

Antes de começarmos, certifique-se de que você tenha:

• SDK do .NET 9.0

• Visual Studio 2022+ ou VS Code

• ngrok para tunelamento local

• Um account da API da Vonage e um agente RBM. (Veja abaixo)

• Um dispositivo compatível com RCS para testes

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

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

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.

Criar o projeto ASP.NET Core

Começaremos gerando uma Web API mínima do ASP.NET Core usando o modelo integrado da CLI.

dotnet new web -n RcsSuggestedReplies
cd RcsSuggestedReplies

Adicionar pacotes NuGet necessários

Instale as dependências necessárias:

dotnet add package Vonage
dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson
dotnet add package Microsoft.AspNetCore.OpenApi
dotnet add package Swashbuckle.AspNetCore

• Vonage: Para usar a Messages API

• Newtonsoft.Json: Manipulação de JSON para solicitações e respostas de API

• OpenApi: Suporte à especificação OpenAPI para seus endpoints

• Swashbuckle: Swagger UI para testar sua API no navegador

Criar uma classe de configuração

Criar CustomConfiguration.cs na raiz do seu projeto e adicione:

namespace RcsSuggestedReplies;

public record CustomConfiguration
{
    public string SenderId { get; init; } = string.Empty;
}

Esta classe utiliza o tipo `record` do C# para definir um objeto de configuração simples e imutável. Ela permite vincular configurações fortemente tipadas do arquivo appsettings.json, tornando seu código mais limpo e menos propenso a erros do que usar strings brutas em todos os lugares.

Configurar as configurações do aplicativo

Crie ou atualize seu arquivo appsettings.json :

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Vonage": {
    "Application.Id": "YOUR_APPLICATION_ID",
    "Application.Key": "-----BEGIN PRIVATE KEY YOUR_PRIVATE_KEY"
  },
  "CustomConfiguration": {
    "SenderId": "YOUR_SENDER_ID"
  }
}

Seu appsettings.json armazena configurações de tempo de execução, como credenciais, ID do remetente e níveis de log. Manter configurações confidenciais como essas em um arquivo de configuração permite a separação entre o código e os valores específicos do ambiente.

Atualize essas variáveis assim que tiver concluído o seção “Crie e configure seu aplicativo Vonage” abaixo.

Criar o endpoint “Enviar mensagem”

Crie um arquivo chamado SendRcsMessageEndpoint.cs na raiz do seu projeto. Esse arquivo define a lógica da API para o envio de mensagens RCS. O SendRcsRequest modela o corpo JSON recebido, enquanto o SendRcsMessageEndpoint lida com a lógica de envio da mensagem por meio da Messages API. Separamos a lógica que constrói a carga útil da mensagem em um método próprio, BuildRcsCustomRequest. Isso melhora a legibilidade e torna a função mais fácil de testar ou ampliar. Por exemplo, você poderia personalizar as sugestões dinamicamente no futuro.

Por enquanto, esse endpoint lida com o envio de mensagens RCS com três respostas sugeridas pré-definidas para agendamento de compromissos.

using Microsoft.Extensions.Options;
using Vonage.Messages;
using Vonage.Messages.Rcs;

namespace RcsSuggestedReplies;

public record SendRcsRequest(string To);

public class SendRcsMessageEndpoint(IMessagesClient messagesClient, IOptions<CustomConfiguration> customConfiguration)
{
    public async Task<IResult> SendRcsMessage(SendRcsRequest request)
    {
        try
        {
            var response = await messagesClient.SendAsync(BuildRcsCustomRequest(request));
            Console.WriteLine($"Message sent: {response.MessageUuid}");
            return Results.Ok();
        }
        catch (Exception exception)
        {
            Console.WriteLine($"Error sending message: {exception.Message}");
            return Results.Problem(exception.Message);
        }
    }

    private RcsCustomRequest BuildRcsCustomRequest(SendRcsRequest sendRcsRequest)
    {
        return new RcsCustomRequest
        {
            From = customConfiguration.Value.SenderId,
            To = sendRcsRequest.To,
            Custom = new
            {
                ContentMessage = new
                {
                    Text = "What time works best for your appointment?",
                    Suggestions =
                        new[]
                        {
                            new
                            {
                                Reply = new
                                {
                                    Text = "9am",
                                    PostbackData = "time_9am"
                                }
                            },
                            new
                            {
                                Reply = new
                                {
                                    Text = "11am",
                                    PostbackData = "time_11am"
                                }
                            },
                            new
                            {
                                Reply = new
                                {
                                    Text = "2pm",
                                    PostbackData = "time_2pm"
                                }
                            }
                        }
                }
            }
        };
    }
}

Criar o ponto de extremidade de recepção de mensagens

Crie outro arquivo chamado ReceiveRcsInboundEndpoint.cs na raiz do seu projeto. Essa classe lida com mensagens de webhook recebidas da Vonage. Ela verifica a autenticidade da solicitação usando a validação JWT e envia uma resposta de confirmação quando o usuário seleciona uma das respostas sugeridas. A verificação da assinatura JWT garante que você não esteja processando mensagens falsificadas ou maliciosas e que as solicitações recebidas sejam, de fato, provenientes da Vonage. Após analisar a resposta do usuário, enviamos uma mensagem de confirmação amigável. Manter essa lógica em um método separado mantém o função ReceiveRcsInbound mais focada e fácil de ler.

using Microsoft.Extensions.Options;
using Vonage;
using Vonage.Messages;
using Vonage.Messages.Rcs;
using Vonage.Messages.Webhooks;
using Vonage.Request;

namespace RcsSuggestedReplies;

public class ReceiveRcsInboundEndpoint(IMessagesClient messagesClient, IOptions<CustomConfiguration> customConfiguration, Credentials credentials)
{
    public async Task<IResult> ReceiveRcsInbound(HttpContext httpContext, MessageWebhookResponse messageWebhookResponse)
    {
        var token = httpContext.Request.Headers.Authorization.ToString().Split(' ')[1];
        if (!Jwt.VerifySignature(token, credentials.ApplicationKey))
        {
            return Results.Unauthorized();
        }

        if (messageWebhookResponse is {Channel: "rcs", MessageType: "reply"})
        {
            var userSelection = messageWebhookResponse.Reply?.ToString();
            Console.WriteLine($"User {messageWebhookResponse.From} select: {userSelection}");
            try
            {
                var response =
                    await messagesClient.SendAsync(BuildConfirmationMessage(messageWebhookResponse, userSelection));
                Console.WriteLine($"Confirmation sent: {response.MessageUuid}");
            }
            catch (Exception exception)
            {
                Console.WriteLine($"Error sending confirmation: {exception.Message}");
            }
        }

        return Results.Ok();
    }

    RcsTextRequest BuildConfirmationMessage(MessageWebhookResponse messageWebhookResponse1, string? s) =>
        new()
        {
            To = messageWebhookResponse1.From,
            From = customConfiguration.Value.SenderId,
            Text = $"{s} is a great choice!",
        };
}

Este endpoint processa as mensagens RCS recebidas, verifica sua autenticidade e envia respostas de confirmação.

Configurar o arquivo Program.cs

Atualize seu arquivo Program.cs para o seguinte.

Aqui, configuramos a injeção de dependências, que é um elemento central do projeto do ASP.NET Core. Registramos o cliente Vonage e nossos endpoints personalizados para que possam ser injetados onde for necessário, tornando o código mais modular.

using RcsSuggestedReplies;
using Vonage.Extensions;
using Vonage.Messages.Webhooks;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// Register Vonage and application services
builder.Services.AddVonageClientScoped(builder.Configuration);
builder.Services.Configure<CustomConfiguration>(builder.Configuration.GetSection("CustomConfiguration"));
builder.Services.AddScoped<SendRcsMessageEndpoint>();
builder.Services.AddScoped<ReceiveRcsInboundEndpoint>();

var app = builder.Build();

// Configure the HTTP request pipeline
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.MapControllers();

// Define our API endpoints
app.MapPost("send-rcs",
    async (SendRcsMessageEndpoint endpoint, SendRcsRequest request) => await endpoint.SendRcsMessage(request));
app.MapPost("inbound-rcs",
    async (ReceiveRcsInboundEndpoint endpoint, HttpContext context, MessageWebhookResponse inbound) =>
        await endpoint.ReceiveRcsInbound(context, inbound));

app.Run();

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 ASP.NET Core, que será executado na porta 5000:

ngrok http 5000

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.

>> Seu aplicativo pode estar sendo executado em uma porta diferente. Você pode verificar no arquivo launchSettings.json para confirmar.

Crie e configure seu aplicativo da Vonage

Agora que seu aplicativo ASP.NET 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”. 

Nas configurações do seu aplicativo Vonage:

1. Defina o URL de entrada como https://YOUR_NGROK_URL/inbound-rcs.

2. Defina o 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 (RcsSuggestedReplies).

4. Salve as alterações.

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

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

Atualize suas credenciais da Vonage

Substitua os valores provisórios em appsettings.json pelas suas credenciais reais da Vonage:

"Vonage": {
  "Application.Id": "YOUR_ACTUAL_APPLICATION_ID",
  "Application.Key": "YOUR_PRIVATE_KEY"
},
"CustomConfiguration": {
  "SenderId": "YOUR_ACTUAL_SENDER_ID"
}

Execute seu aplicativo e faça o teste

Comece sua inscrição:

dotnet run

Seu aplicativo de mensagens RCS já está em execução! Você pode usar uma ferramenta como o Postman ou o cURL para enviar uma solicitação POST para o seu /send-rcs com o número de telefone do destinatário:

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

No dispositivo do destinatário compatível com RCS, a mensagem com as respostas sugeridas deve aparecer.

Quando o destinatário seleciona uma resposta sugerida, seu /inbound-rcs processará a resposta, e uma mensagem de confirmação será enviada de volta.

RCS conversation where a user selects a time from suggested replies and receives a confirmation message, powered by the Vonage Messages API.

Conclusão

Você acabou de criar um aplicativo ASP.NET Core funcional, capaz de enviar e receber respostas sugeridas do RCS usando a Messages API do Vonage. Essa melhoria simples na interface do usuário, que permite que os usuários toquem em uma resposta em vez de digitá-la, pode melhorar significativamente a forma como os usuários interagem com seu aplicativo.

Com verificação por webhook, tratamento estruturado de respostas e mensagens de confirmação, este modelo oferece uma base sólida para você expandir suas funcionalidades. Experimente adicionar RCS Cards, armazenar respostas em um banco de dados ou gerar dinamicamente sugestões de respostas a partir do histórico do usuário

Se você tiver alguma dúvida ou ideias sobre o que gostaria de desenvolver a seguir, venha participar da conversa na nossa Slack da Comunidade Vonage ou entre em contato pelo X (antigo Twitter). Adoraríamos ver o que você criar!