Enviar y recibir respuestas sugeridas RCS con ASP.NET Core y Vonage

Servicios de Comunicación Enriquecidos (RCS) representa la evolución de los SMS: aporta experiencias de marca, interactivas y similares a las de las aplicaciones a su aplicación de mensajería nativa. Con Messages API de Vonagede Vonage, puedes enviar mensajes RCS con Respuestas sugeridas: opciones en las que se puede hacer clic que mejoran el compromiso y agilizan el manejo de las respuestas.

En este tutorial, crearás una API web ASP.NET Core desde cero que utiliza SDK .NET de Vonage de Vonage para enviar y recibir mensajes de respuesta sugeridos por RCS. También aprenderás a configurar la aplicación, configurar webhooks seguros y probar el flujo de extremo a extremo usando ngrok y tu teléfono habilitado para RCS.

>> TL;DR: Ver el código completo en GitHub

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

Requisitos previos

Antes de empezar, asegúrate de que tienes:

• .NET 9.0 SDK

• Visual Studio 2022+ o VS Code

• ngrok para túneles locales

• Una Account API de Vonage y un agente RBM. (Ver a continuación)

• Un dispositivo con capacidad RCS para realizar pruebas

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Cómo contactar a tu administrador de cuentas de Vonage

Para poder enviar y recibir funciones de RCS en tu aplicación de Vonage, necesitarás tener registrado un agente de Rich Business Messaging (RBM).

Actualmente, la mensajería RCS a través de Vonage sólo está disponible para cuentas administradas. Deberás comunicarte con tu administrador de cuenta para solicitar la activación del modo para desarrolladores para tu agente de RBM. El modo para desarrolladores te permite probar la mensajería RCS a números permitidos antes de completar el proceso de verificación del agente y lanzarlo en producción.

Por favor póngase en contacto con nuestro equipo de ventas si no tiene una cuenta gestionada.

>> Comprender la diferencia entre RCS y RBM.

Crear el proyecto ASP.NET Core

Empezaremos generando una API web ASP.NET Core mínima utilizando la plantilla CLI incorporada.

dotnet new web -n RcsSuggestedReplies
cd RcsSuggestedReplies

Añadir paquetes NuGet necesarios

Instale las dependencias necesarias:

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

• Vonage: Para utilizar la API de Messages

• Newtonsoft.Json: Manejo de JSON para peticiones y respuestas API

• OpenApi: Soporte de la especificación OpenAPI para sus endpoints

• Swashbuckle: Swagger UI para probar su API en el navegador

Crear una clase de configuración

Cree ConfiguraciónPersonalizada.cs en la raíz de su proyecto y añada

namespace RcsSuggestedReplies;

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

Esta clase utiliza el método registro de C# para definir un objeto de configuración simple e inmutable. Permite enlazar configuraciones fuertemente tipadas desde appsettings.jsonhaciendo que tu código sea más limpio y menos propenso a errores que el uso de cadenas en bruto en todas partes.

Configurar los ajustes de las Applications

Cree o actualice su archivo 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"
  }
}

Su appsettings.json almacena la configuración en tiempo de ejecución, como las credenciales, el ID de remitente y los niveles de registro. Mantener ajustes sensibles como estos en un archivo de configuración permite separar el código de los valores específicos del entorno.

Actualiza estas variables una vez que hayas completado la sección "Crear y configurar tu aplicación de Vonage" a continuación.

Crear el punto final de envío de mensajes

Cree un archivo llamado SendRcsMessageEndpoint.cs en la raíz de su proyecto. Este archivo define la lógica del API para enviar mensajes RCS. El archivo SendRcsRequest modela el cuerpo JSON entrante, mientras que el registro SendRcsMessageEndpoint maneja la lógica para enviar el mensaje a través de la API de Messages API de Vonage. Separamos la lógica que construye la carga útil del mensaje en su propio método, BuildRcsCustomRequest. Esto mejora la legibilidad y hace que la función sea más fácil de probar o extender. Por ejemplo, podrías personalizar las sugerencias dinámicamente en el futuro.

Por ahora, este punto final se encarga de enviar mensajes RCS con 3 respuestas sugeridas codificadas para la programación de citas.

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"
                                }
                            }
                        }
                }
            }
        };
    }
}

Crear el punto final de recepción de mensajes

Cree otro archivo llamado ReceiveRcsInboundEndpoint.cs Esta clase maneja los mensajes de webhook entrantes de Vonage. Verifica la autenticidad de la solicitud mediante la validación JWT y envía una respuesta de confirmación cuando el usuario selecciona una de las respuestas sugeridas. La verificación de la firma JWT garantiza que no se procesen mensajes falsos o maliciosos y que las solicitudes entrantes provengan realmente de Vonage. Al mantener esta lógica en un método separado, el método ReceiveRcsInbound se mantiene enfocada y es más fácil de leer.

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 punto final gestiona los mensajes RCS entrantes, verifica su autenticidad y envía respuestas de confirmación.

Configurar el archivo Program.cs

Actualice su Programa.cs a lo siguiente.

Aquí configuramos la inyección de dependencias, que es una parte fundamental del diseño de ASP.NET Core. Registramos el cliente de Vonage y nuestros endpoints personalizados para que puedan inyectarse cuando sea necesario, haciendo que el código sea más 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();

Cómo exponer su servidor con ngrok

Para recibir webhooks de Vonage, tu servidor local debe ser accesible a través de Internet. Usa ngrok para exponer tu servidor ASP.NET Core, que se ejecutará en el puerto 5000:

ngrok http 5000

Tenga en cuenta la URL HTTPS proporcionada por ngrok (por ejemplo, https://your-ngrok-subdomain.ngrok.io).

Puede leer más sobre pruebas con ngrok en nuestro portal de herramientas para desarrolladores.

>> Puede que tu aplicación se esté ejecutando en un puerto diferente. Puedes comprobarlo en launchSettings.json para confirmarlo.

Crea y configura tu aplicación de Vonage

Ahora que tu aplicación ASP.NET está lista, también necesitarás crear y configurar tu aplicación de Vonage. Primero, crea tu aplicación en el Panel de Vonage. Dale un nombre a la aplicación y activa la función de mensajes.

En la configuración de tu aplicación de Vonage:

1. Establezca la URL de entrada a https://YOUR_NGROK_URL/inbound-rcs.

2. Establezca la URL de estado a https://example.com/rcs-status.
   ** Los estados de los mensajes se tratarán en un próximo artículo.

3. Genere una clave pública y privada haciendo clic en el botón. Asegúrese de mover su private.key al directorio raíz del proyecto (RcsSuggestedReplies).

4. Guarda los cambios.

A continuación, vincule su Agente RCS haciendo clic en el botón "Vincular cuentas externas" pestaña:

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

Actualiza tus credenciales de Vonage

Sustituya los valores del marcador de posición en appsettings.json con tus credenciales reales de Vonage:

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

Ejecute su aplicación y pruébela

Inicie su solicitud:

dotnet run

¡Su aplicación de mensajería RCS ya está funcionando! Puede utilizar una herramienta como Postman o cURL para enviar una solicitud POST a su archivo /send-rcs con el número de teléfono del destinatario:

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

En el dispositivo habilitado para RCS del destinatario, debería aparecer el mensaje con las respuestas sugeridas.

Cuando el destinatario selecciona una respuesta sugerida, su archivo /inbound-rcs gestionará la respuesta y se enviará un mensaje de confirmación.

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

Conclusión

Ahora has creado una aplicación ASP.NET Core funcional que puede enviar y recibir respuestas sugeridas de RCS usando la API de Messages de Vonage. Esta simple mejora de la interfaz de usuario, que permite a los usuarios tocar una respuesta en lugar de escribirla, puede mejorar drásticamente la forma en que los usuarios interactúan con tu aplicación.

Con la verificación webhook, la gestión de respuestas estructuradas y los mensajes de confirmación, esta plantilla te ofrece una base sólida sobre la que expandirte. Intenta añadir RCS Cards, almacenar respuestas en una base de datos o generar dinámicamente respuestas sugeridas a partir del historial del usuario.

Si tienes alguna pregunta o alguna idea sobre lo que te gustaría construir a continuación, únete a la conversación en nuestra Slack de la comunidad de Vonage o comunícate en X (antes Twitter). ¡Nos encantaría ver lo que construyes!