Référence NCCO

Un objet de contrôle d'appel (NCCO) est représenté par un tableau JSON. Vous pouvez l'utiliser pour contrôler le flux d'un appel Voice API. Pour que votre NCCO s'exécute correctement, les objets JSON doivent être valides.

Pendant que vous développez et testez les NCCO, vous pouvez utiliser le Voice Playground pour tester les NCCO de manière interactive. Vous pouvez Pour en savoir plus, consultez l'aperçu de la Voice API ou accéder directement au terrain de jeu vocal dans le tableau de bord.

Actions du NCCO

L'ordre des actions dans le NCCO contrôle le flux de l'appel. Les actions qui doivent être achevées avant que l'action suivante puisse être exécutée sont les suivantes synchrone. Les autres actions sont asynchrone. En d'autres termes, ils sont censés poursuivre les actions suivantes jusqu'à ce qu'une condition soit remplie. Par exemple, une action record se termine lorsque l'action endOnSilence est satisfaite. Lorsque toutes les actions du BCN sont terminées, l'appel prend fin.

Les actions du NCCO et les options et types pour chaque action sont les suivants :

Notez que dans toutes les actions, le eventUrl DOIT être un tableau, même s'il ne contient qu'une seule valeur.

Enregistrer

Utiliser le record pour enregistrer un appel ou une partie d'un appel :

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

L'action d'enregistrement est asynchrone. Vous pouvez définir une condition synchrone - endOnSilence, timeOut ou endOnKey - pour terminer l'enregistrement lorsqu'elle est remplie. Si aucune condition n'est définie, l'enregistrement fonctionnera de manière asynchrone et passera instantanément à l'action suivante tout en continuant à enregistrer l'appel. L'enregistrement ne se terminera et n'enverra l'événement correspondant que lorsque l'appel sera terminé. Cette fonction est utilisée pour des scénarios similaires à la surveillance des appels.

Vous pouvez transcrire un enregistrement à l'aide de la fonction transcription option. Une fois la transcription de l'enregistrement achevée, un rappel sera envoyé à une personne de l'Union européenne. eventUrl. Les paramètres de transcription vous permettent de spécifier un nom de fichier personnalisé. eventUrl et language pour vos transcriptions. Veuillez noter qu'il s'agit d'une fonction payante ; les tarifs exacts peuvent être consultés sur le site web de la Commission européenne. Prix de l'API Voice sous la rubrique "Fonctions programmables".

Pour plus d'informations sur la procédure à suivre, voir Enregistrement.

Vous pouvez utiliser les options suivantes pour contrôler un record action :

Paramètres de transcription

Paramètres de retour des enregistrements

Voir le Référence pour les webhooks pour les paramètres d'enregistrement ou de transcription qui sont renvoyés au eventUrl.

Conversation

Vous pouvez utiliser le conversation pour créer des conférences standard ou modérées, tout en préservant le contexte de communication. L'utilisation de conversation avec le même name réutilise les mêmes données persistantes Conversation. La première personne à appeler le numéro virtuel attribué à la conversation la crée. Cette action est synchrone.

Les exemples suivants du BCN montrent comment configurer différents types de conversation. Vous pouvez utiliser le answer_url afin de vous assurer que vous envoyez un NCCO aux participants et un autre à l'animateur.

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

Vous pouvez utiliser les options suivantes pour contrôler un conversation action :

Connecter

Vous pouvez utiliser le connect pour connecter un appel à des terminaux tels que des numéros de téléphone ou un poste VBC.

Cette action est synchrone, après une relier l'action suivante de la pile NCCO est traitée. Une action de connexion se termine lorsque le terminal que vous appelez est occupé ou indisponible. Vous appelez les terminaux de manière séquentielle en imbriquant les actions de connexion.

Les exemples suivants du BCN montrent comment configurer différents types de connexions.

[
  {
    "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
        },
        "authorization": {
            "type": "custom",
            "value": "Bearer eyJhbGciOi..."
        }
      }
    ]
  }
]

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

Vous pouvez utiliser les options suivantes pour contrôler un connect action :

Types et valeurs des points de terminaison

Téléphone (PSTN) - numéros de téléphone au format E.164

Exemple de la shaken option :

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

Applications - Connecter l'appel à une application compatible RTC

WebSocket - le WebSocket auquel se connecter

SIP - le point d'extrémité SIP auquel se connecter

VBC - l'extension Vonage Business Cloud (VBC) pour se connecter à .

Parler

Les talk envoie un discours synthétisé à une conversation.

Le texte fourni dans l'action "talk" peut être soit simple, soit formaté à l'aide de la fonction SSML. Les balises SSML fournissent des instructions supplémentaires au synthétiseur de synthèse vocale qui vous permettent de régler la hauteur, la prononciation et de combiner des textes dans plusieurs langues. Les balises SSML sont basées sur XML et envoyées en ligne dans la chaîne JSON.

Par défaut, l'action talk est synchrone. Cependant, si vous définissez bargeIn à vrai vous devez définir un entrée plus loin dans la pile NCCO. Les exemples NCCO suivants montrent comment envoyer un message vocal synthétisé à une conversation ou à un appel :

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

Vous pouvez utiliser les options suivantes pour contrôler un parler action :

Paramètres de retour de la conversation

Voir Référence pour les webhooks pour les paramètres qui sont renvoyés au eventUrl.

Flux

Les stream permet d'envoyer un flux audio à une Conversation

Par défaut, l'action stream est synchrone. Cependant, si vous définissez bargeIn à vrai vous devez définir un entrée plus tard dans la pile NCCO.

L'exemple suivant du BCN montre comment envoyer un flux audio à une conversation ou à un appel :

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

Vous pouvez utiliser les options suivantes pour contrôler un flux action :

Le flux audio auquel il est fait référence doit être un fichier au format MP3 ou WAV. Si vous rencontrez des problèmes lors de la lecture du fichier, veuillez l'encoder selon les spécifications techniques suivantes : Quels types de fichiers audio préenregistrés puis-je utiliser ?

Cache-Control: public, max-age=360000

Paramètres de retour des cours d'eau

Voir Référence pour les webhooks pour les paramètres qui sont renvoyés au eventUrl.

Entrée

Vous pouvez utiliser le input pour collecter les chiffres ou les paroles de la personne que vous appelez. Cette action est synchrone, Vonage traite l'entrée et la transmet dans l'interface de l'appelant. paramètres envoyé au eventUrl que vous configurez dans votre demande. Votre point de terminaison webhook doit renvoyer un autre NCCO qui remplace le NCCO existant et contrôle l'appel en fonction de l'entrée de l'utilisateur. Vous pouvez utiliser cette fonctionnalité pour créer un serveur vocal interactif (SVI). Par exemple, si votre utilisateur appuie sur 4 ou dit "Sales", vous renvoyez un relier NCCO qui transmet l'appel à votre service commercial.

L'exemple suivant du NCCO montre comment configurer un terminal IVR :

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

L'exemple suivant du NCCO montre comment utiliser bargeIn pour permettre à un utilisateur d'interrompre un talk action. Il convient de noter qu'une action input action doit suivre toute action ayant un bargeIn (par exemple talk ou 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" ]
    }	
  }
]

Les options suivantes peuvent être utilisées pour contrôler un input action :

Paramètres d'entrée DTMF

Remarque : Ces réglages ne s'appliquent pas si le mode est fixé à asynchronous.

Paramètres de reconnaissance vocale

L'exemple suivant montre les paramètres envoyés au eventUrl pour l'entrée DTMF :

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

L'exemple suivant montre les paramètres renvoyés au eventUrl pour la saisie vocale :

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

Paramètres de retour d'entrée

Voir Référence pour les webhooks pour les paramètres d'entrée qui sont renvoyés au eventUrl.

Notifier

Utiliser le notify pour envoyer une charge utile personnalisée à l'URL de votre événement. Votre point de terminaison webhook peut renvoyer un autre NCCO qui remplace le NCCO existant ou renvoyer un payload vide, ce qui signifie que le NCCO existant continuera à s'exécuter.

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

Messages vocaux Paramètres vocaux

Attendre

Vous pouvez utiliser le wait pour ajouter une période d'attente et suspendre l'exécution du BCN en cours pendant un nombre de secondes spécifié.

L'action est synchrone. La période d'attente commence lorsque l'action d'attente est exécutée dans le BCN et se termine après la valeur de temporisation fournie ou par défaut. À ce stade, le BCN reprend l'exécution. L'action timeout est un nombre flottant. Les valeurs valides sont comprises entre 0,1 seconde et 7200 secondes. Les valeurs inférieures à 0,1 prennent par défaut la valeur 0,1 seconde, et les valeurs supérieures à 7200 prennent par défaut la valeur 7200 secondes. Si elle n'est pas spécifiée, la valeur par défaut est de 10 secondes.

L'exemple suivant du BCN montre comment exécuter l'action d'attente :

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

Vous pouvez utiliser les options suivantes pour contrôler un wait action :

Transfert

Les transfer est synchrone. Vous pouvez l'utiliser pour déplacer les segments d'appel d'une conversation en cours vers une autre conversation existante. L'action transfer est terminée pour la conversation en cours, et le NCCO de la conversation cible continue à contrôler le comportement de la conversation cible. Tous les segments de la conversation en cours sont transférés dans la conversation cible, en respectant les paramètres audio (canHear, canSpeak, mute) s'ils sont fournis.

L'exemple suivant du BCN montre comment exécuter l'action de transfert :

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

Vous pouvez utiliser les options suivantes pour contrôler une action de transfert :