Senden und Empfangen von RCS-Vorschlagsantworten mit ASP.NET Core und Vonage

Rich Communication Services (RCS) sind die Weiterentwicklung von SMS: Sie bringen markenbezogene, interaktive und appähnliche Erlebnisse in Ihre native Messaging-App. Mit Nachrichten-API von Vonagekönnen Sie RCS-Nachrichten mit Vorgeschlagene Antwortenliefern: anklickbare Optionen, die das Engagement verbessern und die Bearbeitung von Antworten rationalisieren.

In diesem Tutorial werden Sie eine ASP.NET Core Web API von Grund auf neu erstellen, die das .NET SDK von Vonage verwendet, um RCS-Antwortvorschläge zu senden und zu empfangen. Sie werden auch lernen, wie Sie die Anwendung konfigurieren, sichere Webhooks einrichten und den End-to-End-Flow mit ngrok und Ihrem RCS-fähigen Telefon testen.

>> TL;DR: Sehen Sie sich den vollständigen Arbeits Code auf GitHub

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

Voraussetzungen

Bevor wir anfangen, stellen Sie sicher, dass Sie alles haben:

• .NET 9.0 SDK

• Visual Studio 2022+ oder VS Code

• ngrok für lokalen Tunnelbau

• Ein Vonage API-Konto und ein registrierter RBM-Agent. (Siehe unten)

• Ein RCS-fähiges Gerät für Tests

Vonage API-Konto

Um dieses Tutorial durchzuführen, benötigen Sie ein Vonage API-Konto. Wenn Sie noch keines haben, können Sie sich noch heute anmelden und mit einem kostenlosen Guthaben beginnen. Sobald Sie ein Konto haben, finden Sie Ihren API-Schlüssel und Ihr API-Geheimnis oben auf dem Vonage-API-Dashboard.

Sind Sie bereit, mit dem Bau zu beginnen?

Erleben Sie nahtlose Konnektivität, Echtzeit-Messaging und kristallklare Sprach- und Videoanrufe - alles auf Knopfdruck.

So kontaktieren Sie Ihren Vonage Account Manager

Um RCS-Funktionen in Ihrer Vonage-Anwendung senden und empfangen zu können, benötigen Sie einen registrierten Rich Business Messaging (RBM)-Agenten und ein Telefon mit RCS-Funktionen.

Derzeit ist RCS Messaging über Vonage nur für verwaltete Konten verfügbar. Sie müssen Ihren Kundenbetreuer kontaktieren, um die Aktivierung des Entwicklermodus für Ihren RBM-Agenten zu beantragen. Der Entwicklermodus ermöglicht es Ihnen, RCS Messaging an zugelassene Nummern zu testen, bevor Sie den Prozess der Agentenverifizierung abschließen und in die Produktion einsteigen.

Bitte kontaktieren Sie unser Verkaufsteam wenn Sie noch kein verwaltetes Konto haben.

>> Verstehen Sie den Unterschied zwischen RCS und RBM.

Erstellen Sie das ASP.NET Core-Projekt

Wir beginnen mit der Erstellung einer minimalen ASP.NET Core-Web-API unter Verwendung der integrierten CLI-Vorlage.

dotnet new web -n RcsSuggestedReplies
cd RcsSuggestedReplies

Erforderliche NuGet-Pakete hinzufügen

Installieren Sie die erforderlichen Abhängigkeiten:

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

• Vonage: So verwenden Sie die Nachrichten-API

• Newtonsoft.Json: JSON-Verarbeitung für API-Anfragen und -Antworten

• OpenApi: Unterstützung der OpenAPI-Spezifikation für Ihre Endpunkte

• Swashbuckle: Swagger UI zum Testen Ihrer API im Browser

Erstellen einer Konfigurationsklasse

erstellen. BenutzerdefinierteKonfiguration.cs im Stammverzeichnis Ihres Projekts und fügen Sie hinzu:

namespace RcsSuggestedReplies;

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

Diese Klasse verwendet C#s Datensatz Typ, um ein einfaches, unveränderliches Konfigurationsobjekt zu definieren. Sie ermöglicht es Ihnen, stark typisierte Einstellungen aus appsettings.jsonzu binden, was Ihren Code sauberer und weniger fehleranfällig macht als die Verwendung von rohen Strings überall.

Anwendungseinstellungen konfigurieren

Erstellen oder aktualisieren Sie Ihre appsettings.json Datei:

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

Ihre appsettings.json speichert Laufzeitkonfigurationen wie Anmeldeinformationen, Absender-ID und Protokollebenen. Die Speicherung sensibler Einstellungen wie dieser in einer Konfigurationsdatei ermöglicht die Trennung von Code und umgebungsspezifischen Werten.

Aktualisieren Sie diese Variablen, nachdem Sie die "Erstellen und Konfigurieren Ihrer Vonage-Anwendung" unten abgeschlossen haben.

Erstellen Sie den Endpunkt Nachricht senden

Erstellen Sie eine Datei namens SendRcsMessageEndpoint.cs im Stammverzeichnis Ihres Projekts. Diese Datei definiert die API-Logik für das Senden von RCS-Nachrichten. Die Datei SendRcsRequest Datensatz modelliert den eingehenden JSON-Körper, während der SendRcsMessageEndpoint die Logik für den Versand der Nachricht über die Vonage Messages API behandelt. Wir trennen die Logik, die die Nutzlast der Nachricht erstellt, in eine eigene Methode, BuildRcsCustomRequest. Dadurch wird die Lesbarkeit verbessert und die Funktion lässt sich leichter testen oder erweitern. So können Sie beispielsweise die Vorschläge in Zukunft dynamisch anpassen.

Im Moment übernimmt dieser Endpunkt das Senden von RCS-Nachrichten mit 3 fest einprogrammierten Antwortvorschlägen für die Terminplanung.

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

Erstellen Sie den Endpunkt für den Nachrichtenempfang

Erstellen Sie eine weitere Datei namens ReceiveRcsInboundEndpoint.cs Diese Klasse verarbeitet eingehende Webhook-Nachrichten von Vonage. Sie prüft die Authentizität der Anfrage mithilfe der JWT-Validierung und sendet eine Bestätigungsantwort, wenn der Benutzer eine der vorgeschlagenen Antworten auswählt. Die Überprüfung der JWT-Signatur stellt sicher, dass keine gefälschten oder böswilligen Nachrichten verarbeitet werden und dass die eingehenden Anfragen tatsächlich von Vonage stammen.Nach dem Parsen der Benutzerantwort senden wir eine freundliche Bestätigungsnachricht. Durch die Auslagerung dieser Logik in eine separate Methode bleibt die ReceiveRcsInbound Funktion fokussiert und ist leichter zu lesen.

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

Dieser Endpunkt verarbeitet eingehende RCS-Nachrichten, prüft ihre Authentizität und sendet Bestätigungsantworten.

Konfigurieren Sie die Datei Program.cs

Aktualisieren Sie Ihre Programm.cs Datei wie folgt.

Hier konfigurieren wir die Injektion von Abhängigkeiten, die ein zentraler Bestandteil des Designs von ASP.NET Core ist. Wir registrieren den Vonage-Client und unsere benutzerdefinierten Endpunkte, damit sie bei Bedarf injiziert werden können und der Code modularer wird.

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

Wie Sie Ihren Server mit ngrok freilegen

Um Webhooks von Vonage zu empfangen, muss Ihr lokaler Server über das Internet erreichbar sein. Verwenden Sie ngrok, um Ihren ASP.NET Core-Server freizugeben, der an Port 5000 ausgeführt wird:

ngrok http 5000

Beachten Sie die von ngrok bereitgestellte HTTPS-URL (z. B. https://your-ngrok-subdomain.ngrok.io).

Sie können mehr lesen über Testen mit ngrok in unserem Entwicklerportal nachlesen.

>> Ihre Anwendung läuft möglicherweise auf einem anderen Port. Sie können dies in launchSettings.json überprüfen.

Erstellen und Konfigurieren Ihrer Vonage-Anwendung

Jetzt, da Ihre ASP.NET-Anwendung fertig ist, müssen Sie auch Ihre Vonage-Anwendung erstellen und einrichten. Erstellen Sie zunächst Ihre Anwendung im Vonage Dashboard. Geben Sie der App einen Namen und schalten Sie die Nachrichtenfunktion ein.

In den Einstellungen Ihrer Vonage-Anwendung:

1. Setzen Sie die Eingehende URL auf https://YOUR_NGROK_URL/inbound-rcs.

2. Setzen Sie die Status-URL auf https://example.com/rcs-status.
   ** Der Status von Nachrichten wird in einem späteren Artikel behandelt.

3. Erzeugen Sie einen öffentlichen und einen privaten Schlüssel, indem Sie auf die Schaltfläche klicken. Stellen Sie sicher, dass Sie Ihren private.key Datei in das Stammverzeichnis des Projekts (RcsSuggestedReplies).

4. Speichern Sie die Änderungen.

Verknüpfen Sie dann Ihren RCS-Agenten, indem Sie auf die Schaltfläche "Externe Konten verknüpfen" Registerkarte:

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

Aktualisieren Sie Ihre Vonage-Anmeldeinformationen

Ersetzen Sie die Platzhalterwerte in appsettings.json durch Ihre tatsächlichen Vonage-Anmeldedaten:

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

Anwendung ausführen und testen

Starten Sie Ihre Bewerbung:

dotnet run

Ihre RCS-Messaging-Anwendung läuft jetzt! Sie können ein Tool wie Postman oder cURL verwenden, um eine POST-Anfrage an Ihre /send-rcs Endpunkt mit der Telefonnummer des Empfängers senden:

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

Auf dem RCS-fähigen Gerät des Empfängers sollte die Nachricht mit Antwortvorschlägen erscheinen.

Wenn der Empfänger einen Antwortvorschlag auswählt, wird Ihr /inbound-rcs Endpunkt die Antwort, und es wird eine Bestätigungsnachricht zurückgeschickt.

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

Schlussfolgerung

Sie haben nun eine funktionierende ASP.NET Core-Anwendung erstellt, die RCS Suggested Replies über die Vonage Messages API senden und empfangen kann. Diese einfache UI-Verbesserung, mit der Benutzer eine Antwort antippen können, anstatt sie zu tippen, kann die Interaktion der Benutzer mit Ihrer Anwendung erheblich verbessern.

Mit Webhook-Verifizierung, strukturierter Antwortbehandlung und Bestätigungsnachrichten bietet diese Vorlage eine solide Grundlage, auf der Sie aufbauen können. Versuchen Sie, RCS-Karten hinzuzufügen, Antworten in einer Datenbank zu speichern oder dynamisch vorgeschlagene Antworten aus dem Benutzerverlauf zu generieren.

Wenn Sie Fragen haben oder Ideen, was Sie als Nächstes bauen möchten, nehmen Sie an der Diskussion in unserer Vonage Community Slack oder kontaktieren Sie uns aufX (früher Twitter). Wir würden uns freuen, zu sehen, was Sie bauen!