Détection de la messagerie vocale (détection automatique des machines)

Lorsque l'on utilise l'API Voice de Vonage pour créer une expérience vocale sortante, il est parfois nécessaire de prendre en compte qui, ou dans certains cas quoi, répond à l'appel. Il se peut que l'expérience à créer soit réservée aux humains, auquel cas l'appel doit être déconnecté lorsqu'un système de messagerie vocale y répond. Ou bien, dans le cas où un système de messagerie vocale répond à l'appel, il peut être nécessaire de laisser un message personnalisé après le bip.

Vonage propose deux fonctions différentes pour les cas d'utilisation de la détection des machines :

  • Détection standard des machines - offre une capacité de base de détection des machines, avec des options permettant d'abandonner l'appel automatiquement ou d'informer simplement l'application du fait que l'appel a probablement été pris par la messagerie vocale. Sans frais supplémentaires.
  • Détection avancée des machines - offre une détection plus précise et une flexibilité totale pour construire n'importe quel flux d'appels. Elle offre également une détection par bip et un mode de fonctionnement asynchrone qui permet un meilleur contrôle des appels. La détection avancée des machines est une fonction payante ; les tarifs exacts peuvent être consultés sur la page d'accueil du site web de l'Union européenne. Prix de l'API Voice sous la rubrique "Fonctions programmables".

Note : Si vous essayez d'utiliser les deux méthodes dans le même appel, la détection avancée des machines sera prioritaire et l'option standard ne sera pas utilisée.

Établissement des appels et détection des machines

Quel que soit le type de détection de machine (standard ou avancée) utilisé, les mêmes principes sont applicables. Lorsque l'API Voice de Vonage reçoit l'instruction d'effectuer un appel vers un numéro de téléphone, soit par une requête

POST
, soit par une action de connexion NCCO, et que cette requête inclut l'activation de la détection de machine, le processus d'établissement de l'appel passe par les mêmes états que ceux décrits dans la section Flux d'appels.

Un appel réussi passera toujours par les états suivants avant toute détection de machine :

  • Commencé
  • Sonnerie
  • Répondu

Une fois que l'appel a atteint l'état de réponse, la détection de la machine commence. Pour que la détection des machines puisse commencer, il faut que l'appel soit établi et que l'audio commence à circuler vers Vonage. C'est sur la base de l'analyse de ce son que Vonage détermine si c'est un humain ou une machine qui a répondu à l'appel.

Vonage enverra toujours les résultats au webhook de l'événement dans la section status champ d'un Webhook de type humain / machine.

Dans cette optique, examinons la séquence des événements impliqués dans la détection et le traitement des appels, avant de nous pencher sur la manière d'utiliser chaque type de détection des machines.

Implémentations synchrones et asynchrones

En ce qui concerne le traitement des appels et les actions NCCO, il existe deux options de mise en œuvre : synchrone et asynchrone.

En mode synchrone, toutes les activités liées à la détection de la machine sont effectuées, et ce n'est qu'une fois qu'elles sont terminées que Vonage commence à traiter les instructions NCCO.

Cela signifie qu'après avoir répondu à un appel, les événements suivants se déroulent de manière séquentielle :

  • Événement répondu
  • Événement(s) humain(s) / machine(s) (y compris le bip sonore, le cas échéant)
  • Traitement de la première instruction NCCO
  • (Facultatif) événements liés à l'instruction du NCCO (le cas échéant)
  • Autres instructions du NCCO

L'identification de la partie distante en tant que machine ou humain prend jusqu'à 4-5 secondes, de sorte que le côté de l'appel de Vonage reste silencieux jusqu'à ce que l'identification soit terminée.

Lorsqu'il n'y a pas de détection automatique, le NCCO est récupéré dès que l'on répond à l'appel et commence immédiatement à être traité. Cela signifie que lorsqu'un humain répond à l'appel, il n'y a pas de silence au début de l'appel, ce qui améliore l'expérience de l'utilisateur final. Pour combler le fossé entre l'absence de détection de machine et la détection de machine, Vonage a développé le mode asynchrone dans la nouvelle offre de détection de machine avancée.

En mode asynchrone, les étapes de détection de la machine se déroulent en parallèle avec le traitement NCCO. Ainsi, une fois que l'appel a été pris, c'est de cette manière que les applications peuvent s'attendre à ce que les événements arrivent et soient traités :

Asynchrounous Machine Detection Flow

Dans ce cas, la première action du NCCO commence après l'événement de réponse, alors que la détection de la machine est effectuée en arrière-plan. Si cette action est une action de conversation, cela signifie qu'il n'y a pas de silence dans le canal pendant la détection. De plus, si la première action est terminée, Vonage continuera à traiter d'autres actions du NCCO pendant que la détection est en cours.

Détection standard des machines

Lorsque la détection de machine standard est activée, il est possible pour une application de savoir si une boîte vocale / machine ou un humain a répondu à l'appel. Les développeurs doivent définir l'un des deux comportements possibles lorsqu'une machine est détectée : continue ou hangup.

Par exemple, vous pouvez créer un appel avec détection de machine qui raccroche au cas où une machine répondrait, ou qui récupère un NCCO dans la base de données du answer_url autrement. Dans les deux situations, l'application recevra des événements avec les résultats de la détection afin que vous sachiez si la personne a répondu à l'appel ou non.

Pour ce faire, vous devez envoyer une requête

POST
à https://api.nexmo.com/v1/calls/en utilisant un JWT comme méthode d'autorisation.

Le corps de la demande doit contenir quelque chose comme ceci :

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

Si au lieu de hangup, continue est utilisé, le BCN sera récupéré, mais votre application recevra également l'événement de résultat par l'intermédiaire d'un événement de type Rappel humain / machine à l'URL de votre événement.

Il est important de noter que la détection standard des machines se fait de manière synchrone, ce qui signifie à nouveau que la détection est effectuée avant la récupération et le traitement de la première action NCCO. Pendant la détection, il est impossible d'interagir avec l'utilisateur qui reçoit l'appel.

Pour plus d'exemples sur la manière de passer un appel à l'aide de la Voice API, voir cet extrait de code.

La détection des machines est également possible à partir d'un Action NCCO connectavec les mêmes options de hangup et continue:

{
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "machineDetection": "hangup",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }

Détection avancée des machines

La fonction de détection avancée des machines de Vonage a été conçue pour améliorer à la fois la précision de la détection et l'expérience vocale que Vonage est en mesure de fournir.

Remarque : il s'agit d'une fonction premium, avec un supplément de 0,0070 € par appel pour lequel la détection avancée de la machine est activée.

Pour utiliser la détection avancée des machines lors d'un nouvel appel, vous devez adresser une demande

POST
à https://api.nexmo.com/v1/calls/en utilisant un JWT comme méthode d'autorisation.

Le corps de la demande doit contenir le advanced_machine_detection configuration :

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

Cette opération peut également être effectuée à l'aide d'un Action NCCO connectavec les mêmes options de hangup et 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"
        }
    ]
}

Comme le montrent les exemples, advanced_machine_detection (ou advancedMachineDetection) comporte trois paramètres configurables :

  • behavior - définit ce que la plate-forme Vonage doit faire lorsqu'elle rencontre une machine. Les valeurs possibles sont les suivantes :
    • continue - Si la machine est rencontrée, continuez l'appel.
    • hangup - Si la machine est rencontrée, mettez fin à l'appel.
  • beep_timeout- Cela vous permet de définir la durée d'attente du bip de la messagerie vocale et, dans le cas où il n'est pas reçu, de générer un événement webhook correspondant.
  • mode - en plus du comportement principal de hangup contre continue lors du traitement des appels, il est également possible de définir l'un des trois modes. Ceux-ci sont décrits plus en détail ci-dessous.

default Mode

Les default offre le plus haut niveau de contrôle de l'appel. Ce mode fonctionne de manière asynchrone, ce qui signifie que Vonage commence à traiter les actions NCCO pendant la phase de détection.

A titre d'exemple, supposons que ce NCCO ait été renvoyé à Vonage en réponse à l'extraction du NCCO à partir de l'application 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
  }
]

Lorsque l'appel est pris, ce message commence immédiatement à être diffusé et se répète trois fois pendant que les algorithmes de détection des machines traitent en parallèle le son de la partie distante.

Au cours de cette action de dialogue, un résultat de détection de machine peut se produire, auquel cas un webhook est envoyé à l'application event_url.

Le webhook ressemblera à ceci (avec soit human ou machine comme statut) :

{
  "from": "442079460000",
  "to": "447700900000",
  "status": "human/machine",
  "call_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  }

Indépendamment de l'envoi d'un événement humain ou machine à l'application, cette dernière peut répondre à ce webhook de deux manières. Soit renvoyer un 204 pour continuer, ou renvoyer un 200 avec un nouveau BCN qui remplacera le précédent.

Cela signifie qu'une application peut différencier les comportements. S'il s'agit d'un être humain, l'appel peut se poursuivre avec le même NCCO et effectuer d'autres actions, telles que la demande et le traitement d'une entrée DTMF.

S'il s'agit d'une machine, l'application pourrait attendre le bip et laisser ensuite un message vocal personnalisé. A événement machine avec sub_state beep_start indique le début du bip de la messagerie vocale. En revanche, beep_timeout sub_state indique que le bip n'a pas été reçu après la période d'attente prévue. L'application peut également renvoyer un 200 OK avec un nouveau NCCO, avec le message qui doit être placé dans la boîte vocale.

L'extrait de code suivant, exécuté dans une application, utiliserait une nouvelle action "talk" en cas de détection d'une machine, indiquant que la plateforme doit attendre le bip (à titre d'illustration, dans un exemple réel, un 204 pourrait être utilisé à la place), tandis que si sub_state est beep_start il laisse le message vocal actuel après le bip.

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);
    }

Avec default il est possible de créer des expériences vocales où il n'y a pas de silence au début de l'appel, avec la possibilité de laisser des messages vocaux juste après le bip, évitant ainsi que le message soit tronqué.

detect Mode

Les detect a le même comportement que la détection standard des machines, avec une identification plus précise des machines. Il permet aux développeurs qui souhaitent migrer leur ancienne application vocale, construite sur la base de la détection standard des machines, de le faire avec un minimum de modifications du code.

En règle générale, ce mode doit être utilisé lorsque le comportement souhaité est de raccrocher l'appel en présence d'une machine. Il est synchrone, donc si continue est utilisé à la place de hangup il attendra la détection d'un être humain ou d'une machine pour commencer à traiter le NCCO à partir de la base de données du answer_url s'il s'agit d'un nouvel appel créé à partir de

POST
, ou de l'action suivante dans un NCCO après une action de connexion avec détection.

detect_beep Mode

Les detect_beep s'appuie sur le mode detect en permettant le dépôt d'un message vocal juste après le bip. Ce mode doit être utilisé lorsqu'un continue est souhaitée. Si human est détecté, il se comporte exactement comme detect en ce sens qu'il s'exécute de manière synchrone et attend la fin de la détection de la machine avant de traiter le NCCO ou l'action NCCO suivante.

La principale différence dans ce mode est que lorsqu'une machine est détectée, Vonage attendra que l'utilisateur soit informé de l'état de la machine. beep (ou beep_timeout) avant de traiter l'action NCCO ou l'action NCCO suivante. Cela permet à Vonage de transmettre un message à un humain ou de le laisser dans un message vocal après un bip.