Jornada da Voz

Neste guia, você implementará o seguinte cenário de central de atendimento:

• O usuário liga para o seu número da Vonage,
• A mensagem de boas-vindas inicial é lida em voz alta, e o usuário escolhe uma opção do menu apresentado,
• O usuário está conectado a um agente,
• Depois que o atendente encerra a ligação, o usuário é direcionado para uma pesquisa de satisfação do cliente.

Para entender melhor o fluxo, consulte Fluxo de chamadas.

Pré-requisitos

Para concluir este guia, você precisa de:

• A Account da Vonage,
• O CLI da Vonage instalado e configurado,
• ngrok - para tornar seu servidor web de desenvolvimento acessível aos servidores da Vonage pela Internet,
• Node.JS instalado,
• dois dispositivos de chamada telefônica com números da rede PSTN atribuídos — “telefone do usuário” e “telefone do agente”, por exemplo, dois celulares ou um aplicativo com recurso de chamada, como Vonage Business app.

Instale as dependências

Instale o expresso estrutura de aplicativos web e analisador de corpo pacotes:

Criar um aplicativo de voz

Use a CLI para criar um aplicativo da Voice API com o webhooks que será responsável por atender uma chamada no seu número da Vonage (/webhooks/voice/answer) e registrar eventos de chamadas (/webhooks/voice/event), respectivamente.

Esses webhooks precisam estar acessíveis aos servidores da Vonage; portanto, neste guia, você utilizará ngrok para disponibilizar seu ambiente de desenvolvimento local na Internet pública. Este artigo explica como instalar e executar ngrok e configurar o Vonage para enviar solicitações.

Se você não tiver uma aplicação, pode criar uma usando a 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

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

O comando retorna um ID de aplicativo (que você deve anotar) e as informações da sua chave privada (que você pode ignorar sem problemas para os fins deste guia).

Correr ngrok usando o seguinte comando:

Anote o nome de host temporário que ngrok fornece e use-o no lugar de example.com no seguinte 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

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 um número de telefone

Para atender chamadas recebidas em seu aplicativo, você precisa de um número da Vonage. Se você já tiver um número para usar, pule para a próxima seção para associar o número existente ao seu aplicativo.

Você pode usar o CLI da Vonage para comprar o número de telefone:

Pesquisar um número

Você pode adquirir um número usando a CLI da Vonage. O comando a seguir procura um número para compra (especifique um código de país alternativo de dois caracteres para adquirir um número em outro 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.

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 um número

Depois de encontrar um número que lhe agrade, você pode comprá-lo usando o vonage numbers buy comando:

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

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

Agora você está pronto para escrever o código do seu aplicativo.

Escreva seu webhook de resposta

Quando a Vonage receber uma chamada no seu número virtual, ela enviará uma solicitação ao seu /webhooks/answer rota. Essa rota deve aceitar uma solicitação HTTP GET solicitar e devolver um Objeto de Controle de Chamadas da Nexmo (NCCO) que indica à Vonage como lidar com a chamada.

Seu NCCO deve usar o talk ação para cumprimentar a pessoa que está ligando, e o input ação para obter o usuário Entrada DTMF (tecla pressionada):

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

Crie o webhook do seu evento

Implemente um webhook que capture eventos de chamadas para que você possa acompanhar o ciclo de vida da chamada no console:

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

A Vonage oferece um POST Envie uma solicitação a este endpoint sempre que o status da chamada mudar.

Escreva seu webhook de entrada

Os resultados da entrada DTMF serão enviados para a URL específica que você definir no input ação: /webhooks/input. Adicione um webhook para processar o resultado e incluir alguma interação do usuário.

Caso o reconhecimento seja bem-sucedido, a carga útil da solicitação terá a seguinte aparência:

{
  "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 a entrada do usuário do dtmf.digits matriz para determinar as opções selecionadas. Para conectar o usuário ao agente do departamento correspondente, você criará uma chamada de saída para o endpoint do agente. Para simplificar, você pode usar um número de telefone de teste neste exemplo, como, por exemplo, o seu número de celular. Na prática, o endpoint pode ser um número PSTN ou Terminal SIP para conectar seu PBX ou central de atendimento já existente. Também pode ser um cliente WebRTC, caso você esteja desenvolvendo sua solução de central de atendimento do zero — o Vonage Client SDK oferece tudo o que você precisa para implementar seu próprio aplicativo de agente de Contact Center.

Por fim, ambas as chamadas (ramificações) devem ser transferidas para uma sala de conferência (chamada conversa). Para isso, você deve usar conversation ação com o mesmo name tanto para a chamada do usuário (a etapa de entrada) quanto para a etapa do agente (a chamada de saída). Para gerar o nome da conversa, você pode usar qualquer método de geração de ID exclusivo; por exemplo, utilizando o carimbo de data e hora real.

Adicione o código para lidar com o callback 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)
})  

Adicionar pesquisa NCCO

Em seguida, para realizar a pesquisa de satisfação do cliente ao final da ligação, você deve lidar com completed evento para a etapa do agente. Ele chegará ao mesmo webhook de evento; portanto, você deve estender o webhook de evento com pedido de transferência para a pesquisa NCCO. Para isso, é preciso armazenar os identificadores do usuário e do 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 ...

Amplie o webhook do seu evento com o método de chamada de atualização da API REST, utilizando o NCCO embutido com talk e input ações para mover a perna do usuário até a parte do levantamento:

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

Crie o webhook da sua pesquisa

Adicione um webhook da pesquisa para imprimir os 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)
})

Crie seu servidor Node.js

Por fim, escreva o código para instanciar seu servidor Node.js:

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

Teste seu aplicativo

1. Execute sua aplicação Node.js digitando o seguinte comando:

2. Ligue para o seu número da Vonage a partir do “telefone do usuário” e ouça a mensagem de boas-vindas.

3. Abra o teclado numérico e pressione 1 ou 2.

4. Atenda a chamada recebida no “telefone do agente”.

5. Desligue o telefone do atendente.

6. Ouça a mensagem da pesquisa e pressione qualquer tecla no primeiro dispositivo.

7. Observe o log do console para ver o resultado da pesquisa.

Solução de problemas

Se você não ouvir o som do usuário e do agente, isso pode ocorrer porque as duas ligações estão sendo processadas em locais diferentes. Você pode verificar isso observando diferenças conversation_uuid_to valores no transfer eventos para os segmentos do usuário e do agente. Para resolver isso, tente configurar o SDK para usar um data center específico, conforme descrito no Guia de solução 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)

Conclusão

Com a Voice API da Vonage, você pode aprimorar sua solução de contact center existente com um IVR de qualquer nível de complexidade lógica, que depende apenas do seu caso de uso específico e é praticamente ilimitado. Ou você pode criar sua própria solução do zero usando a Voice API e Client SDK. Alternar entre a parte padronizada da ligação e a conversa ao vivo (e vice-versa) permite combinar qualquer tipo de situação em que se utilize o telefone e criar uma experiência de cliente integrada.

E agora, para onde vamos?

• Saiba mais sobre Fluxo de chamadas com a Voice API
• Aprenda a criar um menu de chamadas (Resposta Interativa de Voz) do zero, seguindo nosso tutorial
• Melhore a experiência do cliente com Reconhecimento de fala, como alternativa ou em conjunto com a entrada DTMF;
• Veja como usar Gravação de chamadas para consultas futuras e análises pós-atendimento;
• Tenha acesso direto à mídia com WebSockets para análises em tempo real e integração com IA.
• Verificar Vonage IA Oferecemos a criação de um IVR ou bot de voz por nossos especialistas para o seu caso de uso específico.