Konversation

Eine Konversation ist eine gemeinsame Kernkomponente, auf die sich Vonage-APIs stützen. Konversationen laufen über mehrere Medien (Text, Sprache) und können mit folgenden Elementen verbunden sein Benutzer über Mitglied Objekte.

Das Conversation-Objekt ist der Schlüssel zum Verständnis der Conversation API. Damit Benutzer kommunizieren können, müssen sie eine Verbindung zu einer Konversation herstellen, woraufhin ein zugehöriges Mitgliedsobjekt in dieser Konversation erstellt wird.

Eine Konversation kann Textnachrichten oder Audioanrufe unterstützen. Für Textnachrichten kann man sich eine Konversation wie einen Chatroom vorstellen. Benutzer können eingeladen werden, einer Konversation beizutreten, und sie können eine Konversation verlassen. Ein einzelner Benutzer kann auch mehreren Konversationen über mehrere Mitgliedsobjekte beitreten.

Im Verlauf einer Konversation sendet Vonage verschiedene Veranstaltungen. Bei diesen Ereignissen kann es sich um Kommunikationsereignisse wie Nachrichten und Sprachströme oder andere Ereignisse wie hinzugefügte oder entfernte Benutzer, Tippanzeigen usw. handeln. Die Absicht ist, dass diese Ereignisse so behandelt werden, wie sie auftreten, obwohl ein Protokoll der Ereignisse von Vonage aufgezeichnet wird, das später durchsucht werden kann.

Es kann keine Kommunikation außerhalb des Kontextes eines Gesprächs geben.

Eine Konversation kann für eine einzelne, zeitlich begrenzte Kommunikationsinteraktion mit einem Anfang und einem Ende verwendet werden, z. B. einen Anruf. Alternativ kann sie als permanenter Container für den gesamten Verlauf aller damit verbundenen Interaktionen verwendet werden.

Ein Beispiel Gespräch

Product deprecation notice

Effective April 30th, 2026, the messaging functionality of the Vonage Conversation API will be discontinued. Access for new users will be closed, and messaging capabilities will no longer be available to existing users after this date.

The voice functionality of the Conversation API will remain available and is not impacted by this change. If you have any questions regarding this partial discontinuation, please contact your account manager or our support team.

Betrachten Sie das folgende Beispiel. Ein Benutzer ruft eine Vonage Number an, die mit einer Vonage Application verbunden ist. Die Anwendung leitet den Anruf an ein zweites Telefon weiter. Dies wird im folgenden Diagramm dargestellt:

Conversation example

Gesprächsdetails

Der Anruf besteht aus zwei Abschnitten: eingehend und ausgehend, und zwei Mitgliedern, die alle in einem Gesprächsobjekt enthalten sind. Wenn Sie den Aufruf der Conversation API verwendet haben Konversation erhalten um Einzelheiten zu diesem Gespräch zu erfahren, würden Sie eine Antwort ähnlich der folgenden erhalten:

{
    "id": "CON-bc643220-2542-499a-892e-c982c4150c06",
    "name": "NAM-1b2c4274-e3f2-494e-89c4-46856ee84a8b",
    "timestamp": {
        "created": "2018-10-25T09:26:18.999Z"
    },
    "sequence_number": 8,
    "numbers": {},
    "properties": {
        "ttl": 172800,
        "video": false
    },
    "members": [
        {
            "member_id": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
            "user_id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
            "name": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6",
            "state": "JOINED",
            "timestamp": {
                "joined": "2018-10-25T09:26:30.334Z"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "initiator": {
                "joined": {
                    "isSystem": true
                }
            }
        },
        {
            "member_id": "MEM-25ccda92-839d-4ac6-a7b2-de310224878b",
            "user_id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
            "name": "vapi-user-f59c1ff26c0543fdb6c02fd30617a1c0",
            "state": "JOINED",
            "timestamp": {
                "invited": "2018-10-25T09:26:19.385Z",
                "joined": "2018-10-25T09:26:30.270Z"
            },
            "invited_by": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b",
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000001",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "initiator": {
                "invited": {
                    "isSystem": true
                }
            }
        }
    ],
    "_links": {
        "self": {
            "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06"
        }
    }
}

In der obigen Antwort sind die Telefonnummern wie folgt:

Numbers Beschreibung
447700000001 Telefon für eingehende Anrufe (Alice)
447700000002 Vonage Numbers, die mit der Vonage Anwendung verknüpft sind
447700000003 Das Zieltelefon (Bob)

Wenn Sie sich die Antwort genau ansehen, können Sie Folgendes feststellen:

  • Es gibt eine Konversation, die durch die ID des Formulars CON-<uuid>.
  • Diese Konversation hat zwei Mitglieder - eines für jeden Benutzer.
  • Beide Mitglieder sind JOINED in die Konversation einbringen.
  • Jedes Mitglied hat einen Kanal, der den Typ phone.
  • Jeder Kanal hat eine ID.
  • Jedem Kanal ist ein anderes Bein zugeordnet.
  • Jedes Bein hat eine eindeutige ID.

Dies wird in der folgenden Abbildung veranschaulicht:

Conversation detail

Zusammenfassend lässt sich sagen, dass es in diesem Beispiel einen Anruf und eine Konversation gibt, die aus zwei Zweigen (eingehend und ausgehend) besteht. Jeder an dem Anruf beteiligte Benutzer wird in die Konversation aufgenommen, indem er ein Mitglied dieser Konversation wird.

Veranstaltungen

Wenn Sie während eines laufenden Gesprächs Ereignisse für die Konversation über die Funktion Ereignisse auflisten API-Aufruf werden die Ereignisse angezeigt, die bisher während des Anrufs stattgefunden haben:

[
    {
        "id": 1,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "timestamp": {
                "joined": "2018-10-25T09:26:19.204Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:19.207Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/1"
    },
    {
        "id": 2,
        "type": "sip:ringing",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:24.384Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/2"
    },
    {
        "id": 3,
        "type": "sip:answered",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "direction": "outbound"
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.277Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/3"
    },
    {
        "id": 4,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-b9948493-be4a-4b36-bb4d-c96bcc2af85b"
            },
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            },
            "timestamp": {
                "invited": "2018-10-25T09:26:19.385Z",
                "joined": "2018-10-25T09:26:30.270Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.273Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/4"
    },
    {
        "id": 5,
        "type": "member:media",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "audio": true,
            "media": {
                "audio": true,
                "audio_settings": {
                    "enabled": true,
                    "earmuffed": false,
                    "muted": false
                }
            },
            "channel": {
                "type": "phone",
                "id": "30cecc87-7ac9-4d03-910a-e9d69558263c",
                "from": {
                    "number": "Unknown",
                    "type": "phone"
                },
                "leg_ids": [
                    "30cecc87-7ac9-4d03-910a-e9d69558263c"
                ],
                "to": {
                    "number": "447700000003",
                    "type": "phone"
                },
                "cpa": false,
                "preanswer": false,
                "ring_timeout": 60000,
                "cpa_time": 5000,
                "max_length": 7200000
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.274Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/5"
    },
    {
        "id": 6,
        "type": "sip:answered",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "direction": "inbound"
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.340Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/6"
    },
    {
        "id": 7,
        "type": "member:joined",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "user": {
                "id": "USR-33a51f4d-d06b-42f6-a525-90d2859ab9f6"
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            },
            "timestamp": {
                "joined": "2018-10-25T09:26:30.334Z"
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.337Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/7"
    },
    {
        "id": 8,
        "type": "member:media",
        "from": "MEM-f44c872e-cba9-444f-88ae-0bfa630865a6",
        "to": "",
        "body": {
            "audio": true,
            "media": {
                "audio": true,
                "audio_settings": {
                    "enabled": true,
                    "earmuffed": false,
                    "muted": false
                }
            },
            "channel": {
                "type": "phone",
                "id": "797168e24c19a3c45e74e05b10fef2b5",
                "from": {
                    "type": "phone",
                    "number": "447700000001"
                },
                "to": {
                    "type": "phone",
                    "number": "447700000002"
                },
                "leg_ids": [
                    "797168e24c19a3c45e74e05b10fef2b5"
                ]
            }
        },
        "state": "",
        "timestamp": "2018-10-25T09:26:30.337Z",
        "href": "https://api.nexmo.com/v0.3/conversations/CON-bc643220-2542-499a-892e-c982c4150c06/events/8"
    }
]

Die Ereignisse, die während dieser vorübergehenden Konversation aufgetreten sind, sind wie folgt:

Ereignis-ID Mitglieds-ID Art der Veranstaltung Beschreibung
1 MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 member:joined Alice zu Vonage Numbers
2 MEM-25ccda92-839d-4ac6-a7b2-de310224878b sip:ringing Vonage an Bob
3 MEM-25ccda92-839d-4ac6-a7b2-de310224878b sip:answered Bob antwortete
4 MEM-25ccda92-839d-4ac6-a7b2-de310224878b member:joined Bob hat sich der Konversation angeschlossen
5 MEM-25ccda92-839d-4ac6-a7b2-de310224878b member:media Bob Audio-Einrichtung
6 MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 member:answered Alice antwortet
7 MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 member:joined Alice nimmt an der Konversation teil
8 MEM-f44c872e-cba9-444f-88ae-0bfa630865a6 member:media Alice Audio-Einrichtung

HINWEIS: Jedes Ereignis hat eine Ereignis-ID.

Da es sich um eine vorübergehende Konversation (Anruf) handelt, ist die Konversation nach Beendigung des Anrufs nicht mehr verfügbar, sofern nicht anders angegeben. Eine Konversation kann z. B. durch die Angabe der Option "Dauerhaft" dauerhaft gemacht werden. conversation Aktion in einer NCCO, die den Anruf steuert. Sie können das Beendigungsereignis sehen, wenn Sie die Aktivität auf dem Ereignis-Webhook für Ihre Anwendung betrachten, zum Beispiel auf https://www.example.com:9000/webhooks/event würden Sie eine Reihe von Ereignissen wie die folgenden sehen:

Zeitstempel Richtung (Bein) Von An Ereignistyp (Status) Anmerkungen
2018-10-25T09:26:18.991Z Eingehend 447700000001 447700000002 started Anrufe Vonage-Nummer
2018-10-25T09:26:18.991Z Eingehend 447700000001 447700000002 ringing Jetzt klingelt es
2018-10-25T09:26:19.827Z K.A. 447700000001 447700000002 K.A. An dieser Stelle wird der Anruf entgegengenommen
2018-10-25T09:26:24.384Z Ausgehend von Unbekannt 447700000003 started Vonage ruft auf
2018-10-25T09:26:24.384Z Ausgehend von Unbekannt 447700000003 ringing Bob läutet
2018-10-25T09:26:30.277Z Ausgehend von Unbekannt 447700000003 answered Bob antwortet
2018-10-25T09:26:30.340Z Eingehend 447700000001 447700000002 answered Alice und Bob verbunden
2018-10-25T09:31:30.179Z Eingehend 447700000001 447700000002 completed Eingehende Strecke abgeschlossen
2018-10-25T09:31:30.179Z Ausgehend von Unbekannt 447700000003 completed Ausgehende Strecke abgeschlossen

Dies zeigt, dass Bob completed und das Gespräch wurde anschließend gelöscht.

In dieser Beschreibung wurde bisher ein Sprachanruf (Medium) über Telefon (Kanal) mit zwei Legs behandelt. Die gleichen grundlegenden Konzepte gelten jedoch auch für andere Medien (Text, Sprache oder Video) und andere Kanäle (Telefon, SIP, Websocket oder App). Die Details für die verschiedenen Anruftypen wären ein wenig anders, z. B. würden Videoanrufe verschiedene Ereignistypen umfassen.