Aviso sobre descontinuação de produto

A partir de 31 de agosto de 2025, a Dispatch API será encerrada para novos usuários, embora o produto continue a receber suporte para os usuários existentes. Se você pretende desenvolver um aplicativo de mensagens com funcionalidade de failover, saiba que essa funcionalidade agora é suportada diretamente na Messages API.

Para obter informações gerais sobre o recurso de failover de mensagens, consulte este guia. Para obter orientações sobre a migração da Dispatch API para a Messages API Failover, consulte este guia.

Caso tenha mais alguma dúvida sobre a descontinuação deste produto, por favor, entre em contato conosco no Slack da Comunidade Vonage.

Um dos momentos mais emocionantes para mim a cada Natal, enquanto crescia, era esperar para saber se o Papai Noel tinha deixado nossos presentes. Toda manhã de Natal, meu pai ia até o quarto onde ficava a árvore de Natal para verificar se “o Papai Noel tinha passado por lá” antes de podermos correr para ver nossos presentes.

Agora, como pai, a responsabilidade de verificar se o Papai Noel entregou os presentes é minha.

Ouvi falar de algumas famílias que acordam às 4 da manhã para abrir os presentes! Isso significa que o Papai Noel pode entregar os presentes em algumas casas bem cedo pela manhã. Então, o que devo fazer? Esperam que eu saia da cama e dê uma olhada embaixo da árvore a cada 30 minutos? Como alguém que já se autoproclamou um “Evangelista da Web em Tempo Real”, não me agrada a ideia do que é, na prática, a versão física do HTTP Polling. Não, não, isso não vai dar certo. Por isso, decidi criar um sistema de notificação de entregas do Papai Noel usando a Dispatch API, com o Facebook Messenger como principal canal de notificação e SMS como alternativa, porque não quero perder essa notificação.

Santa Delivery Notifications via Facebook Messenger

Nesta postagem, vou explicar os componentes utilizados e como eles se integram para oferecer uma solução de notificação de entrega do Papai Noel. Não abordarei os detalhes do código, mas você pode encontrar todo o código no GitHub , juntamente com instruções para executar sua própria instância do aplicativo.

Como funciona

O aplicativo utiliza uma combinação de uma aplicação Node.JS e a Dispatch API Nexmo para enviar a mensagem pelo Facebook Messenger com recurso de SMS caso a mensagem não seja lida, e uma API do Papai Noel desenvolvida por Steve Crow para seu postagem no blog “Rastreando o Papai Noel com SMS e Java” , uma Página do Facebook e um aplicativo associado no Facebook.

Fazendo login no Facebook

A primeira parte do aplicativo solicita que o usuário faça login no Facebook.

Facebook Login Flow

Isso utiliza o botão de login do Facebook , que depende do SDK do JavaScript do Facebook.

Obter a localização dos usuários

A determinação de se o Papai Noel entregou os presentes é feita por meio de uma combinação de:

1. Onde o usuário está localizado

2. Onde o Papai Noel está em sua rota de entregas

Location flow

A localização do usuário é determinada por meio do navegador API de geolocalização. Ela retorna apenas as coordenadas do usuário como uma estimativa.

As coordenadas são enviadas ao back-end Node.JS, que utiliza a API criada para o aplicativo “Acompanhando o Papai Noel por SMS” para localizar a cidade mais próxima das coordenadas.

Obter o número de telefone do usuário para o recurso de SMS alternativo

Agora que o aplicativo sabe onde o usuário está localizado, precisamos saber como enviar notificações. Se a mensagem do Facebook Messenger permanecer não lida, a Dispatch API recorrerá ao envio da mensagem também por SMS. Portanto, precisamos do número de telefone do usuário para esse recurso alternativo.

Get use's phone number flow

O usuário deve inserir seu número de telefone e clicar no botão “Go”. Ao clicar, o número de telefone é enviado para o back-end do Node.JS e armazenado para esse usuário.

Uma melhoria na funcionalidade atual seria utilizar a API Number Insight da Nexmo Number Insight API para garantir que o número de telefone seja válido e Verify API para confirmar que o usuário é o proprietário desse número de telefone.

Inscreva-se para receber as “Notificações de Entrega do Papai Noel” no Facebook Messenger

Provavelmente, a parte mais complicada de todo o aplicativo foi conseguir enviar mensagens ao usuário sem que ele precisasse enviar uma mensagem primeiro para a nossa página no Facebook.

Por fim, encontrei o plug-in “Send to Messenger” que parece ter sido criado exatamente para isso. No entanto, ele impõe alguns requisitos adicionais relacionados à configuração de um aplicativo do Facebook e um webhook “opt_in”.

Também descobri que o botão “Enviar para o Messenger” só era exibido se o usuário já estivesse conectado ao Facebook. Se você der uma olhada no JavaScript do lado do cliente no GitHub desse aplicativo, você verá um código implementado para lidar com algumas restrições do uso desse plug-in, incluindo a necessidade de recarregar a página quando o usuário faz login no Facebook.

Confirm subscription flow

Quando o usuário clicar no botão “Enviar para o Messenger” (que você pode configurar para exibir, em vez disso, “Inscrever-se”), isso acionará o webhook “opt_in” configurado pelo Facebook. A carga útil do webhook contém o importantíssimo ID de usuário no escopo da página , que é um ID exclusivo do usuário associado a uma página do Facebook.

Nesta etapa, salvamos uma assinatura oficial em um banco de dados. Este aplicativo utiliza uma instância do MongoDB gerenciada pelo MLab.

Com esse ID, o aplicativo agora pode enviar mensagens ao usuário usando a Dispatch API Nexmo. Para confirmar a assinatura, é enviada uma mensagem informando ao usuário que ele se inscreveu e indicando sua localização.

Subscription confirmation dialog

Verifique a localização do Papai Noel e envie notificações

Com a assinatura salva, tudo o que resta fazer é monitorar a localização do Papai Noel usando a API do Papai Noel mencionada anteriormente.

Santa delivery notifications flow

O aplicativo utiliza as coordenadas do usuário por meio da API e, quando a API indica que o Papai Noel está se deslocando away da localização do usuário, sabemos que o Papai Noel deve ter feito a entrega. Assim, uma Notificação de Entrega do Papai Noel é enviada pelo Facebook Messenger usando a Dispatch API. Se a mensagem não for lida dentro de um período de tempo configurável (veja expiry_time na referência da API), uma notificação por SMS também é enviada.

Conclusão

Nesta postagem, abordamos como é possível criar uma notificação de entrega do Papai Noel usando o Facebook Messenger com SMS como alternativa, por meio da Dispatch API do Nexmo. Confira o código no GitHub ou abra uma solicitação (ou uma solicitação de pull) caso tenha alguma ideia para melhorar o aplicativo (veja também “Próximos passos” abaixo) ou se tiver alguma dúvida.

Agora, pais e responsáveis em todo o mundo podem dormir tranquilos, sabendo que só precisam sair da cama para verificar se o Papai Noel já entregou os presentes assim que receberem a notificação de entrega do Papai Noel.

Para onde vamos agora?

• Experimente a Dispatch API de forma independente

• Adicione a Number Insight API ao aplicativo para verificar o formato do número ou até mesmo se o número de telefone está localizado no mesmo local indicado pela API de geolocalização

• Use a Verify API para garantir que o usuário seja o titular do número de telefone que está registrando

• Compartilhe sua opinião conosco enviando um tweet para @NexmoDev