Crie um proxy de voz com o Cloud Functions

O Voice Proxy — ou chamada anônima — protege os dados pessoais dos usuários ao fornecer um número de telefone intermediário. Dessa forma, nem quem liga nem quem recebe a ligação vêem os números de telefone reais um do outro. É uma prática comum em serviços de entrega e de transporte compartilhado, como o Deliveroo e o Uber, mas também é útil em diversos cenários de pequenas empresas.

Neste tutorial, vamos criar um dos meus casos de uso favoritos: um telefone comercial virtual.

Abordaremos dois tipos de chamadas:

1. Você está ligando para um cliente pelo seu número da Vonage: capture o número de destino por meio do DTMF e faça a conexão.

2. Outra pessoa está ligando para o seu número da Vonage: transfira a chamada para o seu número pessoal.

Tudo o que precisamos para que isso funcione é um número virtual da Vonage e uma pequena função sem servidor que lide com webhooks.

Vamos usar o Google Cloud Functions, a oferta de Função como Serviço (FaaS) do Google, para uma maneira mais rápida de desenvolver na nuvem.

Com essas funções sem servidor orientadas a eventos, você conta com recursos de computação gerenciados, escalonamento automático e cobrança por uso, calculada com precisão de 100 milissegundos. A experiência do desenvolvedor é simples e intuitiva, permitindo que você se concentre no código enquanto o Google Cloud cuida da infraestrutura operacional.

Você pode pensar no Cloud Functions como blocos de construção que ampliam rapidamente seus serviços em nuvem por meio de código. Eles são executados em resposta a eventos transmitidos via HTTP ou emitidos por outros serviços do Google Cloud Platform, o que os torna uma excelente opção para arquiteturas baseadas em eventos, processamento de dados e automações na nuvem.

Neste exemplo, estamos criando uma função HTTP que é acionada por solicitações HTTP recebidas da Voice API da Vonage, aproveitando a arquitetura baseada em eventos do Google Cloud Functions.

Pré-requisitos

• Google Cloud Platform — Cadastre-se ou faça login com o Google; você receberá um crédito inicial no valor de US$ 300. Esse é um valor generoso que deve ser suficiente por um bom tempo para fins de teste e aprendizado.

• Conhecimentos básicos sobre Node.js e Express.

Configurar o Google Cloud Functions

Criar um novo projeto no Google Cloud

Primeiro, crie um novo projeto, caso ainda não tenha feito isso. Esses projetos servem de base para criar, habilitar e utilizar todos os serviços do Google Cloud.

Acesse a página “Gerenciar recursos” do Cloud Console e clique em “Criar projeto”. Saiba mais sobre como criar e gerenciar recursos no guia do Google Cloud.

Criar uma função na nuvem

Em seguida, selecione Cloud Functions no menu de navegação e, em seguida, clique em Criar função.

Há alguns campos que precisam ser configurados:

1. Dê à sua função um nome.

2. Selecione uma região. Eu escolhi europe-west-2 porque moro perto de Londres. Se você não tiver certeza de qual é a melhor opção para você, confira a lista de regiões disponíveis.

3. Defina o tipo de gatilho para HTTP, já que estamos criando uma função HTTP.

4. Marque as opções “Permitir chamadas não autenticadas” e “Exigir HTTPS”.

Quando terminar, copie a URL gerada e clique em Salvar.

Create function config page

Em seguida, expanda a seção CONFIGURAÇÕES DE TEMPO DE EXECUÇÃO, COMPILAÇÃO E CONEXÕES e role a tela para baixo até a seção Variáveis de ambiente de tempo de execução. Precisaremos definir dois números de telefone como variáveis de ambiente, ambos no formato internacional E. 164. Por exemplo, 447700900123 (Reino Unido) ou 14155550101 (EUA).

• YOUR_VONAGE_NUMBER: um dos seus números virtuais da Vonage. Encontre um no seu Painel da Vonage ou compre um.

• YOUR_PHONE_NUMBER: seu número de telefone pessoal, que você usará para os testes.

Set environment variables

Clique em “Avançar”, e pronto, a configuração está concluída; agora vamos ao código!

Certifique-se de selecionar Editor embutido como Código-fonte, a versão mais recente do Node.js como Runtimee habilite quaisquer APIs sobre as quais a plataforma possa emitir avisos.

Cloud Functions Inline Editor warning about installing Cloud Build

O editor de código embutido exibe uma função padrão gerada usando objetos de solicitação e resposta do Express.js. Vamos substituí-la pela nossa função. Lembre-se de que, se você alterar o nome da função, precisará atualizar o ponto de entrada também.

Criar uma aplicação da Vonage com recursos de voz

A Aplicativo da API da Vonage contém as informações de segurança e configuração necessárias para se conectar aos terminais da Vonage e utilizar as APIs da Vonage. Cada aplicativo da Vonage criado pode oferecer vários recursos; no entanto, por enquanto, precisamos apenas da funcionalidade de voz.

Vamos criar um usando o Painel da Vonage. Acesse Seus aplicativos -> Criar um novo aplicativo.

Ative os recursos de Voice e, em seguida, insira a URL do Cloud Functions gerada no Answer URL campo. A minha é assim: https://europe-west2-my-proxy-calling-project.cloudfunctions.net/proxy-call.
Por enquanto, não vamos implementar um webhook de evento, então fique à vontade para usar http://example.com/event nesse campo.

Quando terminar, clique em “Gerar novo aplicativo”.

Create Voice-enabled Vonage Application

Na próxima página, você verá uma lista dos números virtuais disponíveis na sua Account. Clique no botão “Link” ao lado de qualquer um que você queira associar a este aplicativo. Você ligará para esse número para testar seu aplicativo, portanto, comece com um número local. Como alternativa, se nenhuma lista for exibida ou se você não encontrar nenhum número adequado, também pode comprar mais números.

Link virtual Vonage number to Vonage Application

Se você associar um número diferente daquele definido no ambiente de execução, certifique-se de atualizar o valor de YOUR_VONAGE_NUMBER na interface do usuário do Cloud Console.

Controle do fluxo de chamadas

Agora que você configurou uma aplicação da Vonage, a Vonage enviará uma solicitação GET para o seu Answer URL sempre que alguém ligar para o seu número virtual vinculado. A Vonage espera um Objeto de Controle de Chamada (NCCO) seja retornado, um conjunto de instruções sobre como o fluxo da chamada deve ser executado.

Um NCCO é representado como um array JSON válido contendo uma ou mais ações. Neste exemplo, usaremos algumas delas:

• a talk ação para reproduzir mensagens de conversão de texto em fala durante a ligação

• a input ação para capturar a entrada do usuário por meio da detecção de tons DTMF (pressionamento de teclas)—entrada DTMF

• a connect ação de conectar o chamador e o chamado.

Criação da função na nuvem

Como teremos três casos, precisamos também retornar três NCCOs diferentes, de acordo com cada um deles.

Precisamos abordar três casos:

1. Outra pessoa está ligando para o seu número da Vonage -> transfira a chamada para o seu número de telefone

2. Você está ligando para o seu número da Vonage:

   2.1. Você ainda não forneceu a carga útil DTMF -> capture a entrada DTMF

   2.2. A carga útil DTMF está disponível -> conectar a chamada à carga útil DTMF (número de telefone de destino)

Volte ao Google Cloud Console e substitua o código padrão pelo seguinte.

// Get environment variables
const YOUR_VONAGE_NUMBER = process.env.YOUR_VONAGE_NUMBER;
const YOUR_PHONE_NUMBER = process.env.YOUR_PHONE_NUMBER;


exports.helloWorld = (req, res) => {
    // Check if there's DTMF payload in the request body
    if (req.body.dtmf) {
        // (2.2) Connect call to the number in the DTMF payload
    ])
    } else {
        // Check if you're the caller
        if (req.query.from === YOUR_PHONE_NUMBER) {
            // (2.1) Capture destination number via DTMF input
        } else {
            // (1) Connect caller to your phone number
        }
    }
};

Vamos dar uma olhada em cada uma dessas seções.

1. Receber uma ligação: Conectar o chamador

Primeiro, se outra pessoa ligar para o seu número virtual, você vai querer que a ligação seja encaminhada para o seu número de telefone real. Isso é feito por meio de uma connect ação e, opcionalmente, uma talk ação para informar ao chamador que ele está sendo transferido.

Nesse caso, você precisa devolver o seguinte NCCO:

res.json([{
        action: 'talk',
        text: 'Please wait while we connect you.'
    },
    {
        action: 'connect',
        from: YOUR_VONAGE_NUMBER,
        endpoint: [{
            type: 'phone',
            number: YOUR_PHONE_NUMBER
        }]
    }
])

O trecho acima é mais do que suficiente para esse caso de uso, mas você pode configurar ainda mais essas duas ações, se quiser. Acesse a Referência do NCCO para conhecer todas as opções disponíveis.

2. Fazer uma ligação

Em seguida, precisamos tratar o caso em que você liga para o seu número da Vonage, digitando o número de destino no teclado do seu aparelho (entrada DTMF) e, em seguida, sendo conectado ao número que acabou de digitar.

Esse cenário ocorre em duas etapas.

2.1 Captura de entrada DTMF

Primeiro, precisamos retornar um NCCO que contenha uma input ação para capturar os dígitos. Vamos adicionar uma talk ação também, para incluir instruções.

A talk ação é igual à da etapa anterior, também opcional.

A input ação precisa ser do tipo ['dtmf']. O reconhecimento de voz também está disponível; leia mais sobre essa ação na Referência do NCCO.

Também precisamos alterar as configurações padrão configurações padrão de entrada DTMF para que sejam adequadas à captura de um número de telefone.

• timeOut é o número de segundos antes que a atividade do chamador seja enviada para o eventUrl após sua última ação. O padrão é três, mas vamos usar o valor máximo 10 para termos um pouco de margem de manobra.

• maxDigits é o número de dígitos que o usuário pode digitar; o padrão é quatro. 15 O número de dígitos aceita números de telefone no formato formato internacional E. 164 , que é o formato utilizado pela Vonage para números de telefone. Por exemplo, um número do Reino Unido teria o formato 447700900123.

• submitOnHash permite que a atividade do chamador seja enviada para o eventUrl após pressionar a tecla #. Se a tecla # não for pressionada, o resultado é enviado após timeOut segundos. O valor padrão é False; portanto, certifique-se de defini-lo como true.

res.json([{
        action: 'talk',
        text: 'Please enter a phone number in international format, omitting the leading plus sign. End with the pound key.'
    },
    {
        action: 'input',
        type: ['dtmf'],
        dtmf: {
            timeOut: 10,
            maxDigits: 15,
            submitOnHash: true
        },
        eventUrl: ["https://europe-west2-my-proxy-calling-project.cloudfunctions.net/proxy-call"]
    }
])

2.2 Conectar a chamada à entrada DTMF

Assim que os dígitos forem capturados, a Vonage enviará outra solicitação — do tipo POST por padrão — ao nosso endpoint com uma carga DTMF no corpo da solicitação. Em seguida, um segundo NCCO com uma connect ação para que você seja conectado ao número de destino.

res.json([{
        action: 'talk',
        text: 'Connecting'
    },
    {
        action: 'connect',
        from: YOUR_VONAGE_NUMBER,
        endpoint: [{
            type: 'phone',
            number: req.body.dtmf.digits
        }]
    }
])

Este Objeto de Controle de Chamada é semelhante ao primeiro, exceto que estamos definindo o número de destino dinamicamente. req.body.dtmf.digits contém a carga útil DTMF; consulte a entrada Referência do Webhook para obter mais detalhes sobre os resultados da captura de DTMF.

O produto final

Por fim, vamos juntar todas as partes! Ao inserir os três trechos que discutimos na função inicial, obtemos o seguinte código:

// Get environment variables
const YOUR_VONAGE_NUMBER = process.env.YOUR_VONAGE_NUMBER;
const YOUR_PHONE_NUMBER = process.env.YOUR_PHONE_NUMBER;

exports.helloWorld = (req, res) => {
    // Check if there's DTMF payload in the request body
    if (req.body.dtmf) {
        // (2.2) Connect call to the number in the DTMF payload
        res.json([{
                action: 'talk',
                text: 'Connecting'
            },
            {
                action: 'connect',
                from: YOUR_VONAGE_NUMBER,
                endpoint: [{
                    type: 'phone',
                    number: req.body.dtmf.digits
                }]
            }
        ])
    } else {
        // Check if you're the caller
        if (req.query.from === YOUR_PHONE_NUMBER) {
            // (2.1) Capture destination number via DTMF input
            res.json([{
                    action: 'talk',
                    text: 'Please enter a phone number in international format, omitting the leading plus sign. End with the pound key.'
                },
                {
                    action: 'input',
                    type: ['dtmf'],
                    dtmf: {
                        timeOut: 10,
                        maxDigits: 15,
                        submitOnHash: true
                    },
                    eventUrl: ["https://europe-west2-my-proxy-calling-project.cloudfunctions.net/proxy-call"]
                }
            ])
        } else {
            // (1) Connect caller to your phone number
            res.json([{
                    action: 'talk',
                    text: 'Please wait while we connect you'
                },
                {
                    action: 'connect',
                    from: YOUR_VONAGE_NUMBER,
                    endpoint: [{
                        type: 'phone',
                        number: YOUR_PHONE_NUMBER
                    }]
                }
            ])
        }
    }
};

Quando estiver pronto, clique em IMPLEMENTAR. A implantação pode demorar mais ou menos um minuto; tenha paciência. :) Assim que aparecer uma marca de seleção verde ao lado da sua função, você estará pronto para testá-la!

Function deployed

Seu serviço de encaminhamento de chamadas já está ativo, então ligue para ele! Melhor ainda: peça a um amigo para ligar para o seu número virtual — assim, você poderá testar os dois sentidos das chamadas.

E agora, para onde vamos?

Parabéns! Você acabou de criar um serviço de chamada de proxy com uma pequena função do Google Cloud!

Pronto para ir além? Você tem um caso de uso que exija a gravação de chamadas? Permite que vários números utilizem o serviço? Aceita tanto entradas de voz quanto de DTMF?

Dê uma olhada nos recursos abaixo e pense em como você pode aprofundar o assunto. Conte-nos como está indo, e adoraríamos saber o que você achou!

Recursos

• Visão geral da Voice API

• Referência NCCO

• Referência sobre Webhooks da Voice API

• Referência da Voice API

• Reconhecimento Automático de Fala

• Sinais DTMF

• Google Cloud Functions

• Como usar variáveis de ambiente

No futuro, talvez você queira desenvolver e testar suas funções localmente. Confira o Guia de Desenvolvimento Local do Cloud Functions Guia de Desenvolvimento Local para saber como começar.