Encaminhar uma chamada telefônica por meio de um proxy de voz com Python e Starlette

Existem algumas situações em que podemos precisar que um desconhecido possa nos ligar, ou que possamos ligar para ele. Um entregador pode precisar ligar para você sobre sua encomenda; você pode precisar ligar para o motorista do táxi porque esqueceu seu guarda-chuva. Nessas situações, é conveniente poder ligar e falar diretamente com a pessoa em questão, e não com uma central de atendimento. No entanto, nenhuma das duas pessoas quer que um desconhecido tenha seu número particular.

Com o encaminhamento de chamadas, é possível permitir que as pessoas liguem umas para as outras sem que nenhuma das partes saiba o número de telefone da outra. O encaminhamento de chamadas dessa forma é conhecido como proxy de voz.

Antes de começar

Há algumas coisas de que você precisa antes de começar:

1. Python 3.6+. Este exemplo utiliza a função assíncrona Starlette , portanto, é imprescindível ter uma versão recente do Python.

2. Se você estiver executando o exemplo em seu ambiente de desenvolvimento local, precisará de uma maneira de torná-lo acessível pela internet, por exemplo, usando ngrok.

Baixe o código

Todo o código deste exemplo está disponível na organização Nexmo Community no GitHub. Clone o repositório agora:

git clone git@github.com:nexmo-community/nexmo-python-voiceproxy.git
cd nexmo-python-voiceproxy

Depois de clonar o repositório, você deve instalar suas dependências. Recomendo que você sempre faça isso em um novo ambiente virtual.

python -m venv nexmo-voiceproxy
source nexmo-voiceproxy/bin/activate
pip install -r requirements.txt

Criação de um servidor Starlette

Fornecemos instruções à Voice API da Nexmo por meio de um Objeto de Controle de Chamadas da Nexmo (NCCO). O NCCO é um arquivo JSON que contém uma lista de ações que a Nexmo deve executar sempre que um usuário ligar para um Número Virtual da Nexmo. Neste exemplo, o NCCO possui uma única ação, connect. A connect ação nos permite conectar a chamada a diferentes pontos de extremidade. Um ponto de extremidade pode ser outro número, um WebSocket ou um ponto de extremidade SIP. Neste exemplo, você usa o number tipo. O encaminhamento de uma chamada para um número diferente dessa forma não é visível para o usuário.

async def get(self, request):
    return JSONResponse(
        [
            {
                "action": "connect",
                "from": os.getenv("NEXMO_NUMBER_FROM"),
                "endpoint": [
                    {"type": "phone", "number": os.getenv("NEXMO_NUMBER_TO")}
                ],
            }
        ]
    )

O código acima contém duas variáveis de ambiente que você deve definir. NEXMO_NUMBER_FROM, este é o número de telefone para o qual o usuário liga para iniciar o proxy; é também o número que o outro usuário vê como remetente da chamada. Esse número deve ser um Número Virtual da Nexmo; explicarei mais adiante neste artigo como você pode alugar um Número Virtual e vinculá-lo ao seu aplicativo.

NEXMO_NUMBER_TO é o número de telefone do usuário que recebe a chamada encaminhada. Esse número pode ser qualquer número de telefone no formato E.164.

Eventos da Voice API

Você pode acompanhar o status da sua chamada encaminhada por meio do webhook de eventos. Sempre que houver uma alteração no status da chamada, a Nexmo o notificará por meio de um webhook. As informações fornecidas ao webhook variam de acordo com o status atual; você pode encontrar uma lista completa na documentação da Voice API.

Neste exemplo, as informações são registradas no terminal para que você possa acompanhar os eventos em tempo real. Vale ressaltar que você deve sempre retornar uma 200 OK resposta HTTP a todos os webhooks da Nexmo. Se você não retornar uma 200 OK resposta, a API do Nexmo presume que houve um erro e, após um breve intervalo, tenta acessar o endpoint novamente. Para evitar múltiplas solicitações e dados duplicados, certifique-se de sempre retornar uma 200 OK.

async def post(self, request):
    event = await request.json()
    log.msg("Voice Proxy", **event)
    return PlainTextResponse()

Por padrão, a API da Nexmo solicita o arquivo NCCO por meio de GET e notifica o webhook de eventos usando uma POST solicitação com um corpo em JSON. Você pode alterar isso nas configurações do seu aplicativo, mas o código deste tutorial pressupõe que GET as solicitações sejam para o NCCO e que POST as solicitações são notificações de eventos.

Como vincular um número virtual a um aplicativo de Voice

A API da Nexmo precisa ter acesso ao seu servidor Starlette. Se você estiver executando este exemplo localmente, será necessário expor seu servidor à internet pública. Para obter mais informações sobre como criar um túnel para o localhost, leia nossa postagem no blog sobre o ngrok.

Certifique-se de que seu servidor esteja em execução python server.py e, em seguida, abra um novo terminal para ngrok:

ngrok http 8000

Agora que seu servidor proxy está em funcionamento e acessível pela API da Nexmo, você pode alugar um Número Virtual da Nexmo e criar um novo Aplicativo de Voz usando o painel de controle da Nexmoou por meio da CLI da Vonage. Você pode encontrar mais informações sobre como instalar a CLI da Vonage aqui.

Para fazer isso pela CLI, é preciso executar vários comandos:

vonage numbers:search [COUNTRYCODE]
vonage numbers:buy [NUMBER] [COUNTRYCODE]
vonage apps:create
vonage apps:link [APPLICATION_ID] --number=number

Os comandos acima realizam o seguinte:

• Procure um número disponível com COUNTRYCODE. Insira GB para números virtuais britânicos e US para os dos EUA.

• Depois de encontrar um número adequado, você o compra usando vonage numbers:buy [NUMBER] [COUNTRYCODE]

• Ao criar um novo aplicativo de voz, execute vonage apps:create e siga as instruções. Você deve fornecer um nome para o aplicativo, a URL do seu arquivo NCCO, a URL do seu webhook de eventos e um local para salvar sua chave privada. A chave privada é usada para autenticação na Voice API da Nexmo ao fazer chamadas de saída. Como este exemplo lida apenas com chamadas recebidas, você não precisará dessa chave privada neste momento.

• Por fim, vincule o Número Virtual ao seu novo aplicativo. É possível associar vários números a um único aplicativo; por exemplo, se você quiser ter números locais diferentes para usuários em países diferentes.

Juntando tudo isso

Depois de associar um número virtual ao seu aplicativo de Voice e de ter seu servidor proxy em funcionamento e acessível à internet pública, você estará pronto para encaminhar sua primeira chamada.

Se você usar um segundo dispositivo para ligar para o Número Virtual da Nexmo associado ao seu aplicativo, poderá ver a solicitação do NCCO no terminal Starlette.

Quando a chamada for encaminhada e seu outro telefone começar a tocar, verifique o número exibido do chamador. O número exibido não é o número de telefone do aparelho que iniciou a chamada, mas sim o Número Virtual da Nexmo que você especificou como seu NEXMO_NUMBER_FROM número. Com apenas uma dúzia de linhas de código, você criou um proxy de voz anônimo!

Leitura complementar

O encaminhamento de chamadas é apenas uma das muitas coisas que você pode fazer com a Voice API. Você deveria tentar conectar a chamada a um WebSocket ou modificar o webhook de eventos para acompanhar as estatísticas das suas chamadas. Você poderia até mesmo fazer uma análise de sentimento em tempo real da chamada.

Entre em contato

Se você tiver alguma dúvida ou comentário sobre este post, ou se quiser ser o primeiro a saber quando publicarmos algo novo ou descobrirmos alguma tecnologia interessante, siga-nos no Twitter: @NexmoDev