Referencia OCNC

Un objeto de control de llamadas (NCCO) se representa mediante una matriz JSON. Puedes utilizarlo para controlar el flujo de una llamada a la Voice API. Para que tu 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 al respecto en la Descripción general de la Voice API o Ir directamente al «Voice Playground» en el panel de control.

Acciones de la OCNC

El orden de las acciones en el NCCO controla el flujo de la llamada. Las acciones que deben completarse antes de que se pueda ejecutar la siguiente acción son: síncrono. Otras medidas 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í
conectar 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
corriente Enviar archivos de audio a una conversación. Sí, a menos que bargeIn=true
entrada Recoge los dígitos o capta la entrada de voz de la persona a la que estás llamando. Sí
notificar a Envía una solicitud a tu aplicación para realizar un seguimiento del progreso a través de un NCCO Sí
espera Pausar la ejecución durante un número determinado 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.

Ten en cuenta que, en todas las acciones, el eventUrl El parámetro DEBE ser una matriz, aunque solo contenga un único valor.

Registro

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

[
  {
    "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 completada la transcripción de la grabación, se enviará una notificación a un eventUrl. Mediante los ajustes de transcripción puede especificar un eventUrl y language para tus transcripciones. Ten en cuenta que se trata de un servicio de pago; puedes consultar las tarifas exactas en la Precios de Voice API en "Funciones programables".

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

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

Opción Descripción Requerido
format Graba la llamada en un formato concreto. Las opciones son:
  • mp3
  • wav
  • ogg
El valor por defecto es mp3, o wav cuando se graban más de dos canales.		 No
split Graba el audio enviado y el recibido en canales separados de un equipo de grabación estéreo para conversation para activarlo. No
channels El número de canales que se pueden grabar (máximo 32). Si el número de participantes supera channels cualquier participante adicional se añadirá al último canal del archivo. split conversation también debe estar activada. 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 dígito, 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 la misma se envían a event_url. La gama de valores posibles está comprendida entre 3 segundos y 7200 segundos (2 horas). No
beepStart Establecer en 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 Establece un objeto vacío, {}, para utilizar los valores predeterminados o personalizarlos con Ajustes de transcripción No

Ajustes de transcripción

Opción Descripción Requerido
language La lengua (BCP-47 formato) para la grabación que estás transcribiendo. Actualmente es compatible con 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 la transcripción de la grabación de la llamada. Devolverá un valor comprendido entre -1 (sentimiento negativo) y 1 (sentimiento positivo) para cada segmento. El valor por defecto 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

Puedes utilizar el conversation medida para crear conferencias estándar o moderadas, conservando al mismo tiempo el contexto de la comunicación. Utilizando conversation con el mismo name reutiliza el mismo dato guardado Conversación. La primera persona que llama al número virtual asignado a la conversación la crea. Esta acción es sincrónica.

Nota: puedes invitar a un máximo de 200 personas a tu conversación.

Los siguientes ejemplos de NCCO muestran cómo configurar diferentes tipos de conversación. Puedes utilizar el 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"
    }
  }
]

// 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"]
  }
]

Puedes 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 mp3 archivo que se reproducirá para los participantes hasta que comience la conversación. Por defecto, la conversación comienza cuando la primera persona llama al número virtual asociado a tu aplicación Voice. Para reproducir este archivo MP3 antes de que el moderador se una a la conversación, configura startOnEnter a false para todos los usuarios que no sean el moderador. No
startOnEnter El valor por defecto de verdadero garantiza que la conversación comience cuando esta persona se incorpore a ella name. Configurar en false para los asistentes en una conversación moderada. No
endOnExit Especifica si una conversación moderada finaliza cuando el moderador cuelga. Se establece en false 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 Establecer en 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. Puedes anular la URL predeterminada del evento de grabación y el método HTTP predeterminado indicando valores personalizados 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 Consulta la guía para obtener más detalles.		 No
canSpeak Una lista de los UUID de canal en los que se puede escuchar a este participante. Si no se proporciona, todo el mundo podrá escuchar al participante. Si se proporciona una lista vacía, nadie podrá escuchar al participante. No
canHear Una lista de los UUID de las sesiones que este participante puede escuchar. Si no se proporciona, el participante podrá escuchar a todos. Si se proporciona una lista vacía, el participante no podrá escuchar a ningún otro participante. No
mute Establecer en verdadero para silenciar al participante. El audio de este no se transmitirá a la conversación ni se grabará. Al utilizar 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

Puedes utilizar el connect acción para conectar una llamada a puntos finales, como números de teléfono o una extensión de VBC.

Esta acción es sincrónica, después de un conectar 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 diferentes 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"
      }
    ]
  }
]

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

Puede proporcionar una alternativa para las llamadas que no se conectan. Para ello, establezca el parámetro eventType a synchronous y devolver un NCCO del eventUrl si la Llamada entra en alguno de los siguientes estados:

  • timeout - su usuario no respondió a su llamada con ringing_timer segundos
  • failed - la llamada no se ha completado
  • rejected - La llamada fue rechazada
  • unanswered - la llamada no fue contestada
  • busy - la persona a la que se llama estaba atendiendo otra llamada
[
  {
    "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"
                }
            }
        ]
    }
]

Puedes 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 uno 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 Establecer en 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 hay disponibles). randomFromNumber: true no puede utilizarse junto con from. El valor por defecto es false. No
eventType Establecer en synchronous a:
  • hacer el connect acción sincrónica
  • active eventUrl para devolver un NCCO que sustituya al NCCO actual cuando una llamada pase a determinados estados.
 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 comprendido 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. Anulaciones 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 un NCCO que sustituya al NCCO actual cuando se produzca un 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 persona que llamapara 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 puntos finales

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 Establece los dígitos que se envían al usuario en cuanto se responde a la llamada. El * y # se respetan los dígitos. Las pausas se crean con p. Cada pausa dura 500 ms.
onAnswer Un objeto JSON que contiene un campo obligatorio url clave. La URL proporciona un NCCO que se ejecutará en el número al que se está conectando, antes de que dicha llamada se incorpore a tu conversación actual. Opcionalmente, el ringbackTone puede especificarse con un valor de URL que apunte a un archivo ringbackTone que se reproducirá en repetición hasta el persona que llama, para que no oigan solo 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" }. Ten 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 el encabezado, 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 aparece debajo de la tabla.

Ejemplo shaken opción:

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

Aplicación: conectar la llamada a una aplicación compatible con RTC

Valor Descripción
type El tipo de punto final: app para un solicitud.
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 correspondiente al audio que estás reproduciendo en streaming. 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 Conectarse a un WebSocket por ejemplo cabeceras.
authorization Configuración opcional que define cómo el 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 Authorization encabezado (Bearer <JWT>). Utiliza type: "custom" para enviar un Authorization valor del encabezado tal cual. Al utilizar type: "custom", también debes proporcionar value que contenga el valor sin procesar del encabezado que se va a incluir (por ejemplo, Bearer eyJhbGciOi... o ApiKey X9Z...). Al utilizar type: "vonage", value se ignora. Más información 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 El user del URI. Se utilizará junto con el domain propiedad para crear el URI SIP completo. Si configuras esta propiedad, también debes configurar 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 de control de SIP Trunking o el API SIP programable. Los URI previstos en el tronco se utilizarán a lo largo del user propiedad para crear el URI SIP completo. Así, por ejemplo, si el URI en el troncal 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 sin definir. Ten en cuenta que esta propiedad se refiere al nombre de dominio, no a la 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 headers, la 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 «User-to-User», salvo para asegurarse de que utilice caracteres válidos y de que el contenido no supere el número máximo de caracteres permitido (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 los webhooks de la Voice API.

VBC: la extensión 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.

Charla

El 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 voz, lo que permite ajustar el tono, la pronunciación y combinar texto en varios idiomas. Las etiquetas SSML están basadas en XML y se envían integradas en la cadena JSON.

Por defecto, la acción «talk» es síncrona. Sin embargo, si se configura 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"
  }
]

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

Puedes 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 Establecer en 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 mantendrá true (aunque bargeIn: false se establece en una acción siguiente) hasta que un input se produce una 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 Establecer en true 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.

Transmisión

El 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 posterior en la pila de la 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"]
  }
]

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

Puedes utilizar las siguientes opciones para controlar un corriente 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 de la transmisión en el intervalo -1 >= nivel <= 1, con una precisión de 0,1. El valor por defecto es 0. No
bargeIn Establecer en 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 de Stream más y, a continuación, en la siguiente acción que no sea de Stream en la pila NCCO debe ser un input acción. El valor por defecto es false.

Una vez bargeIn se establece en true se mantendrá true (aunque bargeIn: false se establece en una acción siguiente) hasta que un input se produce una acción.		 No
loop El número de veces audio se repite antes de que se cierre la llamada. El valor por defecto es 1. Configurar en 0 para que se repita infinitamente. No

El flujo de audio al que se hace referencia debe ser un archivo en formato MP3 o WAV. Si tienes problemas para reproducir el archivo, codifícalo según las siguientes especificaciones técnicas: ¿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 encabezado en la respuesta de la URL con los valores adecuados.

Cache-Control: public, max-age=360000

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

Parámetros de retorno del flujo

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

Entrada

Puedes utilizar el 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 conectar NCCO que desvía la llamada a su departamento de ventas.

El siguiente ejemplo de 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 sigue cualquier acción que tenga un bargeIn propiedad (p. ej., 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 se pueden utilizar para controlar un input acción:

Opción Descripción Requerido
type Tipo de entrada aceptable, puede establecerse como [ "dtmf" ] solo para entrada DTMF, [ "speech" ] solo para ASR, o [ "dtmf", "speech" ] para ambos. Sí
dtmf Ajustes DTMF. No
speech Configuración del reconocimiento de voz. No
mode Modo de procesamiento de entradas, actualmente aplicable únicamente a DTMF. Los valores válidos son: synchronous (el valor por defecto) y asynchronous. Si se ajusta a asynchronous, todos 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 marcados por el destinatario de la llamada a esta URL 1) después de timeOut pausa en la actividad o cuando # se pulsa una tecla DTMF o 2) cuando el usuario deja 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 de la función llamada se envía a la eventUrl punto final del webhook timeOut segundos después de la última acción. El valor por defecto es 3. Max tiene 10 años. No
maxDigits El número de dígitos que el usuario puede introducir. El valor máximo es 20por defecto es 4 dígitos. No
submitOnHash Establecer en 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 identificador único del tramo de la llamada del que el usuario debe capturar el audio, definido como una matriz con un único elemento. Por defecto, es el primer tramo de la llamada. 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
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 Establecer en 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 del habla. Valor entero en el que 10 representa una sensibilidad baja y 100, la sensibilidad máxima. El valor por defecto es 90. No
provider Cadena compuesta por el nombre del proveedor. Valor admitido: google. Si provider está establecido, providerOptions debe estar presente (puede ser {} o null). Si provider se omite, providerOptions puede omitirse. Más información aquí. No
providerOptions Objeto JSON con las opciones personalizadas para el proveedor de voz a texto. Si provider se omite, providerOptions puede omitirse. Si provider está establecido, providerOptions debe estar presente y puede ser un objeto vacío {} o null. Más información aquí. No

Algunos parámetros heredados (por ejemplo, language y context) están documentados en el Guía conceptual de voz a texto.

El siguiente ejemplo muestra los parámetros enviados al eventUrl Webhook para la entrada de 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 se deben enviar los eventos. Si devuelves un NCCO al recibir una notificación, este sustituirá al NCCO actual. Sí
eventMethod El método HTTP que se debe utilizar al enviar payload a tu eventUrl. No

Ajustes de voz

Opción Descripción Requerido
language La lengua (BCP-47 formato) para las indicaciones. 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

Puedes utilizar el wait Acción para añadir un periodo de espera y pausar la ejecución del NCCO en curso durante un número determinado 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 que te avise 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 de 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"
  }
]

Puedes 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

El transfer La acción es sincrónica. Puedes utilizarla para trasladar los tramos de la llamada de una conversación actual a otra conversación ya existente. La transfer Esta acción pone fin a la conversación actual, y el NCCO de la conversación de destino sigue controlando el comportamiento de esta. Todas las ramificaciones de la conversación actual se transfieren a la conversación de destino, respetando la configuración de audio (canHear, canSpeak, mute) si se facilitan.

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" ]
   }
   ...
]

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

Opción Descripción Requerido
conversation_id ID de conversación de destino, definido como cadena. Sí
canHear Una lista de los UUID de las «leg» que este participante puede escuchar, definida como una matriz de cadenas de caracteres. Si no se proporciona, el participante podrá escuchar a todo el mundo. Si se proporciona una lista vacía, el participante no podrá escuchar a ningún otro participante. No
canSpeak Una lista de los UUID de los canales en los que este participante puede ser escuchado, definida como una matriz de cadenas. Si no se proporciona, el participante podrá ser escuchado por todo el mundo. Si se proporciona una lista vacía, el participante no podrá ser escuchado por nadie. No
mute Establece el valor en «true» para silenciar al participante. El audio de este no se reproducirá en la conversación ni se grabará. Al utilizar canSpeakEl mute no es compatible. No