Viaje de voz

En esta guía, usted implementará el siguiente escenario de centro de contacto:

  • El usuario llama a tu número de Vonage,
  • Se lee el saludo inicial y el usuario elige una opción del menú que se le propone,
  • El usuario está conectado a un agente,
  • Una vez que el agente cierra la llamada, el usuario es transferido a una encuesta de satisfacción del cliente.

Para comprender mejor el flujo, consulte Flujo de llamadas.

Requisitos previos

Para completar esta guía, necesitas:

  • A Account de Vonage,
  • En CLI de Vonage instalado y configurado,
  • ngrok - para que tu servidor web de desarrollo sea accesible a los servidores de Vonage a través de Internet,
  • Node.JS instalado,
  • dos dispositivos telefónicos de llamada con números RTPC asignados - "teléfono del usuario" y "teléfono del agente", por ejemplo, dos teléfonos móviles o una aplicación con capacidad de llamada como Vonage Empresas app.

Instalar las dependencias

Instale el express marco de aplicaciones web y body-parser paquetes:

npm install express body-parser

Crear una aplicación de voz

Utilice la CLI para crear una aplicación Voice API con el comando webhooks que se encargará de contestar una llamada a tu número de Vonage (/webhooks/voice/answer) y el registro de eventos de llamada (/webhooks/voice/event), respectivamente.

Estos webhooks deben ser accesibles por los servidores de Vonage, por lo que en esta guía utilizarás ngrok para exponer su entorno de desarrollo local a la Internet pública. Este artículo explica cómo instalar y ejecutar ngrok y configura Vonage para enviar solicitudes.

Si no dispone de una aplicación, puede crear una utilizando la CLI

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

El comando devuelve un ID de aplicación (del que debe tomar nota) y la información de su clave privada (que puede puede ignorar con seguridad a los efectos de esta guía).

Ejecutar ngrok utilizando el siguiente comando:

ngrok http 3000

Anote el nombre de host temporal que ngrok y utilizarlo en lugar de example.com en el siguiente comando:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice `
  --voice-answer-url='https://example.com/webhooks/voice/answer' `
  --voice-event-url='https://example.com/webhooks/voice/event' `
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

Comprar un número de teléfono

Para manejar las llamadas entrantes a tu aplicación, necesitas un número de Vonage. Si ya tienes un número para usar, salta a la siguiente sección para asociar el número existente con tu aplicación.

Puede utilizar la función CLI de Vonage para comprar el número de teléfono:

Buscar un número

Puedes comprar un número usando la CLI de Vonage. El siguiente comando busca un número una compra (especifica un código de país alternativo de dos caracteres comprar un número en otro país).

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

Comprar un número

Una vez que haya encontrado un número que le satisfaga, puede comprarlo utilizando el botón vonage numbers buy mando:

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

Ya está listo para escribir el código de su aplicación.

Escriba su webhook de respuesta

Cuando Vonage reciba una llamada entrante en tu número virtual, realizará una solicitud a tus /webhooks/answer ruta. Esta ruta debe aceptar una dirección HTTP GET y devuelve un Objeto de control de llamadas Nexmo (NCCO) que le indica a Vonage cómo manejar la llamada.

Su OCN debe utilizar el talk para saludar a la persona que llama, y la acción input acción para obtener usuario Entrada DTMF (tecla pulsada):

app.get('/webhooks/voice/answer', (request, response) => {
  console.log('answer: ', request.query)

  const ncco = [{
    action: 'talk',
    text: 'Thank you for calling Example Inc.! Press 1 to talk to the sales department, press 2 to get technical support.',
    bargeIn: true
  },
    {
      action: 'input',
      eventUrl: [
        `${request.protocol}://${request.get('host')}/webhooks/input`],
      type: [ 'dtmf' ],
      dtmf: {
        maxDigits: 1
      }
    }
  ]

  response.json(ncco)
})

Escriba su webhook de eventos

Implemente un webhook que capture eventos de llamada para que pueda observar el ciclo de vida de la llamada en la consola:

app.post('/webhooks/voice/event', (request, response) => {
  console.log('event:', request.body)
  response.sendStatus(200);
})

Vonage hace un POST a este punto final cada vez que cambia el estado de la llamada.

Escriba su webhook de entrada

Los resultados de la entrada DTMF se enviarán a la URL específica que establezca en la opción input acción: /webhooks/input. Añade un webhook para procesar el resultado y añadir algo de interacción con el usuario.

En caso de reconocimiento correcto, la carga útil de la solicitud tendrá el siguiente aspecto:

{
  "speech": {
  },
  "dtmf": {
    "digits": "1",
    "timed_out": true
  },
  "from": USER_NUMBER,
  "to": VONAGE_NUMBER,
  "uuid": "abfd679701d7f810a0a9a44f8e298b33",
  "conversation_uuid": "CON-64e6c8ef-91a9-4a21-b664-b00a1f41340f",
  "timestamp": "2020-04-17T17:31:53.638Z"
}

Recuperar la entrada del usuario del archivo dtmf.digits para determinar las opciones que han seleccionado. Para conectar tanto al usuario como al agente del departamento correspondiente, crearás una llamada saliente al endpoint del agente. Puede utilizar un número de teléfono de prueba en este ejemplo para simplificar, por ejemplo, su número de móvil. En la vida real, el punto final podría ser un número RTC o Punto final SIP para conectar tu PBX o centro de contacto existente. También podría ser un cliente WebRTC si está desarrollando su solución de centro de contacto desde cero: el cliente Vonage Client SDK proporciona todo lo que necesita para implantar su propia aplicación de agente de Contact Center.

Por último, ambas llamadas (tramos) deben trasladarse a una sala de conferencias (denominada conversación). Para ello, debe utilizar conversation acción con el mismo name tanto para la llamada del usuario (el tramo de entrada) como para el tramo del agente (la llamada de salida). Para generar el nombre de la conversación, puede utilizar cualquier método de generación de ID único, por ejemplo, utilizando la marca de tiempo real.

Como opción, puede utilizar connect en la OCN para conectar al usuario con el agente. La diferencia es que con connectLa llamada se completará inmediatamente cuando alguno de los participantes cuelgue y sólo quede un tramo. Por lo tanto, sería imposible transferir al usuario a la encuesta después de la llamada; si eso no es necesario en su caso, connect es una opción un poco más práctica. Si desea que el usuario siga conectado después de que el agente finalice la llamada, elija conversation como se muestra en el siguiente ejemplo.

Añadir el código para manejar la devolución de llamada de entrada:

app.post('/webhooks/input', (request, response) => {
  console.log('input:', request.body)

  // generating unique conversation name
  var conversationName = 'conversation_' + Date.now()

  console.log('conversationName: ', conversationName)

  // selecting agent/department endpoint
  var departmentId = request.body.dtmf.digits
  var department = ''
  var departmentNumber = ''

  switch (departmentId) {
    case '1':
      department = 'Sales'
      departmentNumber = AGENT_NUMBER
      break
    case '2':
      department = 'Support'
      departmentNumber = OTHER_AGENT_NUMBER //you can use the same number for the sample
      break
    default:
      break
  }

  var ncco = ''

  if (department != '') {
      // NCCO for the user leg
    ncco = [{
      action: 'talk',
      text: 'Please wait while we connect you to ' + department
    }, {
      action: 'conversation',
      name: conversationName
    }
    ]

    // creating the agent leg and moving it to the same conversation
    vonage.calls.create({
      to: [
        {
          type: 'phone',
          number: departmentNumber
        }
      ],
      from: {
        type: 'phone',
        number: VONAGE_NUMBER
      },
      ncco: [
        {
          action: 'conversation',
          name: conversationName
        }]

    }, (error, response) => {
      if (error) console.error('outbound error:', error)
      if (response) {
          console.log('outbound ok')
      }
    })
  } else { // something went wrong, fallback route
    ncco = [{
      action: 'talk',
      text: 'Press 1 to talk to the sales department, press 2 to get technical support.',
      bargeIn: true
    }, {
      action: 'input',
      eventUrl: [
        `${request.protocol}://${request.get('host')}/webhooks/input`
      ],
      dtmf: {
        maxDigits: 1
      }
    }]
  }
  
  response.json(ncco)
})

Añadir encuesta OCN

A continuación, para aplicar la encuesta de satisfacción del cliente al final de la llamada, deberá gestionar completed del agente. Llegará al mismo webhook de evento, por lo que deberá ampliar el webhook de evento con solicitud de transferencia a la OCN de la encuesta. Para ello, debe almacenar los identificadores de usuario y de pata de agente:

var userLegId = ''
var agentLegId = ''

app.get('/webhooks/answer', (request, response) => {
  console.log('answer: ', request.query)

  userLegId = request.query.uuid

  console.log('userLegId: ', userLegId)
  

...

app.post('/webhooks/input', (request, response) => {
  console.log('input:', request.body)

    // creating the agent's leg and moving it to the same conversation
    vonage.calls.create({
        ...
    }, (error, response) => {
      if (error) console.error('outbound error:', error)
      if (response) {
        agentLegId = response.uuid
        console.log('agentLegId: ', agentLegId)
      }
    })
  } else ...

En el escenario de la vida real, deberías implementar una caché para almacenar los pares de identificadores de pata de usuario/agente. El código de ejemplo que se muestra en esta guía sólo funcionará correctamente para una llamada concurrente.

Amplíe su webhook de eventos con el método de llamada de actualización de la API REST con NCCO en línea con talk y input acciones para mover la pierna del usuario a la parte de la encuesta:

app.post('/webhooks/event', (request, response) => {
  console.log('event:', request.body)

  if (request.body.uuid == agentLegId && request.body.status == 'completed') {
    vonage.calls.update(userLegId, {
      action: 'transfer',
      destination: {
        type: 'ncco',
        ncco: [ {
          action: 'talk',
          text: 'Please valuate quality of service by entering a digit, 1 to 5'
        },
        {
          action: 'input',
          type: [ 'dtmf' ],
          dtmf: {
            maxDigits: 1
          },
          eventUrl: [ `${request.protocol}://${request.get('host')}/webhooks/survey` ]
        }
        ]
      }
    }, (err, res) => {
      if (err) {
        console.error('transfer error:', err)
      } else {
        console.log('transfer ok')
      }
    })
  }
  
  response.sendStatus(200)
})

Escriba el webhook de su encuesta

Añadir webhook de encuesta para imprimir los resultados:

app.post('/webhooks/survey', (request, response) => {
  console.log('survey: ', request.body)

  var phone = request.body.from
  var date = request.body.timestamp
  var score = request.body.dtmf.digits

  console.log('[%s] User %s gave %d', date, phone, score)

  const ncco = [
    {
      action: 'talk',
      text: 'Thank you, good bye.'
    }
  ]

  response.json(ncco)
})

Crea tu servidor Node.js

Por último, escribe el código para instanciar tu servidor Node.js:

const port = 3000
app.listen(port, () => console.log(`Listening on port ${port}`))

Pruebe su aplicación

  1. Ejecute su aplicación Node.js ejecutando el siguiente comando:
node index.js

  1. Llama a tu número de Vonage desde el "teléfono de usuario" y escucha el mensaje de bienvenida.

  2. Abra el teclado de marcación y pulse 1 o 2.

  3. Contesta la llamada entrante "teléfono agente".

  4. Cuelga el teléfono del agente.

  5. Escucha el mensaje de la encuesta y pulsa cualquier tecla del primer dispositivo.

  6. Observe el registro de la consola para ver el resultado de la encuesta.

Solución de problemas

Si no escuchas el sonido del usuario y del agente, potencialmente puede ser porque las dos piernas están siendo procesadas en diferentes lugares. Puede determinar esto viendo diferentes conversation_uuid_to valores en el transfer para las patas de usuario y agente. Para solucionarlo, intente configurar el SDK para utilizar un centro de datos específico como se describe en la sección Guía de resolución de problemas:

const options = {
  apiHost: 'api-us-1.nexmo.com',
  restHost: 'rest-us-1.nexmo.com'
}

const vonage = new Vonage({
  apiKey: VONAGE_API_KEY,
  apiSecret: VONAGE_API_SECRET
  applicationId: VONAGE_APPLICATION_ID,
  privateKey: VONAGE_APPLICATION_PRIVATE_KEY_PATH
}, options)

Conclusión

Con Voice API de Vonage puedes potenciar tu solución de centro de contacto existente con IVR de cualquier complejidad lógica, que depende sólo de tu caso de uso objetivo y es prácticamente ilimitada. O puedes crear tu propia solución desde cero usando Voice API y Client SDK. Alternar entre la parte guionizada de la llamada y la conversación en directo (y viceversa) le permite combinar cualquier caso de uso de las llamadas telefónicas y crear una experiencia del cliente sin fisuras.

¿Y ahora qué?

  • Más información Flujo de llamadas con la Voice API
  • Aprenda a construir un menú de llamada (Respuesta de Voz Interactiva) desde cero siguiendo los siguientes pasos nuestro tutorial
  • Mejore la experiencia del cliente con Reconocimiento de vozcomo alternativa o junto con la entrada DTMF;
  • Ver cómo utilizar Grabación de llamadas para futuras referencias y análisis posteriores a la llamada;
  • Acceda directamente a los medios de comunicación con WebSockets para análisis en tiempo real e integración de IA.
  • Consulte IA de Vonage para que nuestros expertos creen un IVR o un bot de voz para su caso de uso específico.