Crie seu próprio correio de voz com o Node-RED e a Voice API da Nexmo

Tenho evitado o correio de voz durante a maior parte da minha vida. Na maioria das vezes, por um motivo simples: nunca conseguia entender 100% da mensagem.

Eu já me consideraria sortudo se eles tivessem balbuciado um número para o qual eu pudesse ligar de volta, se a caixa postal estivesse mais ou menos vazia ou se tivessem conseguido dizer mais do que apenas o primeiro nome. Na maioria dos casos, porém, a situação era mais ou menos assim:

"Oi, Julia, aqui é o Ted, da empresa ‘não_sei_bem_o_nome’. Sinto muito por não termos conseguido retomar o contato sobre isso — se você for como eu, tenho certeza de que está sendo puxada em várias direções diferentes e está muito ocupada. Mas me faça um favor: quando receber esta mensagem, ligue de volta e deixe uma mensagem dizendo o que decidiu fazer em relação à minha proposta. Seja qual for a decisão, será bom para mim saber. Agradeço desde já e ficarei aguardando sua ligação...”

Ted... Mosby? Crilly? Talvez Cassidy? Nunca saberemos.

Felizmente, criar seu próprio correio de voz no Node-RED é mais rápido e mais fácil do que decifrar essas mensagens. Acompanhe este tutorial para ver como funciona!

O que você vai construir

Este tutorial faz parte do série “Introdução ao Nexmo e ao Node-RED” .

Esses artigos mostram como começar a usar as APIs da Nexmo, como SMS, Voice e Verify; portanto, fique à vontade para consultá-los à medida que for avançando ou caso queira adicionar outra funcionalidade.

Neste tutorial, vamos criar um serviço simples de correio de voz que permite que quem ligar entre em contato com o seu número Nexmo e deixe uma mensagem.

A mensagem de voz gravada será então recuperada dos servidores da Nexmo e enviada para o seu endereço de e-mail.

Dependências

Pré-requisitos

Antes de começar, você precisará de algumas coisas:

• Node.js e Node-RED instalados, caso você esteja desenvolvendo localmente

• Uma maneira de expor seu servidor à internet. Isso significa que você está executando uma versão hospedada do Node-RED ou usando um serviço de tunelamento como ngrok — confira este guia Tutorial de Introdução ao Ngrok no Node-RED tutorial

Como obter suas credenciais

Para usar os nós do Nexmo no Node-RED, você precisará fornecer suas credenciais; por isso, é melhor tê-las à mão. Acesse seu painel de controle para encontrar sua chave de API e seu segredo e anote-os.

Em seguida, você precisará de um Voice-enabled . Acesse Numbers > Comprar números para adquirir um.

buy number nexmo dashboard

Configurando seu editor do Node-RED

Acesse o editor do Node-RED digitando no navegador http://localhost:1880.

Depois de abrir o editor, você precisará instalar os Nexmo Nodese o Node do Ngrok(caso não esteja usando uma versão hospedada do Node-RED) e o de e-mail. Você pode fazer isso na paleta “Gerenciar” , procurando os pacotes correspondentes e clicando em “Instalar”:

• Nexmo: node-red-contrib-nexmo

• Ngrok: node-red-contrib-ngrok

• E-mail: node-red-node-email

Após reiniciar o Node-RED, você deverá ver todos esses nós aparecerem no lado esquerdo da tela — na sua paleta de nós, entre outros nós padrão.

Exponha seu servidor local à Internet

Caso você não esteja usando uma versão hospedada do Node-RED, a Voice API da Nexmo precisará de outra forma de acessar seus endpoints de webhook; portanto, vamos tornar seu servidor local acessível pela internet pública. Se você estiver executando o Node-RED em um servidor web público em vez de na sua máquina local, já está tudo pronto para seguir em frente para a [Criar uma Application Nexmo Voice].

Uma maneira prática de fazer isso é usando um serviço de tunelamento como o ngrok, e há um node para isso que você acabou de adicionar à sua paleta.

Ele pega as cordas em e fora como entrada para iniciar/parar o túnel e exibe o endereço do host do ngrok como o msg.payload. Confira nosso tutorial sobre Introdução ao Ngrok no Node-RED para saber mais.

Importar da Área de trabalho o trecho abaixo ou tente criar esse caminho por conta própria.

[
    {
        "id": "faed0f7.1e524f",
        "type": "inject",
        "z": "5b8bbfc3.1a9f18",
        "name": "",
        "topic": "",
        "payload": "on",
        "payloadType": "str",
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "x": 190,
        "y": 100,
        "wires": [
            [
                "8a01baeb.6756d"
            ]
        ]
    },
    {
        "id": "11051fa9.75bd1",
        "type": "inject",
        "z": "5b8bbfc3.1a9f18",
        "name": "",
        "topic": "",
        "payload": "off",
        "payloadType": "str",
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "x": 190,
        "y": 160,
        "wires": [
            [
                "8a01baeb.6756d"
            ]
        ]
    },
    {
        "id": "8a01baeb.6756d",
        "type": "ngrok",
        "z": "5b8bbfc3.1a9f18",
        "port": "1880",
        "creds": "5a9e2b8c.173a2c",
        "region": "ap",
        "subdomain": "",
        "name": "",
        "x": 400,
        "y": 140,
        "wires": [
            [
                "93fd5675.743c1"
            ]
        ]
    },
    {
        "id": "93fd5675.743c1",
        "type": "debug",
        "z": "5b8bbfc3.1a9f18",
        "name": "",
        "active": true,
        "tosidebar": true,
        "console": false,
        "tostatus": false,
        "complete": "false",
        "x": 620,
        "y": 140,
        "wires": []
    },
    {
        "id": "5a9e2b8c.173a2c",
        "type": "ngrokauth",
        "z": ""
    }
]

Neste momento, seu editor deve estar mais ou menos assim:

ngrok path

Como última etapa antes de clicar em “Implantar”, abra as ngrok propriedades do nó e especifique o número da porta (1880 para o Node-RED) e a região.

Você também pode adicionar seu authtoken, caso já tenha um account no ngrok. Não se preocupe se não tiver; basta pular essa etapa por enquanto. O node exibirá um aviso informando que não está totalmente configurado, mas isso não representa nenhum problema.

ngrok properties

Acesso Implantar e clique no botão inject botão do nó e, em seguida, acesse a URL exibida na área de depuração (YOUR_URL para referência futura) para encontrar seu editor do Node-RED em um endereço público.

ngrok node-red

Criar um aplicativo de voz da Nexmo

A Voice API da Nexmo utiliza o Nexmo Applications para armazenar as informações de segurança e configuração necessárias para se conectar aos terminais da Nexmo.

Na paleta do Nexmo Node-RED, vários nós permitem criar essas Applications: getrecording, earmuff, mute, hangup, transfer, createcall, playaudio, playtts e playdtmf.

Arraste qualquer um desses nós para a sua área de trabalho e, em seguida, clique duas vezes nele para abrir as propriedades do nó.

Ao lado do Nexmo Credentials, selecione “Adicionar novo nexmovoiceapp...” no menu suspenso e clique no botão “Editar”. Preencha os detalhes abaixo e clique em “Criar novo aplicativo”.

O Node-RED criará então uma nova Application Nexmo no seu Account e preencherá os campos “App ID” e “Private Key”. Após essa etapa, fique à vontade para excluir o nó Nexmo que você utilizou, já que um nexmovoiceapp foi criado um nó de configuração que contém todas as credenciais do Nexmo necessárias para este fluxo.

create voice app

Configurar um número para ligar

Em seguida, você precisará vincular seu número virtual a este aplicativo.

Encontre o aplicativo de voz que você acabou de criar no seu painel do Nexmo, acessando Voice > Seus Applications.

Clique no nome deste aplicativo e, em seguida, na seção Numbers , clique na botão “Link” ao lado do número virtual que você alugou anteriormente.

Caso o número que você deseja usar já esteja vinculado a outro aplicativo, clique em Gerenciar número e configure-o para encaminhar as chamadas recebidas para o seu aplicativo.

link number

Dica extra: Use um comment node para anotar o número da Nexmo vinculado ao seu aplicativo; assim, você sempre o terá à mão.

Atender chamadas recebidas

Quando você recebe uma chamada no seu número virtual, a Voice API Nexmo faz uma GET solicitação a um endpoint definido por você, YOUR_URL/answere aguarda um conjunto de instruções sobre como lidar com a chamada.

Primeiro, vamos implementar esse endpoint.

Definir o ponto de extremidade do webhook para chamadas recebidas

Adicione um voice webhook e um return ncco nó à sua área de trabalho e conecte-os para definir um ponto de extremidade de webhook. Em seguida, abra as voice webhook propriedades do nó, selecione GET como um Method e digite /answer no URL campo e, em seguida, pressione Implantar.

inbound webhook

Ótimo! Agora você tem um webhook que retorna um NCCO para a API da Nexmo. Neste momento, ele ainda não contém nenhuma instrução, então vamos adicionar algumas!

Criar o Objeto de Controle de Chamadas da Nexmo (NCCO)

As instruções esperadas pela API da Nexmo vêm na forma de um Objeto de Controle de Chamadas da Nexmo, também conhecido como NCCO.

Há várias ações diferentes disponíveis; encontre os nós correspondentes na paleta Nexmo no seu editor Node-RED ou consulte a Referência do NCCO para saber mais sobre elas.

Nesse caso, provavelmente você vai querer cumprimentar a pessoa que ligou e, em seguida, começar a gravar a mensagem. Para fazer isso, você precisará adicionar um talk nó seguido por um record nó.

Adicione-os à sua área de trabalho e, em seguida, conecte-os entre os voice webhook e return ncco .

talk

Em seguida, abra o talk editor de nós e defina o Text{} campo com a mensagem que você deseja que seja lida para quem está ligando. Por exemplo: “Oi! Você ligou para o X, por favor, deixe uma mensagem.”

Se você está com saudades das mensagens de voz à moda antiga, está tudo certo. Por outro lado, você também pode personalizar a experiência selecionando uma Voice Name ou utilizando tags SSML, para que a mensagem soe mais como uma pessoa e menos como um robô.

record

Nas record propriedades do nó, preencha o URL {} campo com YOUR_URL/record. Esse será o eventURL para o qual a Nexmo enviará um conjunto de parâmetros assim que a gravação for concluída.

Se você der uma olhada no Referência da NCCO , logo perceberá que o número de chamada não está entre eles.

Felizmente, podemos obter o número de telefone do chamador a partir do `answerURL` e passá-lo como um parâmetro de consulta.

Atualize o URL {} campo para YOUR_URL/record?from={{msg.call.from}}. Dessa forma, poderemos acessar o from valor por meio do registro eventURL, referenciando msg.req.query.from.

Antes de passar para a próxima etapa, certifique-se de ter selecionado POST como Method, MP3 como um Format e que você definiu um valor para End On Silence (por exemplo, 3).

voicemail record

Se você quiser ver o NCCO gerado, acesse YOUR_URL/answer. Você verá um conjunto de ações, ou “instruções”, no formato JSON que a Nexmo usará para controlar o fluxo da chamada.

Pronto para dar um passo adiante? Ligue para o seu número da Nexmo para ver como funciona!

voicemail NCCO

Buscar gravação

Nesse momento, o chamador é recebido por uma mensagem de TTS, seguida por um bipe, e sua mensagem é gravada. O próximo passo é baixar a gravação dos servidores da Nexmo.

Registrar URL do evento

Primeiro, vamos definir o campo eventURL, para o qual esperamos que os parâmetros da gravação sejam enviados após a conclusão.

Adicione um http in nó à sua área de trabalho e, em seguida, conecte um http response nó, bem como a um debug nó a ele. Dessa forma, você pode começar a registrar eventos na área de depuração e entender um pouco melhor o que realmente está acontecendo.

Abra as http in propriedades do nó, selecione POST como um Method e preencha o URL campo com /record.

O http response nó deve ter 200 definido como Status code, mas não se preocupe com isso, esse também é o valor padrão.

Embora os dados de gravação estejam chegando como msg.payload, ainda temos o from valor armazenado em msg.req.query.from. Certifique-se de selecionar complete msg object no debug editor do nó como Output.

Começar a gravar

Para realmente recuperar a gravação, vamos usar o getrecording Nexmo.
Adicione um à sua tela, conecte-o ao /record http in e abra o editor do nó.

Você verá dois campos:

1. Nexmo Credentials - selecione o aplicativo de voz que você criou anteriormente no menu suspenso.

2. Filename {} - Observe o {} símbolo no rótulo, o que significa que este campo suporta modelos Mustache e que o valor pode ser definido dinamicamente. Isso nos dá a oportunidade perfeita de incluir o número do chamador e um carimbo de data/hora no nome do arquivo; portanto, vamos defini-lo como recordings/{{msg.req.query.from}}_{{msg.payload.timestamp}}.mp3.

Observe que este nó não grava o áudio no disco; o campo “nome do arquivo” serve para definir o valor de `msg.filename`. Em seguida, há algumas opções diferentes que você pode seguir: enviar o áudio para o seu próprio servidor, prosseguir com um file nó e baixá-lo para o seu computador, ou usar um e-mail nó e enviá-lo para você mesmo.

Enviar a gravação para um endereço de e-mail

Para este exemplo, usaremos o nó padrão do Node-RED e-mail , que envia o msg.payload como um e-mail, com o assunto msg.topic.

No nosso caso, msg.payload trata-se de um buffer binário (a gravação) e ele será convertido em um anexo. Se você quiser adicionar um corpo ao seu e-mail, defina-o como msg.description usando um change nó no fluxo antes do e-mail nó.

O nome do arquivo será msg.filename, que já especificamos.

Conecte um change nó a getrecording, seguido por um e-mail nó. Você encontrará ambos na sua paleta de nós, change em função e e-mail em social. A seguir, vamos ver como configurá-las.

change

Abra as change propriedades do nó e defina duas regras usando o operação .

Primeiro, vamos definir msg.topico assunto do e-mail.

No campo superior, substitua payload por topic, e selecione expression tipo no to menu suspenso, que utiliza o JSONata . Para incluir o número do chamador no assunto do e-mail, preencha este campo com algo como 'Voicemail from ' & msg.req.query.from.

Clique no botão “Adicionar” para definir uma segunda regra. Desta vez, vamos definir o valor de msg.description, o corpo do e-mail. Você pode usar uma expressão novamente ou simplesmente usar uma sequência de caracteres simples, como “Ei, você recebeu uma mensagem de voz!”.

voicemail change

Imprensa Concluído quando terminar, e vamos passar para o e-mail nó!

e-mail

No e-mail editor de nós, há três campos que você precisa preencher: To - o endereço de e-mail do destinatário, Userid e Password - seus dados de login de e-mail.

voicemail email

Quando terminar, clique em Concluído e Implantar. Seu correio de voz já está funcionando!

Registrar eventos de chamada

Mais uma coisa antes de você ir embora! É bem útil ver seus eventos de chamada na área de depuração e entender melhor o que realmente está acontecendo; então, vamos adicionar um webhook de eventos!

Conecte um http in nó a um http response nó, bem como a um debug nó, para que você possa visualizar seus eventos de chamada na área de depuração.

No http in nó, selecione POST como um Method e preencha o URL campo com /event.

O http response nó deve ter 200 definido como Status code, mas não se preocupe com isso, esse também é o valor padrão.

voicemail flow

Agora ligue para o seu número da Nexmo e acompanhe os eventos da chamada na barra lateral de depuração!

Experimente!

E pronto! Você criou seu próprio serviço de correio de voz e, com sorte, nunca mais terá que aturar outra mensagem de voz chata. Ligue para o seu número da Nexmo e receberá um e-mail em breve.

E agora, para onde vamos?

Leitura complementar

• Referência da Voice API

• Registrar referência NCCO

• Nomes de vozes do TTS

• Uso de tags SSML

• Introdução ao ngrok no Node-RED

Experimente outro tutorial

• Encaminhar uma chamada por meio de um proxy de voz com o Node-RED

• Criar uma teleconferência com o Node-RED

• Verify números de telefone com o Node-RED

• Como transmitir áudio em uma chamada com o Node-RED

• Como fazer chamadas telefônicas com conversão de texto em fala usando o Node-RED

• Como receber chamadas telefônicas com o Node-RED

• Como enviar mensagens SMS com o Node-RED

• Como receber mensagens SMS com o Node-RED