Adicionar um “Call Whisper” a uma chamada recebida

Os números de telefone estão por toda parte na publicidade: em outdoors, em comerciais de TV, em sites, em jornais. Muitas vezes, esses números redirecionam para a mesma central de atendimento, onde um atendente precisa perguntar por que a pessoa está ligando e onde ela viu o anúncio.

Por meio de mensagens de espera, o contexto da chamada recebida é informado ao operador do call center antes de ser conectada ao chamador. Este guia apresentará um aplicativo que implementa essa abordagem. Um usuário ligará para um dos dois números. A aplicação atende a chamada e o chamador ouve uma mensagem de espera. Enquanto isso, a aplicação também faz uma chamada para o operador do call center, reproduz um “call whisper” diferente dependendo do número discado e, em seguida, conecta o operador à conferência com o chamador.

Os exemplos foram escritos em Node.js com o Express, e você pode encontrar o código no GitHub.

Neste guia

Você verá como configurar o recurso “Call Whisper” em uma chamada recebida:

• Como funciona - uma visão geral de quem chama quem e como o processo se desenrola ao longo do aplicativo de exemplo.
• Antes de começar - configure o aplicativo e os números necessários para este guia.
• Introdução à programação - clonar o repositório e colocar o aplicativo em funcionamento.
• Explicação passo a passo do código - aprofundar-se nos detalhes do funcionamento do aplicativo.
• Leitura complementar - dê uma olhada em alguns outros recursos que podem ser úteis para você.

Como funciona

Antes de começar

Antes de pegarmos o código e colocá-lo em execução, há algumas coisas que precisamos fazer primeiro.

Inscreva-se no Vonage

Cadastre-se para obter um Account da API da Vonage se você ainda não tiver um.

Configurar a CLI

Este guia utiliza o Ferramenta de linha de comando da Vonage, portanto, verifique se ele está instalado antes de continuar.

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

Introdução à programação

O código deste projeto está disponível em GitHub. Este projeto em Node.js, que utiliza o Express, tem como objetivo fornecer a você um exemplo funcional que você poderá adaptar às suas próprias necessidades.

Clone o repositório

Clone ou baixe o repositório para o seu computador, em um novo diretório.

Configurar as opções

Seu aplicativo precisará de mais informações sobre você e sobre o próprio aplicativo antes de poder ser executado. Copie o .env-example arquivo para .env e edite esse novo arquivo para refletir as configurações que você deseja usar:

• CALL_CENTER_NUMBER: O número de telefone para entrar em contato com o atendente da central de atendimento, como o seu número de celular
• INBOUND_NUMBER_1: Um dos números que você comprou
• INBOUND_NUMBER_2: O outro número que você comprou
• DOMAIN: O nome de domínio onde seu aplicativo será executado; por exemplo, o meu é: ff7b398a.ngrok.io

Instale as dependências

No diretório em que você baixou o código, execute npm install. Isso instala o Express e outras dependências necessárias para este projeto.

Inicie o servidor

Com a configuração concluída e as dependências instaladas, seu aplicativo está pronto para funcionar! Execute-o com:

npm start

Por padrão, o aplicativo é executado na porta 3000. Se você for usar ngrok, você pode iniciar seu túnel agora.

Experimente

Vamos testar a demonstração. Para isso, você precisará de dois celulares (um para ser o “chamador” e outro para ser o “atendente do call center”), então talvez seja necessário pedir a ajuda de um amigo ou usar o Skype para fazer a primeira ligação.

1. Ligue para um dos números que você comprou.
2. A pessoa que ligar ouvirá uma mensagem de boas-vindas e, em seguida, o telefone do atendente do call center tocará.
3. Quando o atendente do call center atender, ele ouvirá a mensagem “em voz baixa” antes de ser conectado ao chamador original.
4. Agora tente de novo, mas ligue para o outro número e preste atenção ao “sussurro” diferente.

Explicação passo a passo do código

A demonstração é divertida, mas se você estiver interessado em criar isso por conta própria, há alguns pontos importantes que provavelmente vai querer conferir. Esta seção analisa as partes principais do código para cada etapa do processo, para que você possa identificar onde cada coisa acontece e adaptar esse aplicativo às suas necessidades.

Atenda a chamada recebida e inicie uma chamada

Sempre que alguém ligar para um dos números vinculados ao aplicativo da Vonage, a Vonage receberá uma chamada. A Vonage, então, notificará seu aplicativo web sobre essa chamada. Para isso, ela faz uma solicitação de webhook para o seu aplicativo web answer_url ponto final — neste caso /answer. Quando a chamada é atendida, o aplicativo conecta o chamador ao atendente do call center.

lib/routes.js

app.get('/webhooks/voice/answer', (req, res) => {
  const  answer_url = 'http://'+process.env['DOMAIN']+'/on-answer'
  console.log(answer_url);

  res.json([
    {
      "action": "talk",
      "text": "Thanks for calling. Please wait while we connect you"
    },
    {
      "action": "connect",
      "from": req.query.to,
      "endpoint": [{
        "type": "phone",
        "number": process.env['CALL_CENTER_NUMBER'],
        "onAnswer": {"url": answer_url}
      }]
    }
  ]);
});

A resposta que retornamos é uma matriz de NCCOs (Objetos de controle de chamadas da Nexmo). O primeiro é a mensagem falada que o chamador ouve; o segundo conecta-se ao outro chamador e especifica qual URL deve ser usada quando essa pessoa atender a chamada.

Reproduza um “Whisper” e conecte a chamada

Quando o atendente do call center atende a ligação, o onAnswer A URL é usada; no nosso aplicativo, ela é a /on-answer ponto final. Esse é o código que identifica qual número foi discado e determina qual mensagem deve ser reproduzida.

lib/routes.js

// Define the topics for the inbound numbers
const topics = {}
topics[process.env['INBOUND_NUMBER_1']] = 'the summer offer';
topics[process.env['INBOUND_NUMBER_2']] = 'the winter offer';

Quando a chamada for estabelecida, reproduza um sussurro de chamada para o agente usando o talk A equipe da NCCO deve informar aos participantes sobre qual campanha publicitária a ligação se refere, antes de conectá-los ao interlocutor que está aguardando na conferência.

lib/routes.js

app.get('/on-answer', function(req, res) {
  // we determine the topic of the call based on the inbound call number
  const topic = topics[req.query.from]
  res.json([
    // We first play back a little message telling the call center operator what
    // the call relates to. This "whisper" can only be heard by the call center operator
    {
      "action": "talk",
      "text": "Incoming call regarding "+topic
    }
  ]);
});

Existem tantas possibilidades aqui que podem ajudá-lo a personalizar as mensagens de voz. Você poderia passar o número da pessoa que está ligando com o url em on-answer e consultá-los, permitindo que você os cumprimente pelo nome ou forneça alguma outra informação. As possibilidades são infinitas, mas esperamos que este guia lhe ofereça um exemplo prático que você possa usar como base e personalizar.

Leitura complementar

• GitHub contém todo o código desta aplicação de exemplo.
• Confira nosso Guias de voz para saber mais sobre o que você pode fazer com a voz.
• O Referência da Voice API possui documentação detalhada para cada endpoint.