Erkennung von Voicemails (automatische Erkennung von Maschinen)
Bei der Verwendung der Vonage Voice API zur Erstellung einer abgehenden Sprachverbindung muss manchmal berücksichtigt werden, wer oder in manchen Fällen was den Anruf entgegennimmt. Vielleicht ist das zu erstellende Erlebnis nur für Menschen gedacht. In diesem Fall sollte der Anruf unterbrochen werden, wenn er von einem Voice-Mail-System entgegengenommen wird. Oder, falls ein Voice-Mail-System den Anruf entgegennimmt, könnte es notwendig sein, nach dem Signalton eine individuelle Nachricht zu hinterlassen.
Vonage bietet zwei verschiedene Funktionen für Anwendungsfälle der Maschinenerkennung:
- Standard-Maschinendetektion - bietet eine grundlegende Funktion zur Erkennung von Anrufbeantwortern mit der Option, den Anruf automatisch zu beenden oder die Anwendung nur darüber zu informieren, dass der Anruf wahrscheinlich von der Mailbox angenommen wurde. Frei von zusätzlichen Gebühren.
- Erweiterte Maschinendetektion - bietet eine genauere Erkennung und volle Flexibilität beim Aufbau eines beliebigen Anrufablaufs. Außerdem bietet es eine Signaltonerkennung und einen asynchronen Funktionsmodus, der eine bessere Anrufsteuerung ermöglicht. Advanced Machine Detection ist ein kostenpflichtiges Leistungsmerkmal; die genauen Preise finden Sie auf der Seite Voice API-Preise Seite unter 'Programmierbare Funktionen'.
Hinweis: Wenn Sie versuchen, beide Methoden in demselben Anruf zu verwenden, hat die erweiterte Maschinenerkennung Vorrang und die Standardoption wird nicht verwendet.
Rufaufbau und Maschinenerkennung
Unabhängig von der Art der verwendeten Maschinenerkennung (Standard oder erweitert) gelten dieselben Grundsätze. Wenn die Vonage Voice API angewiesen wird, einen Anruf an eine Telefonnummer zu tätigen, entweder durch eine
Ein erfolgreicher Anruf durchläuft immer die folgenden Zustände, bevor eine Maschinenerkennung erfolgt:
- Gestartet
- Klingeln
- Antwortet
Sobald der Anruf angenommen wurde, beginnt die Maschinenerkennung. Damit die Maschinenerkennung beginnen kann, muss der Anruf aufgebaut sein und Audio an Vonage fließen. Anhand der Analyse dieser Audiodaten stellt Vonage fest, ob der Anruf von einem Menschen oder einer Maschine angenommen wurde.
Vonage sendet die Ergebnisse immer an den Ereignis-Webhook in der status Feld eines Webhook vom Typ Mensch/Maschine.
Vor diesem Hintergrund wollen wir zunächst die Abfolge der Ereignisse bei der Erkennung und Verarbeitung von Anrufen erörtern, bevor wir uns mit der Verwendung der einzelnen Arten der Maschinenerkennung befassen.
Synchrone und asynchrone Implementierungen
Bei der Anrufverarbeitung und den NCCO-Aktionen gibt es zwei Möglichkeiten der Implementierung: synchron und asynchron.
Im synchronen Modus werden alle Aktivitäten im Zusammenhang mit der Maschinenerkennung durchgeführt, und erst danach beginnt Vonage mit der Verarbeitung der NCCO-Anweisungen.
Das bedeutet, dass nach der Beantwortung eines Anrufs nacheinander Folgendes geschieht:
- Beantwortetes Ereignis
- Ereignis(e) Mensch/Maschine (ggf. einschließlich Signalton)
- Erste NCCO-Instruktion verarbeiten
- (fakultativ) Veranstaltungen im Zusammenhang mit dem NCCO-Unterricht (falls zutreffend)
- Weitere NCCO-Anweisungen
Die Identifizierung des anderen Teilnehmers als Maschine oder Mensch dauert bis zu 4-5 Sekunden, so dass die Vonage-Seite des Anrufs schweigt, bis die Identifizierung abgeschlossen ist.
Wenn keine maschinelle Erkennung erfolgt, wird nach der Annahme des Anrufs der NCCO abgerufen und sofort mit der Verarbeitung begonnen. Das bedeutet, dass in den Fällen, in denen ein Mensch den Anruf entgegennimmt, zu Beginn des Anrufs keine Stille herrscht, was für den Endbenutzer ein besseres Erlebnis darstellt. Um die Lücke zwischen keiner Maschinenerkennung und Maschinenerkennung zu schließen, hat Vonage den asynchronen Modus im neuen Angebot der erweiterten Maschinenerkennung entwickelt.
Im asynchronen Modus laufen die Schritte der Maschinenerkennung parallel zur NCCO-Verarbeitung ab. Nach der Beantwortung des Anrufs können die Applications also erwarten, dass die Ereignisse auf diese Weise eintreffen und verarbeitet werden:
In diesem Fall beginnt die erste Aktion des NCCO nach dem Antwort-Ereignis, während die Maschinenerkennung im Hintergrund ausgeführt wird. Wenn es sich bei dieser Aktion um eine Gesprächsaktion handelt, bedeutet dies, dass keine Stille im Kanal herrscht, während die Erkennung stattfindet. Wenn die erste Aktion abgeschlossen ist, fährt Vonage mit der Verarbeitung weiterer Aktionen des NCCO fort, während die Erkennung stattfindet.
Standard-Maschinendetektion
Wenn die standardmäßige Anrufbeantwortererkennung aktiviert ist, kann eine Anwendung erkennen, ob ein Anrufbeantworter oder ein Mensch den Anruf entgegengenommen hat. Die Entwickler müssen eine von zwei Verhaltensweisen für die Erkennung einer Maschine definieren: continue oder hangup.
Sie können zum Beispiel einen Anruf mit Maschinenerkennung erstellen, der auflegt, wenn eine Maschine antwortet, oder einen NCCO von der answer_url sonst. In beiden Fällen erhält die Anwendung Ereignisse mit den Ergebnissen der Erkennung, so dass Sie wissen, ob die Person den Anruf angenommen hat oder nicht.
Um dies zu erreichen, würden Sie eine
https://api.nexmo.com/v1/calls/mit einem JWT als Autorisierungsmethode. Der Text der Anfrage sollte in etwa so lauten:
{
"answer_url": [
"https://example.com/answer"
],
"answer_method": "POST",
"to": [
{
"type": "phone",
"number": "14155550100",
}
],
"from": {
"type": "phone",
"number": "14155550100"
},
"event_url": [
"https://example.com/event"
],
"event_method": "POST",
"machine_detection": "hangup"
}
Wenn anstelle von hangup, continue verwendet wurde, würde das NCCO abgerufen werden, aber Ihre Anwendung würde auch das Ergebnisereignis durch ein Rückruf Mensch/Maschine zu Ihrer Ereignis-URL.
Es ist wichtig zu beachten, dass die standardmäßige Maschinenerkennung synchron erfolgt, was wiederum bedeutet, dass die Erkennung vor dem Abrufen und Verarbeiten der ersten NCCO-Aktion erfolgt. Während der Erkennung ist es unmöglich, mit dem Benutzer, der den Anruf erhält, zu interagieren.
Weitere Beispiele für das Tätigen eines Anrufs mit der Voice API finden Sie unter dieses Codeschnipsel.
Die maschinelle Erkennung ist auch über eine NCCO connect Aktionmit den gleichen Optionen von hangup und continue:
{
"action": "connect",
"eventUrl": ["https://example.com/events"],
"timeout": "45",
"from": "447700900000",
"machineDetection": "hangup",
"endpoint": [
{
"type": "phone",
"number": "447700900001"
}
]
}
Erweiterte Maschinendetektion
Die fortschrittliche Maschinenerkennung von Vonage wurde entwickelt, um sowohl die Genauigkeit der Erkennung als auch das Spracherlebnis zu verbessern, das Vonage bieten kann.
Hinweis: Hierbei handelt es sich um eine Premiumfunktion, für die eine zusätzliche Gebühr von 0,0070 € pro Anruf bei aktivierter Advanced Machine Detection anfällt.
Um die erweiterte Maschinenerkennung bei einem neuen Anruf zu nutzen, müssen Sie eine
https://api.nexmo.com/v1/calls/mit einem JWT als Autorisierungsmethode. Der Text der Anfrage muss die advanced_machine_detection Konfiguration:
{
"answer_url": [
"https://example.com/answer"
],
"answer_method": "POST",
"to": [
{
"type": "phone",
"number": "14155550100",
}
],
"from": {
"type": "phone",
"number": "14155550100"
},
"event_url": [
"https://example.com/event"
],
"event_method": "POST",
"advanced_machine_detection": {
"behavior" : “continue”,
"mode": “default”,
"beep_timeout": 45
}
}
Dies kann auch mit einer NCCO connect Aktionmit den gleichen Optionen von hangup und continue:
{
"action": "connect",
"eventUrl": ["https://example.com/events"],
"timeout": "45",
"from": "447700900000",
"advancedMachineDetection": {
"behavior" : “continue”,
"mode": “default”,
"beep_timeout": 45
}
"endpoint": [
{
"type": "phone",
"number": "447700900001"
}
]
}
Wie in den Beispielen zu sehen, advanced_machine_detection (oder advancedMachineDetection) hat drei konfigurierbare Parameter:
behavior- legt fest, was die Vonage-Plattform tun soll, wenn sie auf eine Maschine trifft. Die möglichen Werte sind:continue- Wenn eine Maschine angetroffen wird, setzen Sie den Anruf fort.hangup- Wenn eine Maschine angetroffen wird, beenden Sie den Anruf.
beep_timeout- können Sie festlegen, wie lange auf den Piepton der Voicemail gewartet werden soll, und für den Fall, dass dieser nicht empfangen wird, ein entsprechendes Webhook-Ereignis erzeugen.mode- neben dem Hauptverhalten vonhangupgegencontinuebei der Bearbeitung von Anrufen ist es auch möglich, einen von drei Modi zu definieren. Diese werden im Folgenden näher erläutert.
default Modus
Die default Modus bietet den höchsten Grad an Kontrolle über den Anruf. Dieser Modus arbeitet asynchron, d. h. Vonage beginnt mit der Verarbeitung von NCCO-Aktionen während der Erkennungsphase.
Nehmen wir als Beispiel an, dass dieser NCCO als Antwort auf den NCCO-Abruf von der Website von Vonage zurückgegeben wurde. answer_url:
[
{
"action": "talk",
"text": "Hello from Vonage Voice API. We would like to inform you of a very important message",
"language": "en-GB",
"loop": 3
}
]
Sobald der Anruf entgegengenommen wird, wird diese Nachricht sofort abgespielt und dreimal wiederholt, während die Algorithmen zur Maschinenerkennung parallel den Ton des anderen Teilnehmers verarbeiten.
Während dieser Gesprächsaktion kann ein Maschinenerkennungsergebnis auftreten; in diesem Fall wird ein Webhook an die event_url.
Der Webhook wird wie folgt aussehen (entweder mit human oder machine als Status):
{
"from": "442079460000",
"to": "447700900000",
"status": "human/machine",
"call_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
}
Unabhängig davon, ob ein menschliches oder maschinelles Ereignis an die Anwendung gesendet wird, kann die Anwendung auf einen solchen Webhook auf zwei Arten antworten. Entweder gibt sie eine 204 um fortzufahren, oder geben Sie ein 200 mit einem neuen NCCO, der den bisherigen NCCO ersetzen wird.
Das bedeutet, dass eine Anwendung das Verhalten differenzieren kann. Wenn es sich um einen Menschen handelt, könnte der Anruf mit demselben NCCO fortgesetzt und weitere Aktionen durchgeführt werden, z. B. die Anforderung und Verarbeitung von DTMF-Eingaben.
Handelt es sich um einen Anrufbeantworter, könnte die Anwendung auf den Signalton warten und dann eine individuelle Voicemail-Nachricht hinterlassen. A Maschinenereignis mit sub_state beep_start zeigt den Beginn des Signaltons der Mailbox an. Im Gegensatz dazu, beep_timeout sub_state zeigt an, dass der Signalton nach der festgelegten Wartezeit nicht empfangen wurde. Die Anwendung kann auch ein 200 OK mit einem neuen NCCO, mit der Nachricht, die in der Voicemail platziert werden soll.
Der folgende Codeausschnitt, der in einer Anwendung ausgeführt wird, würde eine neue Gesprächsaktion verwenden, wenn eine Maschine erkannt wird, die besagt, dass die Plattform auf den Signalton warten soll (zur Veranschaulichung: in einem realen Beispiel ein 204 stattdessen verwendet werden könnte), während bei sub_state ist beep_start hinterlässt die eigentliche Voicemail-Nachricht nach dem Signalton.
app.post('/onEvent', (req, res, next) => {
try {
…
if(req.body.status == 'machine' && !(req.body.sub_state == 'beep_start') ) {
const ncco = [{
action: 'talk',
text: 'Oh, it\'s actually a machine. Let’s wait for beep'
}];
console.log(req.body);
res.json(ncco);
}
else if(req.body.status == 'machine' && req.body.sub_state == 'beep_start' ) {
const ncco = [{
action: 'talk',
text: 'This is a very important message Vonage will leave in the voicemail after the beep'
}];
console.log(req.body);
res.json(ncco);
}
else {
console.log(req.body);
res.send(204);
}
Mit default Modus ist es möglich, Spracherlebnisse zu schaffen, bei denen es zu Beginn des Anrufs keine Stille gibt, mit der Möglichkeit, Sprachnachrichten direkt nach dem Signalton zu hinterlassen, ohne dass die Nachricht abgeschnitten wird.
detect Modus
Die detect Modus hat das gleiche Verhalten wie die Standard-Maschinenerkennung mit einer genaueren Erkennung von Maschinen. Entwickler, die ihre alte Sprachanwendung, die auf der Standard-Maschinenerkennung aufbaut, migrieren möchten, können dies mit minimalen Codeänderungen tun.
Normalerweise sollte dieser Modus verwendet werden, wenn das gewünschte Verhalten darin besteht, den Anruf in Anwesenheit einer Maschine aufzulegen. Er ist synchron, wenn also continue verwendet wird, statt hangup wartet es bis nach der Erkennung eines Menschen oder einer Maschine, um mit der Verarbeitung des NCCO aus dem answer_url wenn es sich um einen neuen Anruf handelt, der aus
detect_beep Modus
Die detect_beep Modus baut auf dem detect Modus, bei dem eine Voicemail-Nachricht direkt nach dem Signalton hinterlegt werden kann. Dieser Modus sollte verwendet werden, wenn eine continue Verhalten erwünscht ist. Wenn human erkannt wird, verhält es sich genau wie detect Modus, da er synchron läuft und wartet, bis die Maschinenerkennung beendet ist, bevor er die NCCO oder die nächste NCCO-Aktion verarbeitet.
Der Hauptunterschied in diesem Modus besteht darin, dass Vonage bei der Erkennung eines Geräts auf die beep Ereignis (oder beep_timeout), bevor die NCCO- oder nächste NCCO-Aktion ausgeführt wird. Dies ermöglicht Vonage, eine Nachricht an einen Menschen zu übermitteln oder sie nach einem Signalton in einer Voicemail-Nachricht zu hinterlassen.