Acompanhe o uso dos seus números da Vonage

Obtenha informações sobre a eficácia de suas comunicações com os clientes acompanhando as chamadas recebidas em seus números da Vonage. Ao registrar um número diferente para cada uma de suas campanhas de marketing, você pode verificar qual delas tem o melhor desempenho e usar essas informações para aprimorar suas futuras iniciativas de marketing.

O exemplo de hoje usa o NodeJS e todo o código está disponível no GitHub, no entanto, a mesma abordagem poderia ser utilizada para qualquer outra pilha de tecnologias.

Pré-requisitos

Para seguir este guia, você precisará de:

• A Account da Vonage
• O CLI da Vonage instalado e configurado.
• Um servidor web acessível ao público para que a Vonage possa enviar solicitações de webhook ao seu aplicativo. Se você estiver desenvolvendo localmente, recomendamos ngrok.

Comece agora

Antes de baixar o código e começar a trabalhar, você precisará configurar uma aplicação da Vonage e obter alguns Numbers para usar com ela. Ao criar uma aplicação da Vonage, você especifica alguns webhook pontos de extremidade; esses são URLs na sua própria aplicação e são a razão pela qual seu código deve estar acessível ao público. Quando alguém liga para seu número da Vonage, a Vonage fará uma solicitação da web para o answer_url ponto de extremidade que você especificar e seguir as instruções encontradas nesse local.

Há também um event_url webhook, que recebe atualizações sempre que o estado da chamada muda. Nesta aplicação, o código exibe os eventos no console para fornecer informações úteis durante o desenvolvimento.

Para criar o aplicativo inicial, use a CLI da Vonage para executar o comando abaixo, substituindo sua URL em dois locais:

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

Este comando retorna o UUID (Identificador Universalmente Único) que identifica seu aplicativo. Com o ID do aplicativo, agora você pode adicionar o recurso de voz ao seu aplicativo:

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

Você precisará de alguns números da Vonage para testar este aplicativo. É possível usar a CLI da Vonage para pesquisar e comprar um número por meio dos comandos mostrados abaixo; ao pesquisar um número, digite qualquer código de país em Formato ISO 3166-1 alfa-2.

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.

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

Você pode usar qualquer código de país em Formato ISO 3166-1 alfa-2 para este comando. O resultado é o número que você comprou, então copie-o (você sempre pode obter uma lista com vonage numbers) e vincule-o ao aplicativo que você criou:

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

Repita a etapa de compra e vinculação para quantos números você quiser usar.

Configurar e executar o aplicativo

Primeiro, obtenha o código em este repositório. Você pode clonar o repositório na sua máquina local ou baixar o arquivo zip.

Instale as dependências com este comando: npm install

Em seguida, copie o modelo de configuração .env-example em um arquivo chamado .env. Nesse arquivo, você precisará configurar o número de telefone para o qual a Vonage deve fazer a ligação; portanto, pode ser qualquer telefone que esteja por perto e que você possa atender.

Para iniciar o servidor web: npm start

Verifique se tudo está funcionando conforme o esperado acessando http://localhost:5000. Você deverá ver “Hello Vonage” como resposta.

Atender chamadas de voz recebidas

Quando a Vonage recebe uma chamada para o seu número da Vonage, ela envia uma solicitação para o endpoint do webhook que você configurou ao criou um aplicativo do Voice.

Quando a pessoa faz a ligação, o aplicativo recebe o webhook de entrada. Ele extrai o número do qual a pessoa está ligando (o to número) e o número que discaram (o from (número) e repassa esses valores para a lógica de rastreamento de chamadas.

O webhook recebido é processado pelo /track-call trajeto:

app.get('/track-call', (req, res) => {
    const from = req.query.from;
    const to = req.query.to;

    const ncco = callTracker.answer(from, to);
    return res.json(ncco);
});

Rastrear a chamada antes de conectar o chamador

A lógica para rastrear a chamada, propriamente dita, está separada no aplicativo de exemplo. Observe que o aplicativo perde os dados quando você reinicia o servidor! Para suas próprias aplicações, você pode ampliar essa parte para gravar em um banco de dados, em uma plataforma de log ou em qualquer outro recurso que atenda às suas necessidades. Após rastrear a chamada, o aplicativo retorna um Objeto de Controle de Chamadas da Nexmo (NCCO) para informar aos servidores da Vonage o que fazer a seguir com a chamada.

Você encontrará esse código em lib/CallTracker.js:

class CallTracker {

  config;

  trackedCalls;

  constructor(config) {
    this.config = config;

    this.trackedCalls = {};
  }

  /**
   * Track the call and return an NCCO that proxies a call.
   */
  answer (from, to) {
    if(!this.trackedCalls[to]) {
      this.trackedCalls[to] = [];
    }

    this.trackedCalls[to].push({
      timestamp: Date.now(),
      from: from,
    });

    return [
      {
        action: 'connect',
        from: to,
        endpoint: [
          {
            type: 'phone',
            number: this.config.proxyToNumber,
          },
        ],
      },
    ];
  };
}

A NCCO utiliza o connect ação para conectar a chamada recebida a outra chamada para o número que você especificou no arquivo de configuração. O from O número deve ser um número da Vonage; portanto, o código usa o número rastreado como identificador de chamadas para a chamada efetuada. Verifique o Documentação da NCCO para o connect ação para obter mais detalhes sobre o objeto de controle de chamadas.

Conclusão

Com essa abordagem, você conseguiu vincular alguns números da Vonage ao seu aplicativo node.js, registrar as chamadas recebidas nesses números e conectar os chamadores a um número de saída. Ao registrar a data e a hora, bem como os números de origem e de destino, você pode realizar qualquer análise necessária sobre esses dados para obter os melhores resultados para o seu negócio.

E agora, para onde vamos?

Aqui estão mais algumas sugestões de recursos que você pode achar interessantes como próximo passo após este guia:

• Adicionar um sussurro de chamada a uma chamada recebida para informar alguns detalhes sobre a chamada recebida à chamada efetuada antes de conectar as duas.
• Postagem no blog que explica como Conecte seu servidor de desenvolvimento local à API da Vonage usando um túnel ngrok.
• O Referência sobre Webhooks para o Voice mostra os detalhes dos webhooks recebidos para ambos answer_url e event_url pontos finais.
• Consulte o Documentação da NCCO para obter detalhes sobre outras ações que você pode utilizar para controlar o fluxo das suas chamadas da Vonage.