NCCO-Referenz

Ein Anrufsteuerungsobjekt (NCCO) wird durch ein JSON-Array dargestellt. Sie können es verwenden, um den Ablauf eines Voice API-Aufrufs zu steuern. Damit Ihr NCCO korrekt ausgeführt werden kann, müssen die JSON-Objekte gültig sein.

Beim Entwickeln und Testen von NCCOs können Sie den Voice Playground nutzen, um NCCOs interaktiv auszuprobieren. Sie können Lesen Sie mehr darüber in der Voice API Übersicht oder direkt zum Voice Playground im Dashboard gehen.

NCCO-Aktionen

Die Reihenfolge der Aktionen im NCCO steuert den Ablauf des Aufrufs. Aktionen, die abgeschlossen sein müssen, bevor die nächste Aktion ausgeführt werden kann, sind synchron. Andere Aktionen sind asynchrone. Das heißt, sie sollen die folgenden Aktionen fortsetzen, bis eine Bedingung erfüllt ist. Zum Beispiel, eine record Aktion wird beendet, wenn die endOnSilence Option erfüllt ist. Wenn alle Aktionen im NCCO abgeschlossen sind, endet der Aufruf.

Die NCCO-Aktionen und die Optionen und Typen für jede Aktion sind:

Beachten Sie, dass bei allen Aktionen die eventUrl Parameter MUSS ein Array sein, auch wenn er nur einen einzigen Wert enthält.

Datensatz

Verwenden Sie die record Aktion, um einen Anruf oder einen Teil eines Anrufs aufzuzeichnen:

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from":"447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

Die Aufzeichnungsaktion ist asynchron. Sie können eine synchrone Bedingung definieren - endOnSilence, timeOut oder endOnKey - um die Aufzeichnung zu beenden, wenn sie erfüllt ist. Wenn keine Bedingung festgelegt ist, arbeitet die Aufzeichnung asynchron und fährt sofort mit der nächsten Aktion fort, während der Anruf weiter aufgezeichnet wird. Die Aufzeichnung wird erst dann beendet und das entsprechende Ereignis gesendet, wenn der Anruf beendet wird. Dies wird für ähnliche Szenarien wie die Anrufüberwachung verwendet.

Sie können eine Aufnahme mit der Funktion transcription Option. Sobald die Transkription der Aufnahme abgeschlossen ist, wird ein Rückruf an eine eventUrl. Mit den Transkriptionseinstellungen können Sie eine benutzerdefinierte eventUrl und language für Ihre Transkriptionen. Bitte beachten Sie, dass dies eine kostenpflichtige Funktion ist; die genauen Preise finden Sie auf der Seite Voice API-Preise Seite unter 'Programmierbare Funktionen'.

Informationen über den Arbeitsablauf finden Sie unter Aufnahme.

Sie können die folgenden Optionen verwenden, um eine record Aktion:

Transkriptionseinstellungen

Satzrückgabeparameter

Siehe die Webhook-Referenz für Datensatz- oder Transkriptionsparameter, die an den eventUrl.

Konversation

Sie können die conversation Aktion zur Erstellung von Standard- oder moderierten Konferenzen, wobei der Kommunikationskontext erhalten bleibt. Verwendung von conversation mit demselben name verwendet die gleiche persistierte Konversation. Die erste Person, die die dem Gespräch zugewiesene virtuelle Nummer anruft, erstellt es. Diese Aktion ist synchron.

Die folgenden NCCO-Beispiele zeigen, wie Sie verschiedene Arten von Konversationen konfigurieren können. Sie können die answer_url Webhook-GET-Anforderungsparameter, um sicherzustellen, dass Sie ein NCCO an die Teilnehmer und ein anderes an den Moderator übermitteln.

[
  {
    "action": "conversation",
    "name": "nexmo-conference-standard",
    "record": true,
    "transcription": {
      "eventUrl": [ "https://example.com/transcription" ],
      "eventMethod": "POST",
      "language": "he-IL"
    }
  }
]

// As the customer is the first person to join, there is no canHear/canSpeak entry
// The customer's leg ID is 6a4d6af0-55a6-4667-be90-8614e4c8e83c
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"],
  }
]

// The agent joins and can both hear, and speak to the customer
// The agent's leg ID is 533c0874-f43d-446c-a153-f35bf30783fa
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"], // Customer leg ID
    "canSpeak": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"] // Customer leg ID
  }
]

// Finally, the supervisor joins the conversation. They can hear both the customer
// and the agent, but only speak to the agent
// The supervisor's leg ID is e2833e43-db39-4c1a-b689-d17ad2cf3529
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c", "533c0874-f43d-446c-a153-f35bf30783fa"] // Customer leg ID, Agent leg ID
    "canSpeak": ["533c0874-f43d-446c-a153-f35bf30783fa"] // Agent leg ID
  }
]

[
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "record": true,
    "startOnEnter": true
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference. We will connect you when an agent is available"
  },
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"]
  }
]

Sie können die folgenden Optionen verwenden, um eine Gespräch Aktion:

Verbinden Sie

Sie können die connect Aktion, um einen Anruf mit Endpunkten wie Telefonnummern oder einer VBC-Nebenstelle zu verbinden.

Diese Aktion ist synchron, nach einer verbinden wird die nächste Aktion im NCCO-Stapel abgearbeitet. Eine Verbindungsaktion endet, wenn der angerufene Endpunkt besetzt oder nicht verfügbar ist. Sie rufen Endpunkte nacheinander an, indem Sie Verbindungsaktionen verschachteln.

Die folgenden NCCO-Beispiele zeigen, wie man verschiedene Arten von Verbindungen konfiguriert.

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001",
        "dtmfAnswer": "2p02p"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "ws://example.com/socket",
        "content-type": "audio/l16;rate=16000",
        "headers": {
            "name": "J Doe",
            "age": 40,
            "address": {
                "line_1": "Apartment 14",
                "line_2": "123 Example Street",
                "city": "New York City"
            },
            "system_roles": [183493, 1038492, 22],
            "enable_auditing": false
        }
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "app",
        "user": "jamie"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "sip",
        "uri": "sip:rebekka@sip.mcrussell.com",
        "headers": { "location": "New York City", "occupation": "developer" }
      }
    ]
  }
]

[
  {
    "action": "connect",
    "from": "447700900000",
    "timeout": 5,
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/event-fallback"
    ],
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "voiceName": "Russell",
    "text": "Thank you for calling. Connecting you to extension."
  },
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "vbc",
        "extension": "111"
      }
    ]
  }
]

[
    {  
      "action": "talk",  
      "text": "Please wait while we connect you"
    },
    {
        "action": "connect",
        "eventUrl": [
          "https://example.com/events"
        ],
        "from": "447700900000",
        "endpoint": [
            {  
              "type": "sip",  
              "user": "john",
              "domain": "vonage-developer", 
              "headers":
                { 
                  "location": "New York City", 
                  "occupation": "developer"
                }
            }
        ]
    }
]

Sie können die folgenden Optionen verwenden, um eine connect Aktion:

Beispiel für den shaken Option:

eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"

Endpunkttypen und Werte

Telefon (PSTN) - Telefonnummern im E.164-Format

Beispiel für den shaken Option:

eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"

App - Verbinden Sie den Anruf mit einer RTC-fähigen Anwendung

WebSocket - der WebSocket, mit dem eine Verbindung hergestellt werden soll

SIP - der SIP-Endpunkt, mit dem eine Verbindung hergestellt werden soll

VBC - die Vonage Business Cloud (VBC)-Erweiterung zur Verbindung mit

Gespräch

Die talk Aktion sendet synthetisierte Sprache an eine Konversation.

Der Text, der in der Talk-Aktion angegeben wird, kann entweder einfach sein oder mit SSML. SSML-Tags enthalten weitere Anweisungen für den Text-to-Speech-Synthesizer, mit denen Sie die Tonhöhe und die Aussprache festlegen und Text in mehreren Sprachen miteinander kombinieren können. SSML-Tags sind XML-basiert und werden inline im JSON-String gesendet.

Standardmäßig ist die Gesprächsaktion synchron. Wenn Sie jedoch bargeIn zu wahr müssen Sie eine Eingabe Aktion später im NCCO-Stack. Das folgende NCCO-Beispiel zeigt, wie man eine synthetische Sprachnachricht an eine Konversation oder einen Anruf sendet:

[
  {
    "action": "talk",
    "text": "You are listening to a Call made with Voice API"
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Voice API I V R. ",
    "language": "en-GB",
    "bargeIn": false
  },
  {
    "action": "talk",
    "text": "Press 1 for maybe and 2 for not sure followed by the hash key",
    "language": "en-GB",
    "bargeIn": true
  },
  {
    "action": "input",
    "submitOnHash": true,
    "eventUrl": ["https://example.com/ivr"]
  }
]

[
  {
    "action": "talk",
    "text": "<speak><prosody rate='fast'>I can speak fast.</prosody></speak>"
  }
]

Sie können die folgenden Optionen verwenden, um eine sprechen Aktion:

Gespräch Rückgabeparameter

Siehe Webhook-Referenz für die Parameter, die an den eventUrl.

Stream

Die stream Aktion können Sie einen Audiostrom an eine Konversation senden

Standardmäßig ist die Stream-Aktion synchron. Wenn Sie jedoch die Option bargeIn zu wahr müssen Sie eine Eingabe Aktion später im NCCO-Stapel.

Das folgende NCCO-Beispiel zeigt, wie man einen Audiostrom an eine Konversation oder einen Anruf sendet:

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/music.mp3"]
  }
]

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/announcement.mp3"],
    "bargeIn": "true"
  },
  {
    "action": "input",
    "submitOnHash": "true",
    "eventUrl": ["https://example.com/ivr"]
  }
]

Sie können die folgenden Optionen verwenden, um eine Strom Aktion:

Der angegebene Audiostrom sollte eine Datei im MP3- oder WAV-Format sein. Wenn Sie Probleme mit der Wiedergabe der Datei haben, kodieren Sie sie bitte gemäß der folgenden technischen Spezifikation: Welche Art von voraufgezeichneten Audiodateien kann ich verwenden?

Cache-Control: public, max-age=360000

Stream Return Parameter

Siehe Webhook-Referenz für die Parameter, die an den eventUrl.

Eingabe

Sie können die input Aktion, um Ziffern oder Spracheingaben des Anrufers zu erfassen. Diese Aktion ist synchron, Vonage verarbeitet die Eingaben und leitet sie an die Parameter die an den eventUrl Webhook-Endpunkt, den Sie in Ihrer Anfrage konfigurieren. Ihr Webhook-Endpunkt sollte ein anderes NCCO zurückgeben, das das bestehende NCCO ersetzt und den Anruf auf der Grundlage der Benutzereingabe steuert. Sie können diese Funktionalität nutzen, um eine interaktive Sprachantwort (IVR) zu erstellen. Wenn Ihr Benutzer zum Beispiel drückt 4 oder "Verkauf" sagt, geben Sie eine verbinden NCCO, der den Anruf an Ihre Vertriebsabteilung weiterleitet.

Das folgende NCCO-Beispiel zeigt, wie man einen IVR-Endpunkt konfiguriert:

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something"
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }
  }
]

Das folgende NCCO-Beispiel zeigt, wie man bargeIn um einem Benutzer die Unterbrechung einer talk Aktion. Beachten Sie, dass eine input Aktion muss folgen jeder Aktion, die eine bargeIn Eigenschaft (z.B. talk oder stream).

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something",
    "bargeIn": true
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],	
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }	
  }
]

Die folgenden Optionen können verwendet werden, um eine input Aktion:

DTMF-Eingabeeinstellungen

Anmerkung: Diese Einstellungen gelten nicht, wenn die mode wird eingestellt auf asynchronous.

Spracherkennungseinstellungen

Das folgende Beispiel zeigt die Parameter, die an den eventUrl Webhook für DTMF-Eingabe:

{
  "speech": { "results": [ ] },
  "dtmf": {
    "digits": "1234",
    "timed_out": true
  },
  "from": "15551234567",
  "to": "15557654321",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

Das folgende Beispiel zeigt die Parameter, die zurück an die eventUrl Webhook für Spracheingabe:

{
  "speech": {
    "recording_url": "https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab",
    "timeout_reason": "end_on_silence_timeout",
    "results": [
      {
        "confidence": "0.9405097",
        "text": "sales"
      },
      {
        "confidence": "0.70543784",
        "text": "sails"
      },
      {
        "confidence": "0.5949854",
        "text": "sale"
      }
    ]
  },
  "dtmf": {
    "digits": null,
    "timed_out": false
  },
  "from": "15551234567",
  "to": "15557654321",  
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

Eingabe Rückgabe Parameter

Siehe Webhook-Referenz für Eingabeparameter, die an den eventUrl.

benachrichtigen.

Verwenden Sie die notify Aktion, um eine benutzerdefinierte Nutzlast an Ihre Ereignis-URL zu senden. Ihr Webhook-Endpunkt kann ein anderes NCCO zurückgeben, das das vorhandene NCCO ersetzt, oder eine leere Nutzlast zurückgeben, was bedeutet, dass das vorhandene NCCO weiterhin ausgeführt wird.

[
  {
    "action": "notify",
    "payload": {
      "foo": "bar"
    },
    "eventUrl": [
      "https://example.com/webhooks/event"
    ],
    "eventMethod": "POST"
  }
]

Aufforderungen Spracheinstellungen

Warten

Sie können die wait Aktion, um eine Wartezeit hinzuzufügen und die Ausführung des laufenden NCCO für eine bestimmte Anzahl von Sekunden anzuhalten.

Die Aktion ist synchron. Die Wartezeit beginnt, wenn die Warteaktion im NCCO ausgeführt wird, und endet nach dem angegebenen oder dem Standard-Timeout-Wert. Zu diesem Zeitpunkt setzt der NCCO die Ausführung fort. Die Website timeout ist ein Float-Wert. Gültige Werte reichen von 0,1 Sekunden bis 7200 Sekunden. Werte unter 0,1 Sekunden sind standardmäßig 0,1 Sekunden, und Werte über 7200 sind standardmäßig 7200 Sekunden. Wird kein Wert angegeben, wird der Standardwert 10 Sekunden sein.

Das folgende NCCO-Beispiel zeigt, wie man die Warteaktion ausführt:

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference"
  },
  {
    "action": "wait",
    "timeout": 0.5
  },
  {
    "action": "talk",
    "text": "We will connect you when an agent is available"
  }
]

Sie können die folgenden Optionen verwenden, um eine wait Aktion:

Übertragung

Die transfer Aktion ist synchron. Sie können damit die Gesprächsabschnitte aus einem laufenden Gespräch in ein anderes bestehendes Gespräch verschieben. Die Seite transfer Die Aktion ist für das aktuelle Gespräch beendet, und der NCCO des Zielgesprächs steuert weiterhin das Verhalten des Zielgesprächs. Alle Teile der aktuellen Konversation werden in die Zielkonversation übertragen, wobei die Audioeinstellungen (canHear, canSpeak, mute), wenn sie zur Verfügung gestellt werden.

Das folgende NCCO-Beispiel zeigt, wie die Übertragungsaktion ausgeführt wird:

[
   ...
   {
     "action": "transfer",
     "conversationId": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
     "canHear": [ "9c132730-8c22-4760-a4dc-40502f05b444" ]
   }
   ...
]

Sie können die folgenden Optionen verwenden, um eine Übertragungsaktion zu steuern: