Messages API-Integration

Sie können die Messages API in das Vonage Client SDK integrieren, damit eingehende Nachrichten an die Messages API an eine Konversation gesendet und ausgehende Nachrichten über die Messages API zurückgesendet werden können.

Um fortzufahren, sollten Sie bereits damit vertraut sein:

• Eingehende Nachrichten empfangen mit der Messages API
• Konversationen
• Benutzer
• Konversation Mitglieder
• Senden von Nachrichtenereignissen mit dem Vonage Client SDK

Wie es funktioniert

Beim Umgang mit der Messages API sind die eingehenden und ausgehenden Fälle zu berücksichtigen.

Eingehende Nachrichten

Wenn Sie eine eingehende Nachricht an Ihre Inbound-Webhook-URL der Messages API erhalten, antworten Sie mit einem JSON-Objekt, das die Messages API anweist, diese Nachricht an die Conversation API weiterzuleiten, mit einigen Informationen darüber, an welche Conversation die eingehende Nachricht weitergeleitet werden soll.

Nachfolgend finden Sie ein Beispiel mit JavaScript und Express.JS:

app.post('/message/inbound', (req, res) => {
  const username = `+${req.body.from}`;
  const conversationName = 'my_conversation';
  const region = 'eu-3';

  console.log(username, conversationName, region);

  res.json([{
    action: 'message',
    conversation_name: conversationName,
    user: username,
    region: region,
  }]);
});

Diese Route wird bei jeder eingehenden Nachricht an die Vonage-Applikation aufgerufen. Bei SMS wird dies durch eine SMS ausgelöst, die an eine mit Ihrer Vonage-Applikation verknüpfte virtuelle Nummer gesendet wird, aber der Prozess ist für die anderen von der Messages API angebotenen Kanäle derselbe. Die Antwort ist ein JSON-Objekt, das ähnlich wie die Control-Objekte aufrufen die für Voice verwendet wird und der Conversation API Informationen darüber liefert, wie diese Nachricht zu behandeln ist. Die Conversation API erledigt einige Dinge automatisch für Sie mit dieser Antwort:

1. Es wird eine Konversation mit dem Namen gesucht, der im Feld conversation_name Eigenschaft, in der Region, die in der region Eigenschaft. Wenn sie nicht vorhanden ist, wird sie in der angegebenen Region erstellt.

2. Es wird ein Benutzer mit dem Namen gesucht, der im Feld user Eigenschaft, in der Region, die in der region Eigenschaft. Wenn sie nicht vorhanden ist, wird sie in der angegebenen Region erstellt.

3. Wenn es sich um einen neuen Benutzer oder einen neuen Teilnehmer an der angegebenen Konversation handelt, wird der Benutzer als Mitglied der Konversation hinzugefügt. Dann wird in der Konversation ein Nachrichtenereignis mit dem Textkörper der ursprünglichen eingehenden Nachricht erstellt, die an den Webhook gesendet wurde.

Wie Sie sehen können, ist die Region wichtig, um sicherzustellen, dass eingehende Nachrichten von der Messages API an die richtige Conversation weitergeleitet werden. Die Regionen sind die gleichen, die in der Voice API und Client SDK Konfiguration verwendet werden. In einer Produktionsumgebung müssen Sie wahrscheinlich einen Weg finden, den Webhook für eingehende Nachrichten zu disambiguieren, um sicherzustellen, dass er an die richtige Konversation weitergeleitet wird. Dies könnte wie eine Zuordnung von einer Telefonnummer zu einer bestimmten Konversation aussehen, oder Sie können den Absender bitten, eine Art vorhersehbaren Text in die Nachricht einzufügen, um zu kontrollieren, an welche Konversation die Nachricht geht:

Conv1: Hello World!
Conv2: Hello Vonage!

Sie können die Zeichenkette aufteilen : und verwenden Sie das erste Element, z. B. Conv1 als Name der Konversation.

Ausgehende Nachrichten

Ausgehende Nachrichten (neue Konversationsnachrichtenereignisse) werden von der Konversations-API automatisch über denselben Kanal zurückgesendet, über den die eingehende Nachricht empfangen wurde. Wenn ein Benutzer zu einer Konversation hinzugefügt wird, wird dadurch ein Mitglied erstellt. Die Mitgliedschaft kann als Bindung eines Benutzers an eine Konversation über einen Kanal betrachtet werden. Zusätzlich zu den Kanälen, die die Conversation API unterstützt, kann die Messages API-Kanäle werden für die Nachrichtenübermittlung unterstützt.

Wenn eine eingehende Messages API-Nachricht an die Conversation API weitergeleitet wird, wird ein Mitglied in der angegebenen Conversation mit dem Kanal erstellt, in dem die eingehende Nachricht empfangen wurde. Wenn zum Beispiel das obige Webhook-Codefragment als Antwort auf eine eingehende SMS-Nachricht mit dem Vonage Server SDK verwendet wurde, können Sie das Member-Objekt abrufen:

const member = await vonage.conversations.getMember(
    'my_conversation_id',
    'sms_member_id'
    );

Das würde das Objekt ergeben:

{
  "id": "MEM-644630b7-1ba6-4c71-9fae-834316f1d1d5",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "sms",
    "from": {
      "number": "447441446999"
    },
    "to": {
      "number": "441234567890"
    }
  },
  ...
}

Wie Sie sehen können, ist die channel Objekt enthält erwartungsgemäß den Typ der SMS, wobei die from.number ist die virtuelle Telefonnummer, die mit meiner Vonage-Applikation verknüpft ist, und die to.number ist die Nummer, die die SMS gesendet hat. Vergleichen Sie dies mit einem anderen In-App Member-Objekt aus dem Client SDK:

{
  "id": "MEM-f5fa689b-8a3f-43f3-87fd-5af0d3e35221",
  "conversationId": "CON-0f9af192-d916-4365-b0cb-1b7e3c53576c",
  "channel": {
    "type": "app"
  },
  ...
}

Wenn ein neues Nachrichtenereignis an die Conversation gesendet wird, schaut die Conversation API in der channel für das Mitglied und übermitteln dort das Nachrichtenereignis. Für das erste Mitglied wird also eine SMS über die Messages API an die folgende Adresse gesendet to.number aus dem virtuellen from.number und für das zweite Mitglied wird es per In-App Messaging zugestellt.

Erstellen von Messages API-Benutzern und -Mitgliedern

Wie oben gezeigt, kann die Conversation API automatisch einen Benutzer und ein Mitglied für Sie erstellen. Wenn Sie dies jedoch selbst tun möchten, können Sie das Vonage Server SDK oder die Conversation API direkt verwenden:

const number = 'sms_sender_number';
const vonageNumber = "my_vonage_number";
const conversationId = 'my_conversation_id';

const formattedNumber = `+${number}`
const user = await vonage.users.createUser({
    name: formattedNumber,
    displayName: formattedNumber,
    channels: {
        sms: [{
            number: number
        }]
    }
});

const member = await vonage.conversations.createMember(
    conversationId,
    {
        state: 'joined',
        user: {
            name: user.name
        },
        channel: {
            type: 'sms',
            from: {
                number: vonageNumber
            },
            to: {
                number: number
            }
        }
    }
);


console.log(member);

Dadurch wird zunächst ein Benutzer mit einem SMS-Kanal erstellt, der die Telefonnummer enthält, die der Benutzer zum Senden einer SMS verwenden wird. Dann wird dieser Benutzer als Mitglied der Konversation mit einem SMS-Kanal wie oben beschrieben hinzugefügt. Die Kanäle des Benutzers werden mit den bei der Erstellung eines Mitglieds angegebenen Kanälen abgeglichen.