Envoyer et recevoir des réponses suggérées RCS avec ASP.NET Core et Vonage

Les services de communication riches (RCS) représentent l'évolution des SMS : ils apportent des expériences de marque, interactives et semblables à celles d'une application dans votre application de messagerie native. Avec l'API Messages API de Vonagede Vonage, vous pouvez envoyer des messages RCS avec Réponses suggéréesdes options cliquables qui améliorent l'engagement et rationalisent le traitement des réponses.

Dans ce tutoriel, vous construirez une API Web ASP.NET Core à partir de zéro qui utilise le SDK .NET de Vonage de Vonage pour envoyer et recevoir des messages de réponse suggérés par RCS. Vous apprendrez également à configurer l'application, à mettre en place des webhooks sécurisés et à tester le flux de bout en bout à l'aide de ngrok et de votre téléphone compatible RCS.

>> TL;DR : Voir le code de travail complet sur GitHub

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

Conditions préalables

Avant de commencer, assurez-vous que vous avez.. :

• .NET 9.0 SDK

• Visual Studio 2022+ ou VS Code

• ngrok pour le tunneling local

• Un compte API de Vonage et un agent RBM enregistré. RBM enregistré. (Voir ci-dessous)

• Un appareil compatible avec le RCS pour les essais

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.

Comment contacter votre Account Manager de Vonage

Afin d'envoyer et de recevoir des capacités RCS dans votre application Vonage, vous devez avoir un agent RBM (Rich Business Messaging) enregistré. Rich Business Messaging (RBM) enregistré.

Actuellement, la messagerie RCS via Vonage n'est disponible que pour les comptes gérés. Vous devrez contacter votre Account Manager pour demander l'activation du mode développeur pour votre agent RBM. Le mode développeur vous permet de tester la messagerie RCS vers des numéros inscrits sur la liste d'autorisation avant de terminer le processus de vérification de l'agent et de lancer en production.

Veuillez contacter contacter notre équipe de vente si vous n'avez pas de compte géré.

>> Comprendre la différence la différence entre RCS et RBM.

Créer le projet ASP.NET Core

Nous commencerons par générer une API Web ASP.NET Core minimale à l'aide du modèle CLI intégré.

dotnet new web -n RcsSuggestedReplies
cd RcsSuggestedReplies

Ajouter les paquets NuGet requis

Installer les dépendances nécessaires :

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

• Vonage: Pour utiliser l'API Messages

• Newtonsoft.Json: Gestion JSON pour les requêtes et les réponses de l'API

• OpenApi : Support de la spécification OpenAPI pour vos points d'extrémité

• Casse-cou: Swagger UI pour tester votre API dans le navigateur

Créer une classe de configuration

Créer CustomConfiguration.cs à la racine de votre projet et ajoutez-y

namespace RcsSuggestedReplies;

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

Cette classe utilise la fonction record de C# pour définir un objet de configuration simple et immuable. Elle vous permet de lier des paramètres fortement typés à partir de appsettings.jsonce qui rend votre code plus propre et moins sujet aux erreurs que l'utilisation de chaînes de caractères brutes partout.

Configuration des paramètres de l'application

Créez ou mettez à jour votre fichier appsettings.json de l'application :

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

votre appsettings.json stocke la configuration d'exécution telle que les informations d'identification, l'ID de l'expéditeur et les niveaux de journalisation. Le fait de conserver des paramètres sensibles comme ceux-ci dans un fichier de configuration permet de séparer le code des valeurs spécifiques à l'environnement.

Mettez à jour ces variables une fois que vous avez terminé le processus de création et de configuration de votre application Vonage. "Créer et configurer votre application Vonage". ci-dessous.

Créer le point de terminaison d'envoi de message

Créer un fichier nommé SendRcsMessageEndpoint.cs à la racine de votre projet. Ce fichier définit la logique de l'API pour l'envoi de messages RCS. Le fichier SendRcsRequest modélise le corps JSON entrant, tandis que l'enregistrement SendRcsMessageEndpoint gère la logique d'envoi du message via l'API Messages de Vonage. Nous séparons la logique qui construit la charge utile du message dans sa propre méthode, BuildRcsCustomRequest. Cela améliore la lisibilité et rend la fonction plus facile à tester ou à étendre. Par exemple, vous pourriez personnaliser les suggestions de manière dynamique à l'avenir.

Pour l'instant, ce point d'accès permet d'envoyer des messages RCS avec 3 suggestions de réponses codées en dur pour la prise de rendez-vous.

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

Créer le point de terminaison de réception des messages

Créer un autre fichier appelé ReceiveRcsInboundEndpoint.cs à la racine de votre projet. Cette classe gère les messages Webhook entrants provenant de Vonage. Elle vérifie l'authenticité de la demande à l'aide de la validation JWT et envoie une réponse de confirmation lorsque l'utilisateur sélectionne l'une des réponses proposées. La vérification de la signature JWT garantit que vous ne traitez pas de messages usurpés ou malveillants, et que les demandes entrantes proviennent bien de Vonage.Après avoir analysé la réponse de l'utilisateur, nous envoyons un message de confirmation amical. Le fait de conserver cette logique dans une méthode distincte permet à la méthode ReceiveRcsInbound reste ciblée et plus facile à lire.

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

Ce point d'accès traite les messages RCS entrants, vérifie leur authenticité et envoie des réponses de confirmation.

Configuration du fichier Program.cs

Mettez à jour votre Programme.cs comme suit.

Ici, nous configurons l'injection de dépendances, qui est un élément essentiel de la conception d'ASP.NET Core. Nous enregistrons le client Vonage et nos points de terminaison personnalisés afin qu'ils puissent être injectés là où c'est nécessaire, ce qui rend le code plus modulaire.

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();

Comment exposer votre serveur avec ngrok

Pour recevoir des webhooks de Vonage, votre serveur local doit être accessible sur Internet. Utilisez ngrok pour exposer votre serveur ASP.NET Core, qui fonctionnera sur le port 5000 :

ngrok http 5000

Notez l'URL HTTPS fournie par ngrok (par exemple, https://your-ngrok-subdomain.ngrok.io).

Vous pouvez en savoir plus sur les tests avec ngrok dans notre portail d'outils pour les développeurs.

>> Votre application s'exécute peut-être sur un port différent. Vous pouvez vérifier dans launchSettings.json pour confirmer.

Créer et configurer votre application Vonage

Maintenant que votre application ASP.NET est prête, vous devez également créer et configurer votre application Vonage. Tout d'abord, créez votre application dans le tableau de bord de Vonage. Donnez-lui un nom et activez la fonction Messages.

Dans les paramètres de votre application Vonage :

1. Définir l URL entrante entrante https://YOUR_NGROK_URL/inbound-rcs.

2. Définir l URL d'état de l'état à https://example.com/rcs-status.
   ** Les statuts des messages seront abordés dans un prochain article.

3. Générez une clé publique et une clé privée en cliquant sur le bouton. Veillez à déplacer votre clé.privée dans le répertoire racine du projet (RcsSuggestedReplies).

4. Enregistrez les modifications.

Reliez ensuite votre agent RCS en cliquant sur le bouton "Lier des Account externes" l'onglet "Lier des comptes externes" :

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

Mettez à jour vos informations d'identification Vonage

Remplacer les valeurs de remplacement dans appsettings.json par vos identifiants Vonage réels :

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

Exécutez votre application et testez-la

Commencez votre application :

dotnet run

Votre application de messagerie RCS fonctionne maintenant ! Vous pouvez utiliser un outil comme Postman ou cURL pour envoyer une requête POST à votre fichier /send-rcs avec le numéro de téléphone du destinataire :

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

Sur l'appareil compatible RCS du destinataire, le message avec les réponses suggérées devrait s'afficher.

Lorsque le destinataire sélectionne une réponse suggérée, votre fichier /inbound-rcs traitera la réponse et un message de confirmation sera envoyé en retour.

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

Conclusion

Vous avez maintenant construit une application ASP.NET Core fonctionnelle qui peut envoyer et recevoir des réponses suggérées RCS à l'aide de l'API Messages de Vonage. Cette simple amélioration de l'interface utilisateur, qui permet aux utilisateurs de taper une réponse au lieu de la taper, peut améliorer considérablement la façon dont les utilisateurs interagissent avec votre application.

Avec la vérification des webhooks, la gestion des réponses structurées et les messages de confirmation, ce modèle vous donne une base solide sur laquelle vous pouvez vous développer. Vous pouvez essayer d'ajouter des cartes RCS, de stocker les réponses dans une base de données ou de générer dynamiquement des suggestions de réponses à partir de l'historique de l'utilisateur.

Si vous avez des questions ou des idées sur ce que vous aimeriez construire ensuite, venez rejoindre la conversation dans notre Communauté Vonage Slack ou contactez-nous sur X (anciennement Twitter). Nous serions ravis de voir ce que vous construisez !