Referencia OCNC

Un objeto de control de llamada (NCCO) está representado por una matriz JSON. Puede utilizarlo para controlar el flujo de una llamada Voice API. Para que su NCCO se ejecute correctamente, los objetos JSON deben ser válidos.

Mientras desarrollas y pruebas las NCCO, puedes utilizar Voice Playground para probarlas de forma interactiva. Puede Más información en la descripción general de la Voice API. o ir directamente a la zona de juegos de voz en el salpicadero.

Acciones de la OCNC

El orden de las acciones en la OCN controla el flujo de la llamada. Las acciones que deben completarse antes de que pueda ejecutarse la siguiente son síncrono. Otras acciones son asíncrono. Es decir, se supone que continúan sobre las acciones siguientes hasta que se cumple una condición. Por ejemplo, una record termina cuando el endOnSilence se cumple. Cuando se completan todas las acciones de la OCNC, finaliza la Convocatoria.

Las acciones de la OCNC y las opciones y tipos de cada acción son:

Acción Descripción Sincrónico
registro Toda o parte de una convocatoria No
conversación Crear o unirse a un Conversación Sí
conecte A un punto final conectable, como un número de teléfono o una extensión VBC. Sí
hable Enviar voz sintetizada a una Conversación. Sí, a menos que bargeIn=true
flujo Enviar archivos de audio a una conversación. Sí, a menos que bargeIn=true
entrada Recoge dígitos o captura la voz de la persona a la que llamas. Sí
notificar a Envíe una solicitud a su aplicación para seguir el progreso a través de una OCN Sí
espere Pausa la ejecución durante un número especificado de segundos Sí
transferencia Desplazar los tramos de llamada de una conversación en curso a otra conversación existente Sí

Nota: Conectar una llamada entrante proporciona un ejemplo de cómo enviar tus NCCO a Vonage luego de que se inicie una llamada o conferencia.

Tenga en cuenta que en todas las acciones, el eventUrl DEBE ser una matriz, aunque sólo contenga un valor.

Registro

Utiliza el record para grabar una llamada o parte de ella:

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

La acción de registro es asíncrona. Puede definir una condición sincrónica - endOnSilence, timeOut o endOnKey - para finalizar la grabación cuando se cumpla. Si no se establece ninguna condición, la grabación funcionará de forma asíncrona y continuará instantáneamente con la siguiente acción mientras sigue grabando la llamada. La grabación sólo finalizará y enviará el evento correspondiente cuando finalice la llamada. Esto se utiliza para escenarios similares a la monitorización de llamadas.

Puede transcribir una grabación utilizando la función transcription opción. Una vez finalizada la transcripción de la grabación, se enviará una devolución de llamada a un eventUrl. Mediante los ajustes de transcripción puede especificar un eventUrl y language para sus transcripciones. Tenga en cuenta que este servicio es de pago; las tarifas exactas pueden consultarse en la página Precios de Voice API en "Funciones programables".

Para obtener información sobre el flujo de trabajo a seguir, consulte Grabación.

Puede utilizar las siguientes opciones para controlar un record acción:

Opción Descripción Requerido
format Graba la Llamada en un formato específico. Las opciones son:
  • mp3
  • wav
  • ogg
El valor por defecto es mp3o wav al grabar más de 2 canales.		 No
split Graba el audio enviado y el recibido en canales separados de un equipo de grabación estéreo para conversation para permitirlo. No
channels El número de canales a grabar (máximo 32). Si el número de participantes es superior a channels cualquier participante adicional se añadirá al último canal del archivo. split conversation también debe estar activado. No
endOnSilence Detener la grabación tras n segundos de silencio. Una vez detenida la grabación, los datos de grabación se envían a event_url. El rango de valores posibles es 3<=endOnSilence<=10. No
endOnKey Detiene la grabación cuando se pulsa un dígito en el microteléfono. Los valores posibles son: *, # o cualquier cifra, por ejemplo 9. No
timeOut La duración máxima de una grabación en segundos. Una vez detenida la grabación, los datos de grabación se envían a event_url. La gama de valores posibles está comprendida entre 3 segundos y 7200 segundos (2 horas). No
beepStart Ajustar a true para reproducir un pitido cuando se inicia una grabación. No
eventUrl La URL del punto final del webhook que se llama de manera asincrónica cuando finaliza una grabación. Si la grabación del mensaje está alojada en Vonage, este webhook contiene el archivo URL que necesita para descargar la grabación y otros metadatos. No
eventMethod El método HTTP utilizado para realizar la solicitud a eventUrl. El valor por defecto es POST. No
transcription [Beta] Establece un objeto vacío, {}para utilizar los valores por defecto o personalizarlos con Ajustes de transcripción No

Ajustes de transcripción

Opción Descripción Requerido
language La lengua (BCP-47 ) de la grabación que estás transcribiendo. Actualmente admite los mismos idiomas que la grabación automática de voz, y hay una lista disponible aquí. No
eventUrl La URL del punto final del webhook que se llama de forma asíncrona cuando finaliza una transcripción. No
eventMethod El método HTTP que Vonage utiliza para realizar la solicitud a eventUrl. El valor por defecto es POST. No
sentimentAnalysis [Vista previa para desarrolladores] Realiza un análisis de sentimiento en los segmentos de transcripción de la grabación de la llamada. Devolverá un valor entre -1 (sentimiento negativo) y 1 (sentimiento positivo) para cada segmento. El valor predeterminado es false. No

Nota: hay un límite máximo de 2 horas para transcribir llamadas de voz.

Parámetros de devolución de registros

Véase el Referencia de Webhook para los parámetros de registro o transcripción que se devuelven al eventUrl.

Conversación

Puede utilizar la función conversation para crear conferencias estándar o moderadas, preservando el contexto de comunicación. Utilización de conversation con el mismo name reutiliza la misma persistencia Conversación. La primera persona que llama al número virtual asignado a la conversación la crea. Esta acción es sincrónica.

NotaPuedes invitar hasta 200 personas a tu Conversación.

Los siguientes ejemplos de NCCO muestran cómo configurar distintos tipos de Conversación. Puede utilizar las opciones answer_url para asegurarse de que envía una OCN a los participantes y otra al moderador.

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

Puede utilizar las siguientes opciones para controlar un conversación acción:

Opción Descripción Requerido
name El nombre de la sala de Conversación. Los nombres están espaciados hasta el nivel de aplicación y región. Sí
musicOnHoldUrl Una URL a la página mp3 a los participantes hasta que comience la conversación. Por defecto, la conversación se inicia cuando la primera persona llama al número virtual asociado a tu aplicación Voz. Para transmitir este mp3 antes de que el moderador se una a la conversación, configure startOnEnter a falso para todos los usuarios que no sean el moderador. No
startOnEnter El valor por defecto de verdadero garantiza que la conversación se inicie cuando este interlocutor se una a la conversación name. Ajustar a falso para los asistentes en una conversación moderada. No
endOnExit Especifica si una conversación moderada finaliza cuando el moderador cuelga. Se establece en falso por defecto, lo que significa que la conversación sólo finaliza cuando cuelga el último participante que queda, independientemente de si el moderador sigue o no en la llamada. Configurar endOnExit a verdadero para terminar la conversación cuando el moderador cuelgue. No
record Ajustar a verdadero para grabar esta conversación. Para las conversaciones estándar, las grabaciones comienzan cuando uno o más asistentes se conectan a la conversación. Para las conversaciones moderadas, las grabaciones comienzan cuando el moderador se conecta. Es decir, cuando se ejecuta un NCCO para la conversación nombrada donde startOnEnter se establece en verdadero. Cuando finaliza la grabación, la URL desde la que se descarga la grabación se envía a la URL del evento. Puede anular la URL de evento de grabación predeterminada y el método HTTP predeterminado proporcionando direcciones eventUrl y eventMethod opciones en el conversation definición de acción.
Por defecto, el audio se graba en formato MP3. Consulte la grabación para más detalles.		 No
canSpeak Una lista de UUIDs de pata por los que este participante puede ser escuchado. Si no se proporciona, el participante podrá ser escuchado por todos. Si se proporciona una lista vacía, el participante no será escuchado por nadie. No
canHear Una lista de UUID de pierna que este participante puede oír. Si no se proporciona, el participante puede oír a todos. Si se proporciona una lista vacía, el participante no oirá a ningún otro participante. No
mute Ajustar a verdadero para silenciar al participante. El audio del participante no se reproducirá en la conversación y no se grabará. Cuando utilice canSpeakEl mute no es compatible. No
transcription Configuración de la transcripción. Si se presenta (incluso como objeto vacío), se activa la transcripción. El parámetro de registro debe estar ajustado a verdadero. Véase Ajustes de transcripción arriba para más detalles. No

Conectar

Puede utilizar la función connect acción para conectar una llamada a puntos finales como números de teléfono o una extensión VBC.

Esta acción es sincrónica, después de un conecte se procesa la siguiente acción de la pila NCCO. Una acción de conexión finaliza cuando el punto final al que se llama está ocupado o no está disponible. Los puntos finales se llaman secuencialmente anidando acciones de conexión.

Los siguientes ejemplos de NCCO muestran cómo configurar distintos tipos de conexiones.

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

Puede utilizar las siguientes opciones para controlar un connect acción:

Opción Descripción Requerido
endpoint Conjunto de endpoint a los que conectarse. Actualmente admite un máximo de una endpoint objeto. Tipos de terminales disponibles. Sí
from Un número en E.164 que identifica a la persona que llama. Este debe ser uno de tus números virtuales de Vonage si te estás conectando a un teléfono real, ya que de lo contrario la llamada no se conectará. No
randomFromNumber Ajustar a true para utilizar un número de teléfono aleatorio como from. El número se seleccionará de la lista de números asignados a la aplicación actual. La aplicación intentará utilizar números del mismo país que el de destino (si están disponibles). randomFromNumber: true no puede utilizarse junto con from. El valor por defecto es false. No
eventType Ajustar a synchronous a:
  • hacer el connect acción sincrónica
  • active eventUrl para devolver una OCN que anula la OCN actual cuando una llamada pasa a estados específicos.
 No
timeout Si la llamada no se contesta, establece el número de segundos antes de que Vonage deje de sonar endpoint. Debe ser un número entero entre 1 y 120. El valor por defecto es 60. No
limit Duración máxima de la llamada en segundos. El valor por defecto y máximo es 7200 segundos (2 horas). No
machineDetection Configura el comportamiento cuando Vonage detecta que un destino es un contestador automático. Configúralo en:
  • continue - Vonage envía una solicitud HTTP a event_url con el evento Call machine
  • hangup - Finalizar la llamada
 No
advancedMachineDetection Configura el comportamiento de la detección avanzada de máquinas de Vonage. Anula machineDetection si ambos están activados. Véase el Referencia API para conocer los parámetros. Esta función es de pago; las tarifas exactas pueden consultarse en la página Precios de Voice API en "Funciones programables". No
eventUrl Establezca el punto final de webhook que Vonage llama de forma asíncrona en cada uno de los posibles Llamar a los Estados. Si eventType se establece en synchronous el eventUrl puede devolver una NCCO que sustituya a la NCCO actual cuando se agote el tiempo de espera. No
eventMethod El método HTTP que Vonage utiliza para realizar la solicitud a eventUrl. El valor por defecto es POST. No
ringbackTone Un valor de URL que apunta a un ringbackTone que se reproducirá en repetición hasta el llamantepara que no oigan el silencio. El ringbackTone dejará de reproducirse automáticamente cuando la llamada esté completamente conectada. No se recomienda utilizar este parámetro cuando se conecte a un punto final telefónico, ya que el operador proporcionará su propio ringbackTone. Ejemplo: "ringbackTone": "http://example.com/ringbackTone.wav". No

Tipos y valores de los extremos

Teléfono (RTPC) - números de teléfono en formato E.164

Valor Descripción
type El tipo de punto final: phone para un punto final RTC.
number El número de teléfono al que conectarse en E.164 formato.
dtmfAnswer Configure los dígitos que se envían al usuario en cuanto se contesta la Llamada. La dirección * y # se respetan los dígitos. Las pausas se crean con p. Cada pausa es de 500 ms.
onAnswer Un objeto JSON que contiene url clave. La URL sirve para ejecutar una NCCO en el número al que se está conectando, antes de que esa llamada se una a la conversación existente. Opcionalmente, la ringbackTone puede especificarse con un valor de URL que apunte a un archivo ringbackTone que se reproducirá en repetición hasta el llamantepara que no oigan sólo el silencio. El ringbackTone dejará de sonar automáticamente cuando la llamada esté totalmente conectada. Ejemplo: {"url":"https://example.com/answer", "ringbackTone":"http://example.com/ringbackTone.wav" }. Tenga en cuenta que la clave ringback sigue siendo compatible.
shaken Para los clientes de Vonage a quienes la FCC les exige firmar sus propias llamadas a EE. UU., ofrecemos la opción de realizar llamadas de Voice API usando tu propia firma.

Esta función sólo está disponible previa solicitud. Las llamadas con una firma no válida serán rechazadas. Póngase en contacto con nosotros para obtener más información.

Al utilizar esta opción, debes colocar el contenido del encabezado de identidad STIR/SHAKEN que Vonage debe utilizar para esta llamada. El formato esperado consiste en:
  • un JWT con la cabecera, la carga útil y la firma
  • un info con un enlace al certificado
  • un alg (algoritmo) parámetro que indica el tipo de cifrado utilizado
  • a ppt (tipo de pasaporte) que debe ser shaken
Consulte el ejemplo que figura debajo de la tabla.

Ejemplo shaken opción:

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

App - Conecta la llamada a una aplicación compatible con RTC

Valor Descripción
type El tipo de punto final: app para un aplicación.
user El nombre de usuario del usuario al que conectarse. Este nombre de usuario debe haber sido añadido como usuario.

WebSocket - el WebSocket al que conectarse

Valor Descripción
type El tipo de punto final: websocket para un WebSocket.
uri La URI del websocket al que se está transmitiendo.
content-type El tipo de medio de Internet para el audio que está transmitiendo. Los valores posibles son: audio/l16;rate=16000 o audio/l16;rate=8000.
headers Un objeto JSON que contiene los metadatos que desee. Véase conexión a un websocket por ejemplo cabeceras.
authorization Configuración opcional que define cómo Authorization La cabecera HTTP se establece en el handshake de apertura de WebSocket. Utilice type: "vonage" para que la Voice API incluya el mismo JWT que se utiliza para los webhooks firmados en el archivo Authorization encabezado (Bearer <JWT>). Utilice type: "custom" para enviar un Authorization literalmente. Al utilizar type: "custom"también debe proporcionar value que contiene el valor de cabecera en bruto que debe incluirse (por ejemplo, Bearer eyJhbGciOi... o ApiKey X9Z...). Cuando utilice type: "vonage", value se ignora. Leer más aquí.

SIP - el punto final SIP al que conectarse

Valor Descripción
type El tipo de punto final: sip para SIP.
uri La URI SIP del punto final al que se está conectando en el formato sip:rebekka@sip.example.com. Para utilizar TLS y/o SRTPincluyen, respectivamente transport=tls o media=srtp a la URL con el punto y coma ; como delimitador, por ejemplo: sip:rebekka@sip.example.com;transport=tls;media=srtp. Tenga en cuenta que esta propiedad es mutuamente excluyente con user y domain.
user En user del URI. Se utilizará junto con el domain para crear el URI SIP completo. Si establece esta propiedad, también debe establecer domain y dejar uri Desactivado.
domain El identificador de un tronco creado mediante el panel de control. Debe tratarse de un dominio aprovisionado correctamente mediante la función Panel SIP Trunking o el API SIP programable. Los URI previstos en el tronco se utilizarán a lo largo del user para crear el URI SIP completo. Así, por ejemplo, si el URI en el tronco es: sip.example.com y user es example_userVonage enviará la llamada a example_user@sip.example.com. Si establece esta propiedad, debe dejar uri unset. Tenga en cuenta que esta propiedad se refiere al nombre de dominio, no al URI del dominio.
headers key => value pares de cadenas que contienen cualquier metadato que necesite, por ejemplo { "location": "New York City", "occupation": "developer" }. Las cabeceras se transmiten como parte de la SIP INVITE como X-key: value cabeceras. Así, en el ejemplo, se envían estas cabeceras: X-location: New York City y X-occupation: developer.
standardHeaders Un objeto JSON que contiene una única clave User-to-User. Se utiliza para transmitir información de usuario a usuario si el proveedor lo admite, de acuerdo con RFC 7433. A diferencia de headersla clave no irá precedida de X-ya que está normalizado. Por ejemplo: { "User-to-User": "342342ef34;encoding=hex" }. Vonage no validará el contenido del encabezado de usuario a usuario, excepto para asegurarse de que utilice caracteres válidos y que el contenido esté dentro de la cantidad máxima de caracteres permitidos (256).

Para saber cómo su aplicación puede recibir y gestionar cabeceras SIP personalizadas, consulte la siguiente página en SIP programable. Si desea saber cómo su aplicación puede enviar cabeceras SIP, vaya a la sección Guía de referencia de Voice API Webhooks.

VBC: la extensión de Vonage Business Cloud (VBC) para conectarse a

Valor Descripción
type El tipo de punto final: vbc para una extensión VBC.
extension la extensión VBC a la que conectar la llamada.

Hable con

En talk La acción envía voz sintetizada a una Conversación.

El texto proporcionado en la acción talk puede ser simple o formateado utilizando SSML. Las etiquetas SSML proporcionan instrucciones adicionales al sintetizador de texto a voz que permiten establecer el tono, la pronunciación y combinar texto en varios idiomas. Las etiquetas SSML se basan en XML y se envían en línea en la cadena JSON.

Por defecto, la acción de hablar es sincrónica. Sin embargo, si establece bargeIn a verdadero debe establecer un entrada más adelante en la pila NCCO. Los siguientes ejemplos de NCCO muestran cómo enviar un mensaje de voz sintetizada a una Conversación o Llamada:

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

Puede utilizar las siguientes opciones para controlar un hable acción:

Opción Descripción Requerido
text Una cadena de hasta 1.500 caracteres (excluyendo las etiquetas SSML) que contiene el mensaje a sintetizar en la Llamada o Conversación. Una sola coma en text añade una breve pausa al discurso sintetizado. Para añadir una pausa más larga a break en SSML. Para utilizar SSML debe encerrar el texto en una etiqueta speak elemento. Sí
bargeIn Ajustar a true para que esta acción finalice cuando el usuario interactúe con la aplicación, ya sea con entrada de voz DTMF o ASR. Utilice esta función para que los usuarios puedan elegir una opción sin tener que escuchar todo el mensaje en su Respuesta de voz interactiva (IVR). Si configura bargeIn a true la siguiente acción no verbal en la pila NCCO debe ser un input acción. El valor por defecto es false.

Una vez bargeIn se establece en true se quedará true (aunque bargeIn: false se establece en una acción siguiente) hasta que un input se encuentra la acción		 No
loop El número de veces text se repite antes de que se cierre la Llamada. El valor por defecto es 1. Establézcalo en 0 para que se repita infinitamente. No
level El nivel de volumen al que se reproduce el discurso. Puede ser cualquier valor entre -1 a 1 con 0 por defecto. No
language La lengua (BCP-47 formato) para el mensaje que está enviando. Por defecto: en-US. Los valores posibles figuran en la lista Guía de texto a voz. No
style El estilo vocal (rango vocal, tesitura y timbre). Por defecto: 0. Los valores posibles figuran en la lista Guía de texto a voz. No
premium Ajustar a true para utilizar la versión premium del estilo especificado si está disponible, de lo contrario se utilizará la versión estándar. El valor por defecto es false. Encontrará más información sobre Premium Voices en la sección Guía de texto a voz. No

Parámetros de retorno de Talk

Véase Referencia de Webhook para los parámetros que se devuelven al eventUrl.

Corriente

En stream le permite enviar un flujo de audio a una Conversación

Por defecto, la acción de flujo es sincrónica. Sin embargo, si establece bargeIn a verdadero debe establecer un entrada acción más adelante en la pila NCCO.

El siguiente ejemplo NCCO muestra cómo enviar un flujo de audio a una Conversación o Llamada:

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

Puede utilizar las siguientes opciones para controlar un flujo acción:

Opción Descripción Requerido
streamUrl Una matriz que contiene una única URL a un archivo de audio mp3 o wav (16 bits) para transmitir a la Llamada o Conversación. Sí
level Establece el nivel de audio del flujo en el rango -1 >=nivel<=1 con una precisión de 0,1. El valor por defecto es 0. No
bargeIn Ajustar a true para que esta acción finalice cuando el usuario interactúe con la aplicación, ya sea con entrada de voz DTMF o ASR. Utilice esta función para que los usuarios puedan elegir una opción sin tener que escuchar todo el mensaje en su Respuesta vocal interactiva (IVR) ). Si ajusta bargeIn a true en una acción Stream más y, a continuación, en la siguiente acción no Stream de la pila NCCO debe ser un input acción. El valor por defecto es false.

Una vez bargeIn se establece en true se quedará true (aunque bargeIn: false se establece en una acción siguiente) hasta que un input acción.		 No
loop El número de veces audio se repite antes de cerrar la Llamada. El valor por defecto es 1. Ajustar a 0 para hacer un bucle infinito. No

El flujo de audio al que se hace referencia debe ser un archivo en formato MP3 o WAV. Si tiene problemas para reproducir el archivo, codifíquelo según la siguiente especificación técnica: ¿Qué tipo de archivos de audio pregrabados puedo utilizar?

Si reproduce el mismo archivo de audio varias veces, por ejemplo utilizando la misma grabación en muchas llamadas, considere la posibilidad de añadir un Cache-Control a la respuesta URL con los valores adecuados.

Cache-Control: public, max-age=360000

Esto permite que Vonage almacene en caché tu archivo de audio en lugar de descargarlo cada vez, lo que puede mejorar significativamente el rendimiento y la experiencia del usuario. El almacenamiento en caché es compatible con URL HTTP y HTTPS.

Parámetros de retorno del flujo

Véase Referencia de Webhook para los parámetros que se devuelven al eventUrl.

Entrada

Puede utilizar la función input para recopilar dígitos o la entrada de voz de la persona a la que llamas. Esta acción es sincrónica, Vonage procesa la entrada y la reenvía en el parámetros enviado al eventUrl que configure en su solicitud. Su webhook endpoint debería devolver otro NCCO que reemplace al NCCO existente y controle la Llamada basándose en la entrada del usuario. Podría utilizar esta funcionalidad para crear una Respuesta de Voz Interactiva (IVR). Por ejemplo, si el usuario pulsa 4 o dice "Ventas", se devuelve un conecte NCCO que desvía la llamada a su departamento de ventas.

El siguiente ejemplo NCCO muestra cómo configurar un punto final 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" ]
    }
  }
]

El siguiente ejemplo de NCCO muestra cómo utilizar bargeIn para permitir que un usuario interrumpa un talk acción. Tenga en cuenta que un input acción debe seguir cualquier acción que tenga un bargeIn (por ejemplo talk o 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" ]
    }	
  }
]

Las siguientes opciones pueden utilizarse para controlar un input acción:

Opción Descripción Requerido
type Tipo de entrada aceptable, puede establecerse como [ "dtmf" ] sólo para entrada DTMF, [ "speech" ] sólo para ASR, o [ "dtmf", "speech" ] para ambos. Sí
dtmf Ajustes DTMF. No
speech Configuración del reconocimiento de voz. No
mode Modo de tratamiento de las entradas, actualmente sólo aplicable a DTMF. Los valores válidos son synchronous (por defecto) y asynchronous. Si se ajusta a asynchronoustodos Ajustes DTMF debe dejarse en blanco. En modo asíncrono, los dígitos se envían de uno en uno al webhook de eventos en tiempo real. En el modo synchronous se controla mediante la configuración DTMF y las entradas se envían por lotes. No
eventUrl Vonage envía los dígitos pulsados por el destinatario de la llamada a esta URL 1) tras timeOut pausa en la actividad o cuando # se pulsa para DTMF o 2) después de que el usuario deje de hablar o 30 segundos de habla para la entrada de voz. No
eventMethod El método HTTP utilizado para enviar información de eventos a event_url El valor por defecto es POST. No

Ajustes de entrada DTMF

Nota: Estos ajustes no se aplican si el mode se establece en asynchronous.

Opción Descripción Requerido
timeOut El resultado de la actividad del destinatario de la llamada se envía a la aplicación eventUrl punto final de webhook timeOut segundos después de la última acción. El valor por defecto es 3. El máximo es 10. No
maxDigits El número de dígitos que el usuario puede pulsar. El valor máximo es 20por defecto es 4 dígitos. No
submitOnHash Ajustar a true para que la actividad del receptor de la llamada se envíe a su punto final de webhook en eventUrl después de pulsar #. Si # no se pulsa el resultado se presenta después de timeOut segundos. El valor por defecto es false. Es decir, el resultado se envía a su punto final webhook después de timeOut segundos. No

Configuración del reconocimiento de voz

Opción Descripción Requerido
uuid El ID único del tramo de la llamada para que el usuario capture el discurso, definido como una matriz con un único elemento. El primer tramo unido de la llamada por defecto. No
endOnSilence Controla el tiempo que el sistema esperará después de que el usuario deje de hablar para decidir que la entrada se ha completado. El valor por defecto es 2.0 (segundos). El rango de valores posibles está comprendido entre 0.4 segundos y 10.0 segundos. No
language Idioma previsto del discurso del usuario. Formato: BCP-47. Predeterminado: en-US. Lista de idiomas admitidos. No
context Matriz de pistas (cadenas) para mejorar la calidad del reconocimiento si se esperan determinadas palabras del usuario. No
startTimeout Controla el tiempo que el sistema esperará a que el usuario empiece a hablar. El rango de valores posibles está entre 1 segundo y 60 segundos. El valor por defecto es 10. No
maxDuration Controla la duración máxima del habla (desde que el usuario empieza a hablar). El valor por defecto es 60 (segundos). El rango de valores posibles está entre 1 y 60 segundos. No
saveAudio Ajustar a true por lo que la grabación de entrada de voz (recording_url) se envía a su punto final de webhook en eventUrl. El valor por defecto es false. No
sensitivity Sensibilidad de audio utilizada para diferenciar el ruido de la voz. Un valor entero donde 10 representa la sensibilidad baja y 100 la sensibilidad máxima. Por defecto es 90. No

El siguiente ejemplo muestra los parámetros enviados al eventUrl webhook para entrada 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"
}

El siguiente ejemplo muestra los parámetros enviados de vuelta al eventUrl webhook para entrada de voz:

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

Entrada Parámetros de retorno

Véase Referencia de Webhook para los parámetros de entrada que se devuelven al eventUrl.

Notificar a

Utiliza el notify para enviar una carga útil personalizada a la URL del evento. Su punto final de webhook puede devolver otra NCCO que sustituya a la NCCO existente o devolver una carga útil vacía, lo que significa que la NCCO existente seguirá ejecutándose.

[
  {
    "action": "notify",
    "payload": {
      "foo": "bar"
    },
    "eventUrl": [
      "https://example.com/webhooks/event"
    ],
    "eventMethod": "POST"
  }
]
Opción Descripción Requerido
payload El cuerpo JSON que se enviará a la URL del evento. Sí
eventUrl La URL a la que enviar los eventos. Si devuelve una OCN al recibir una notificación, sustituirá a la OCN actual. Sí
eventMethod El método HTTP que se utilizará para enviar payload a su eventUrl. No

Ajustes de voz

Opción Descripción Requerido
language La lengua (BCP-47 formato) para los avisos. Por defecto: en-US. Los valores posibles figuran en la lista Guía de texto a voz. No
style El estilo vocal (rango vocal, tesitura y timbre). Por defecto: 0. Los valores posibles figuran en la lista Guía de texto a voz. No

Espere

Puede utilizar la función wait acción para añadir un periodo de espera y pausar la ejecución de la OCN en ejecución durante un número especificado de segundos.

La acción es sincrónica. El periodo de espera comienza cuando se ejecuta la acción de espera en la OCN y finaliza tras el valor de tiempo de espera proporcionado o por defecto. En ese momento, la OCNC reanuda la ejecución. La dirección timeout es un valor flotante. Los valores válidos van de 0,1 segundos a 7200 segundos. Los valores por debajo de 0,1 son por defecto 0,1 segundos, y los valores por encima de 7200 son por defecto 7200 segundos. Si no se especifica, el valor por defecto es 10 segundos.

Nota: si necesitas una llamada de retorno informando de que la acción de espera ha finalizado, añade una acción de notificación después de la acción de espera.

El siguiente ejemplo NCCO muestra cómo ejecutar la acción de espera:

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

Puede utilizar las siguientes opciones para controlar un wait acción:

Opción Descripción Requerido
timeout Controla la duración del periodo de espera antes de ejecutar la siguiente acción en la OCNC. Este parámetro es un valor flotante. Los valores válidos van de 0,1 segundos a 7200 segundos. Los valores por debajo de 0,1 son por defecto 0,1 segundos, y los valores por encima de 7200 son por defecto 7200 segundos. El valor por defecto es 10. No

Transferencia

En transfer es sincrónica. Puede utilizarla para mover los tramos de llamada de una conversación actual a otra conversación existente. La dirección transfer es terminal para la conversación actual, y la OCN de la conversación de destino sigue controlando el comportamiento de la conversación de destino. Todos los tramos de la conversación actual se transfieren a la conversación de destino, respetando los ajustes de audio (canHear, canSpeak, mute) si se proporcionan.

El siguiente ejemplo NCCO muestra cómo ejecutar la acción de transferencia:

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

Puede utilizar las siguientes opciones para controlar una acción de transferencia:

Opción Descripción Requerido
conversation_id ID de la conversación de destino, definido como cadena. Sí
canHear Una lista de UUID de pierna que este participante puede oír, definida como una matriz de cadenas. Si no se proporciona, el participante puede oír a todos. Si se proporciona una lista vacía, el participante no oirá a ningún otro participante. No
canSpeak Una lista de UUIDs de pata por los que este participante puede ser escuchado, definida como una matriz de cadenas. Si no se proporciona, el participante puede ser escuchado por todos. Si se proporciona una lista vacía, el participante no será escuchado por nadie. No
mute Establézcalo como true para silenciar al participante. El audio del participante no se reproducirá en la conversación y no se grabará. Si utiliza canSpeakEl mute no es compatible. No