Verify números de telefone com o Node-RED

Nos tutoriais anteriores você aprendeu sobre as APIs de SMS e Voice API da Nexmo, se familiarizou com o envio e o recebimento de mensagens e chamadas e, esperamos, também teve a oportunidade de experimentar e brincar com a personalização dessas experiências no Node-RED.

Neste tutorial, vamos dar uma olhada na Verify API e exploraremos uma maneira prática de validar os números de telefone dos seus usuários.

Muitos aplicativos cadastram usuários com pouco mais do que um número de telefone, a fim de manter o processo o mais simples possível, e precisam usar esse identificador para autenticação posteriormente.

Então, vamos ver como podemos fazer isso, além de garantir que não haja contas duplicadas e que os usuários possam realmente ser contatados pelos números de telefone fornecidos por eles.

Pré-requisitos

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

• Node.js e Node-RED instalados no seu computador

Como obter suas credenciais

Para interagir com a Verify API, é preciso prestar atenção a alguns detalhes. Depois de criar uma conta no Nexmo, acesse o painel de controle para encontrar sua chave de API e seu segredo. Você usará essas credenciais mais tarde para se autenticar na API.

Configurando seu editor do Node-RED

Primeiro, você precisará instalar o ambiente de execução e o editor. Isso pode ser feito tanto em seu computador local quanto em um computador de placa única (por exemplo, o Raspberry Pi) ou em diversas opções hospedadas na nuvem.

Este exemplo será executado no seu computador local; portanto, depois de instalar o Node-RED globalmente, digite o comando abaixo no terminal para começar.

Você pode então acessar o editor do Node-RED digitando no navegador http://localhost:1880.

Depois de abrir o editor, você precisará instalar os nós do Nexmo. Você pode fazer isso na seção paleta “Gerenciar” , procurando pelo node-red-contrib-nexmo pacote e clicar em “Instalar”.

install node red

Em seguida, repita a etapa anterior para o node-red-dashboard pacote também.

Após reiniciar o Node-RED, você deverá ver agora todos os nós do Nexmo e do Dashboard exibidos no lado esquerdo da tela, entre os outros nós padrão na paleta de nós.

Interface do usuário

Para este tutorial, você precisará de uma interface de usuário simples para coletar as entradas do usuário. Existem algumas maneiras de fazer isso, incluindo escrever seu próprio HTML e CSS, mas uma alternativa muito mais rápida é usar os nós de painel do Node-RED.

O que você vai precisar:

• Um campo de texto para inserir o número de telefone

• Um campo de texto para inserir o código PIN

• A Cancelar verificação botão

• A Botão “Ligue para mim” — isso dará ao usuário a opção de solicitar uma ligação telefônica, além de um SMS, como forma de receber o código PIN.

Acelere o processo ao importar da área de transferência o trecho abaixo, ou experimente você mesmo os nós do painel.

[
    {
        "id": "463e8e92.d82a78",
        "type": "tab",
        "label": "Verify Demo",
        "disabled": false,
        "info": ""
    },
    {
        "id": "fb7955ef.0e5fd8",
        "type": "ui_form",
        "z": "463e8e92.d82a78",
        "name": "",
        "label": "Verify your phone number:",
        "group": "91563061.fc448",
        "order": 1,
        "width": 0,
        "height": 0,
        "options": [
            {
                "label": "eg. 447401234567",
                "value": "number",
                "type": "text",
                "required": true
            }
        ],
        "formValue": {
            "number": ""
        },
        "payload": "",
        "submit": "Send me a code",
        "cancel": "delete",
        "topic": "",
        "x": 430,
        "y": 140,
        "wires": [
            []
        ]
    },
    {
        "id": "b60bf0b2.9a839",
        "type": "ui_button",
        "z": "463e8e92.d82a78",
        "name": "",
        "group": "91563061.fc448",
        "order": 2,
        "width": "0",
        "height": "0",
        "passthru": false,
        "label": "Call me",
        "tooltip": "",
        "color": "",
        "bgcolor": "",
        "icon": "",
        "payload": "",
        "payloadType": "str",
        "topic": "",
        "x": 520,
        "y": 580,
        "wires": [
            []
        ]
    },
    {
        "id": "b182a10d.c8f08",
        "type": "ui_button",
        "z": "463e8e92.d82a78",
        "name": "",
        "group": "91563061.fc448",
        "order": 3,
        "width": 0,
        "height": 0,
        "passthru": false,
        "label": "Cancel Verification",
        "tooltip": "",
        "color": "",
        "bgcolor": "red",
        "icon": "",
        "payload": "",
        "payloadType": "str",
        "topic": "",
        "x": 550,
        "y": 760,
        "wires": [
            []
        ]
    },
    {
        "id": "a2251664.3ba2f",
        "type": "comment",
        "z": "463e8e92.d82a78",
        "name": "Start Verification - Collect phone number to be verified",
        "info": "",
        "x": 520,
        "y": 80,
        "wires": []
    },
    {
        "id": "7185f18d.87142",
        "type": "comment",
        "z": "463e8e92.d82a78",
        "name": "Check if received code matches the generated one",
        "info": "",
        "x": 510,
        "y": 280,
        "wires": []
    },
    {
        "id": "7f30e.60359cf28",
        "type": "comment",
        "z": "463e8e92.d82a78",
        "name": "Next Verification - Escalate to TTS Call",
        "info": "",
        "x": 610,
        "y": 520,
        "wires": []
    },
    {
        "id": "c46fa301.4eb0d8",
        "type": "comment",
        "z": "463e8e92.d82a78",
        "name": "Cancel Verification",
        "info": "",
        "x": 550,
        "y": 700,
        "wires": []
    },
    {
        "id": "ab7fb094.d7d1f8",
        "type": "ui_form",
        "z": "463e8e92.d82a78",
        "name": "",
        "label": "Check code:",
        "group": "91563061.fc448",
        "order": 4,
        "width": 0,
        "height": 0,
        "options": [
            {
                "label": "Enter the PIN code you received",
                "value": "code",
                "type": "text",
                "required": true
            }
        ],
        "formValue": {
            "code": ""
        },
        "payload": "",
        "submit": "submit",
        "cancel": "delete",
        "topic": "",
        "x": 390,
        "y": 340,
        "wires": [
            []
        ]
    },
    {
        "id": "91563061.fc448",
        "type": "ui_group",
        "z": "",
        "name": "Verify Demo Input Fields",
        "tab": "fdce8e2a.f4364",
        "disp": false,
        "width": "8",
        "collapse": false
    },
    {
        "id": "fdce8e2a.f4364",
        "type": "ui_tab",
        "z": "",
        "name": "Verify Demo",
        "icon": "dashboard",
        "disabled": false,
        "hidden": false
    }
]

Quando estiver pronto, seu editor deverá ter uma aparência semelhante a esta:

verify UI template

Para visualizar sua interface do usuário, acesse http://127.0.0.1:1880/ui.

verify UI

Verificação do seu usuário

Depois de coletarmos o número de telefone de um usuário, podemos iniciar o processo de verificação enviando uma solicitação de verificação à Verify API.

Iniciar verificação

Para iniciar uma verificação, você precisará de um sendverify nó conectado ao formulário que captura o número de telefone do usuário. Por padrão, isso enviará um texto curto personalizado e um código PIN em uma mensagem SMS para o número de telefone do usuário, seguido por duas chamadas com texto-para-voz, caso ele não consiga enviar o código recebido.

Abra as sendverify propriedades do nó clicando duas vezes nele. Lá você encontrará os três campos obrigatórios que precisará preencher: Nexmo Credentials, To {} e Brand {}.

Observe o {} ao lado dos rótulos, o que significa que esses campos suportam Mustache Templating e você poderá passar valores dinamicamente.

No Nexmo Credentials menu suspenso, selecione Adicionar novo nexmobasic e clique no botão “Editar”. Em seguida, você será solicitado a fornecer seu API Key e API Secret para se autenticar na Verify API — ambos podem ser encontrados no seu Painel do Nexmo.

Quando terminar, clique em “Adicionar”. Agora, ao lado do Nexmo Credentials rótulo, você verá um nó de configuração; ele armazenará suas credenciais daqui em diante.

Em seguida, você precisará passar o número de telefone do usuário para o To {} campo. Se você importou o trecho de código da interface do usuário acima, isso será {{msg.payload.number}}, já que especificamos no primeiro form que o valor de entrada deve ser coletado na number chave msg.payload. Você pode alterar isso abrindo as form propriedades do nó e escolher uma Name.

Por fim, você pode personalizar o corpo da mensagem SMS de solicitação de verificação em Brand {} para ajudar os usuários a identificar o nome da sua empresa ou do seu aplicativo. É necessária uma sequência alfanumérica de 18 caracteres que será anexada ao início do número PIN gerado pela Verify API.

Por exemplo: “Seu PIN da Acme Inc. é...”

send verify configuration

O sendverify nó exibe a resposta da API recebida da Nexmo, contendo um request_id e um status parâmetro. Saiba mais sobre os códigos de status na Verify API Referência.

O request_id será usado em todas as etapas seguintes; portanto, precisamos torná-lo acessível a todos os outros nós no fluxo atual. Para isso, conecte um change nó a sendverify, abra as propriedades do nó e defina flow.request_id como msg.payload.request_id.

verify set request ID

Para entender um pouco melhor o que está acontecendo, você também pode conectar um debug nó no sendverify. Dessa forma, você poderá acompanhar a resposta da API na barra lateral de depuração.

Verificar código PIN

A solicitação foi aceita com sucesso pela Nexmo; seu usuário recebeu um código de verificação e já o inseriu no formulário correspondente. Sucesso? Quase.

Agora precisamos verificar se o código enviado é, de fato, aquele gerado e enviado pela Verify API.

Para esta etapa, precisaremos do checkverify nó, que receberá como entrada o ID da solicitação e o código fornecido pelo usuário, comparar os dois e, em seguida, enviar a resposta da API para msg.payload.

Depois de arrastá-lo para a sua área de trabalho, conecte-o ao formulário que captura o código PIN enviado pelo usuário e, em seguida, conecte um debug nó a seguir para ver o objeto de resposta na barra lateral de depuração.

Abra as checkverify propriedades do nó. No Nexmo Credentials menu suspenso, selecione o nó de configuração criado por sendverify, preencha o Request ID {} campo com {{flow.request_id}} e insira o código enviado pelo usuário no Code {} campo.

Se você importou o trecho de interface do usuário acima, isso será {{msg.payload.code}}, já que especificamos no segundo form que o valor de entrada deve ser coletado na code chave msg.payload. Você pode alterar isso abrindo as form propriedades do nó e selecionar um Name.

check verify

Parabéns!🎉 Seu fluxo do Verify já está em funcionamento. Acesse http://localhost:1880/ui e experimente!

Depois de inserir o código PIN recebido, volte ao Editor do Node-RED e observe com mais atenção a barra lateral de depuração.

O objeto de resposta conterá detalhes sobre sua solicitação, incluindo status, que indica se a solicitação foi bem-sucedida ou não. Se o PIN enviado pelo usuário corresponder ao gerado pela Verify API, status terá o valor de "0".

Verificar o status da verificação

Embora o número de telefone do usuário tenha sido validado com sucesso, não há nenhum indício desse evento, além da barra lateral de depuração, neste momento.

Para definir o que deve acontecer após o término do processo de verificação, podemos usar a status propriedade de msg.payload para separar os diferentes cenários.

Você pode querer conceder acesso a esse usuário a uma determinada página da web ou Application, salvar os dados do usuário cuja verificação foi bem-sucedida em um banco de dados ou informá-lo sobre o resultado e solicitar que ele tente novamente caso a verificação tenha falhado. Na verdade, tudo depende do seu caso de uso e do motivo pelo qual você está tentando verificar seus usuários.

Para simplificar, vamos avaliar a status propriedade e, com base no valor dela, informar ao usuário se a verificação foi bem-sucedida ou não. Se você quiser ser mais preciso com suas mensagens de erro, fique à vontade para adicionar mais rotas para outros códigos de status também.

Para isso, vamos precisar de:

• um switch nó para verificar o valor de msg.payload.status

• um notification nó do painel para informar o usuário

• dois change nós para preparar a mensagem que o notification nó irá exibir — um em caso de sucesso e outro em caso de falha.

Adicione esses nós à sua área de trabalho e conecte-os conforme mostrado na imagem abaixo.

check verify switch

Agora, vamos examinar mais de perto cada um desses nós:

switch

O switch nó encaminha mensagens com base nos valores de suas propriedades ou na posição na sequência. Neste caso, queremos criar duas rotas com base no valor de msg.payload.status.

Quando uma mensagem chega, o nó avalia cada uma das regras definidas em suas propriedades e encaminha a mensagem para as saídas correspondentes de quaisquer regras que se encaixem.

Primeiro, clique duas vezes no switch nó para acessar suas propriedades. No Property campo, substitua “payload” por “status”, para que seja msg.payload.status seja avaliado.

Em seguida, precisamos definir regras com base no valor dele. Clique no botão “Adicionar” para adicionar uma segunda regra, já que precisaremos de duas:

1. sucesso: na primeira regra, selecione “==” no primeiro menu suspenso e digite um “0” no campo de texto ao lado;

2. falha: na segunda regra, selecione “!=” no primeiro menu suspenso e digite um “0” no campo de texto ao lado. Isso abrangerá todos os casos em que a verificação não for bem-sucedida.

Observe que as regras têm um -> 1 e um -> 2 ao lado delas. Isso indica que, se a primeira condição for verdadeira, os nós conectados à primeira saída serão acionados. Em todos os outros casos, os que estiverem conectados à segunda saída serão acionados.

notification

O notification nó é exibido msg.payload como uma notificação pop-up ou um mensagem de diálogo na interface do usuário. Você pode escolher o tipo de notificação no Layout menu suspenso nas propriedades do nó e, no caso de uma janela pop-up, também é possível configurar sua posição.

Defina a duração no Timeout (S) campo, inserindo o número de segundos que você deseja que ele permaneça visível na interface do usuário.

Se você quiser definir um título, pode fazê-lo no Topic campo; ou, caso haja um msg.topic estiver disponível, ele será usado como título.

É possível personalizar ainda mais a experiência definindo uma cor de borda, seja no Border campo ou passando-a dinamicamente em msg.highlight.

change

Nos change nós, vamos usar a Set operação para especificar os valores de msg.payload e msg.highlight.

Vamos abrir as propriedades do primeiro change (certifique-se de que ele esteja conectado à primeira saída do switch nó, nosso cenário de sucesso). Defina msg.payload uma mensagem de sucesso como “Verificação bem-sucedida!”, clique no botão para definir uma segunda regra e defina msg.highlight para “verde”.

Repita os mesmos passos para o segundo change nó, mas, desta vez, insira msg.payload “Falha na verificação!” como valor e defina msg.highlight para “vermelho”. Além disso, certifique-se de que ele esteja conectado à segunda saída do switch nó.

Acesso Implantar e tente novamente! Agora, quando o processo de verificação for concluído, você verá uma janela pop-up com o resultado!

Próxima verificação

Assim que o processo de verificação for iniciado, a Nexmo fará três tentativas para enviar o código PIN para o número de telefone fornecido: uma mensagem SMS e duas chamadas com sintetizador de voz (TTS).

Há momentos em que uma ligação telefônica é a melhor opção, seja por questões de acessibilidade ou por pura preferência pessoal. É sempre um toque legal oferecer aos nossos usuários a opção de escolher um método alternativo de entrega; portanto, vamos dar uma olhada em como implementar um botão que encaminhe o processo de verificação para uma ligação via TTS instantaneamente.

No modelo de fluxo fornecido, localize o botão “Ligue para mim” e conecte um nextverify nó a ele. Abra as nextverify propriedades do nó, selecione seu Nexmo Credentials no menu suspenso e preencha o Request ID {} campo com {{flow.request_id}}. Talvez seja interessante também adicionar um debug nó para ter um pouco mais de visibilidade do seu lado, e um change nó seguido por um notification nó para informar ao usuário o que está acontecendo — exatamente como você fez na etapa anterior, mas isso é totalmente opcional.

Cancelar verificação

Em um mundo ideal, pararíamos por aqui, mas sempre surge alguma coisa, não é mesmo? Você cometeu um erro ao preencher um formulário e clicou em “enviar” — tarde demais para mudar de ideia e clicar naquele “Excluir” agora, a verificação já começou.

Você pode achar que basta esperar um pouco e tentar novamente depois que der errado. Sim, isso também funciona, mas não é a maneira ideal de proceder. Além de proporcionar uma experiência frustrante aos seus usuários, pense na pobre alma inocente que acaba recebendo duas ligações, além daquela mensagem inicial de verificação — às 2 da manhã. Opa.

Felizmente, existe uma maneira rápida e fácil de implementar um botão “Cancelar verificação” .

Se você importou o trecho de interface do usuário fornecido, basta conectar um cancelverify nó ao saída do botão e abrir as cancelverify propriedades do nó, selecionar sua Nexmo Credentials no menu suspenso e preencher o Request ID {} campo com {{flow.request_id}}.

Você também pode adicionar um debug nó para visualizar o objeto de resposta na barra lateral de depuração e um change nó seguido por um notification nó para informar ao usuário que o cancelamento foi realizado com sucesso.

Agora clique nesse botão Implantar e teste! Lembre-se de que, para que uma solicitação de cancelamento seja válida, ela precisa ser iniciada pelo menos 30 segundos após o envio do número de telefone. Ainda dá tempo de sobra para evitar que a chamada de TTS seja iniciada!

E pronto! Com sua proteção de segurança instalada, agora você pode dormir melhor à noite — assim como todos os estranhos desavisados que você também vai Verify. Bom trabalho!

Crédito extra – Verificação da pesquisa

Você já pode acompanhar o andamento do processo de verificação na barra lateral de depuração, já que cada objeto de retorno recebido da API da Nexmo é registrado por um nó de depuração, o que fornece informações valiosas sobre o que está acontecendo.

Às vezes, a área de depuração pode ficar um pouco cheia, dificultando a localização exata da informação que você está procurando. Além disso, talvez você queira verificar o resultado entre um evento e outro, sem precisar esperar que o próximo ocorra para que outro objeto de retorno apareça. Ele pode já ter sido concluído, mas você não tem certeza se falhou ou foi concluído com sucesso.

A boa notícia é que existe um searchverify nó da Nexmo que cuida de todas essas questões. Ao ser acionado por, digamos, um inject nó, ele exibirá todas as informações disponíveis sobre uma solicitação de verificação passada ou atual identificada por um request_id.

Adicione um searchverify nó à sua área de trabalho, conecte-o entre um inject e um debug nó. Nas searchverify propriedades do nó, selecione seu Nexmo Credentials no menu suspenso e preencha o Request ID {} campo com {{flow.request_id}} para obter detalhes sobre a verificação atual. Você também pode colar um request_id neste campo, caso queira verificar uma verificação que ocorreu antes da atual.

Agora, ao observar a barra lateral de depuração, depois de testar seu aplicativo, você perceberá que, sempre que clicar no inject botão do nó no seu editor, ele retornará um objeto com todos os detalhes disponíveis sobre a solicitação em questão. Dê uma olhada mais de perto nos campos de resposta e acesse a Referência da API da Nexmo para saber mais sobre cada um deles.

Para onde vamos agora?

• Nexmo Verify Referência da API

• Verify Documentação

Experimente outro tutorial:

• 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

• Apresentamos o pacote Nexmo para o Node-RED

• Como enviar mensagens SMS com o Node-RED

• Como receber mensagens SMS com o Node-RED