Transmissão de dados em tempo real para vários canais por meio da Messages API

Este tutorial mostra como enviar dados para vários canais em tempo real usando a Messages API. Ele demonstra como enviar dados para todos os canais compatíveis. São fornecidas informações sobre como testar todos os canais. Se você estiver interessado em fazer testes usando o Facebook Messenger, recomenda-se que você siga as etapas descritas em este tutorial Em primeiro lugar, porque esse tutorial contém muitas informações específicas do Facebook. Para testar o WhatsApp e o Viber, você precisará de accounts comerciais nesses serviços.

Cenário de exemplo

Neste tutorial, você aprenderá a enviar cotações de ações em tempo real para um usuário no canal de sua escolha. Um usuário pode se cadastrar para receber dados em qualquer canal compatível de sua preferência. Por exemplo, ele pode receber as cotações de ações pelo celular via SMS ou pelo Facebook Messenger. O WhatsApp e o Viber também são compatíveis. No Facebook Messenger, no WhatsApp e por SMS, os usuários podem se cadastrar para receber informações sobre uma ação específica. No entanto, o Viber não suporta mensagens recebidas por uma empresa; portanto, os usuários precisariam se cadastrar por meio de um site para receber os dados. Além disso, no caso do WhatsApp, há uma complicação adicional: o WhatsApp exige que a empresa envie ao usuário um MTM antes que o usuário possa concordar em receber mensagens.

Observe que, neste tutorial, são utilizados apenas preços simulados de ações.

Código-fonte

O código-fonte em Python deste projeto está disponível na Comunidade Vonage Repositório do GitHub. De particular interesse é um cliente genérico que oferece uma maneira prática de enviar uma mensagem para qualquer canal compatível com uma única chamada de método. Você também verá código em Python para lidar com mensagens recebidas no WhatsApp, SMS e Messenger.

Pré-requisitos

Criar um Account na Vonage
Instalar o Node.js - necessário para utilizar a Interface de Linha de Comando (CLI) da Vonage.
Instale o CLI da Vonage
Saiba como testar seu servidor de webhooks localmente
Python 3 instalado
Flask instalado
Tenha contas nos canais que você deseja utilizar, como Facebook, Viber e WhatsApp.

Você também pode achar útil consultar os seguintes tópicos de visão geral:

Se você pretende testar esse caso de uso com o Facebook Messenger, é recomendável que você siga as etapas descritas em este tutorial primeiro.

As etapas

Depois que os pré-requisitos forem atendidos, as etapas são as seguintes:

Criar uma aplicação da Vonage
Configure o Ngrok
Configure seus webhooks de SMS no Painel
Escreva seu aplicativo básico
Envie um SMS
Revisar o código do cliente genérico
O caso de uso revisitado
Testando o aplicativo

Existem várias maneiras de obter o mesmo resultado com o Vonage. Este tutorial mostra apenas uma maneira específica de fazer as coisas; por exemplo, você verá como usar a linha de comando para criar o aplicativo, em vez do Painel de Controle. Outros tutoriais demonstram outras maneiras de fazer as coisas.

Crie sua aplicação Vonage

Se ainda não tiver feito isso, crie um novo diretório para o seu projeto, como, por exemplo, real-time-app. Vá para este diretório.

Use a CLI para criar seu aplicativo Vonage:

vonage apps:create "Real-time App" --messages_inbound_url=https://abcd1234.ngrok.io/inbound --messages_status_url=https://abcd1234.ngrok.io/status

Anote o ID do aplicativo gerado. Você também pode verificar isso no painel de controle.

Esse comando também criará uma chave privada, real_time_app.key no diretório atual, bem como atualizar/criar vonage_app.json.

Esse comando também configura os dois webhooks por meio dos quais ocorre toda a interação entre seu aplicativo e a Vonage. É necessário que você tenha um servidor em execução e acessível à Vonage nessas URLs.

Configure o Ngrok

Certifique-se de que o Ngrok esteja em execução para realizar testes localmente. Para iniciar o Ngrok, digite:

ngrok http 9000

Para gerar uma URL temporária do Ngrok. Se você for um assinante pago, pode digitar:

ngrok http 9000 -subdomain=your_domain

Observe que, neste caso, o Ngrok redirecionará os webhooks do Vonage que você especificou ao criar seu aplicativo do Vonage para localhost:9000.

Configure seus webhooks de SMS no Painel

No Painel, acesse configurações da conta. Aqui você pode configurar seus webhooks de SMS no nível da Account:

Webhook	URL
Recibo de entrega	https://abcd1234.ngrok.io/webhooks/delivery-receipt
SMS recebidas	https://abcd1234.ngrok.io/webhooks/inbound-sms

Observe que você precisará substituir “abcd1234” nas URLs dos webhooks pelas suas próprias informações. Se você tiver um Account pago no Ngrok, esse pode ser o seu domínio personalizado.

NOTA: É necessário seguir esta etapa, pois os aplicativos Messages e Dispatch, no momento, suportam apenas SMS de saída, e não SMS de entrada. Por esse motivo, você utilizará os webhooks de SMS no nível da conta para lidar com SMS de entrada, mas utilizará a Messages API para enviar SMS de saída.

Escreva seu aplicativo básico

No caso mais simples, seu aplicativo registraria as informações das mensagens recebidas, bem como os dados de confirmação de entrega e de status das mensagens. Isso ficaria mais ou menos assim:

from flask import Flask, request, jsonify
from pprint import pprint

app = Flask(__name__)

@app.route('/webhooks/inbound', methods=['POST'])
def inbound_message():
    print ("** inbound_message **")
    data = request.get_json()
    pprint(data)
    return ("inbound_message", 200)

@app.route('/webhooks/status', methods=['POST'])
def message_status():
    print ("** message_status **")
    data = request.get_json()
    pprint(data)
    return ("message_status", 200)

@app.route('/webhooks/inbound-sms', methods=['POST'])
def inbound_sms():
    print ("** inbound_sms **")
    values = request.values
    pprint(values)
    return ("inbound_sms", 200)

@app.route('/webhooks/delivery-receipt', methods=['POST'])
def delivery_receipt():
    print ("** delivery_receipt **")
    data = request.get_json()
    pprint(data)
    return ("delivery_receipt", 200)

if __name__ == '__main__':
    app.run(host="localhost", port=9000)

Adicione este código a um arquivo chamado app1.py e salve-o.

Execute localmente com:

python3 app1.py

Envie um SMS

Seu aplicativo básico já está em funcionamento e pronto para registrar eventos. Você pode testar esse aplicativo básico enviando um SMS para qualquer número da Vonage vinculado a qualquer aplicativo de voz, desde que o número da Vonage tenha recursos de voz e SMS. Se você não tiver um aplicativo de voz e não souber como criar um, pode consultar essas informações. O motivo pelo qual você precisa seguir essa etapa adicional é que, atualmente, a Messages API e a Dispatch API não oferecem suporte a SMS recebidas, apenas a SMS enviadas; portanto, você precisa usar o webhook no nível da conta para receber notificações por SMS.

Ao examinar as informações de rastreamento geradas ao enviar um SMS, você verá algo semelhante ao seguinte:

** inbound_sms ** {'keyword': 'MESSAGE', 'message-timestamp': '2019-04-16 13:55:21', 'messageId': '1700000240EAA6B6', 'msisdn': '447700000001', 'text': 'Message from Tony', 'to': '447520635498', 'type': 'text'}

Cliente genérico

Atualmente, a Vonage não oferece suporte oficial às APIs Messages e Dispatch no SDK para servidor em Python, mas nossa API REST é compatível (versão beta) e a O código em Python é fornecido no projeto, em uma classe reutilizável. Essa classe permite enviar uma mensagem usando a Messages API para qualquer um dos canais compatíveis. Vale a pena dar uma olhada rápida no código:

    def send_message (self, channel_type, sender, recipient, msg):
        if channel_type == 'messenger':
            from_field = "id"
            to_field = "id"
        elif channel_type == 'whatsapp' or channel_type == "sms": 
            from_field = "number"
            to_field = "number"
        elif channel_type == 'viber_service_msg':
            from_field = "id"
            to_field = "number"
               
        data_body = json.dumps({
            "from": {
	        "type": channel_type,
	        from_field: sender
            },
            "to": {
	        "type": channel_type,
	        to_field: recipient
            },
            "message": {
	        "content": {
	            "type": "text",
	            "text": msg
	        }
            }
        })
...

O que acontece é que o corpo da mensagem é gerado para você com base no tipo de canal. Isso ocorre porque os detalhes variam um pouco entre os canais — por exemplo, o Facebook usa IDs, enquanto o WhatsApp e o SMS usam apenas números. O Viber usa um ID e um número. Em seguida, o código utiliza a Messages API para enviar a mensagem para você. Essa é a base do caso de uso, com alguns detalhes adicionais para permitir o cadastro do usuário.

O caso de uso revisitado

É hora de analisar esse caso de uso com mais detalhes para que você possa desenvolver seu aplicativo de forma mais eficaz.

Para canais que suportam mensagens recebidas (Messenger, WhatsApp e SMS), você pode permitir que o usuário envie uma mensagem para se inscrever. No caso do Viber, isso terá que ser feito por meio de outra seção do aplicativo web. Normalmente, você disponibilizaria um formulário no qual o usuário pudesse se inscrever para receber o feed em tempo real.

Se um usuário enviar uma mensagem, como “Oi”, o aplicativo responderá com uma mensagem de ajuda. No nosso caso, essa mensagem é: “Envie-nos uma mensagem contendo MSFT ou GOOGL para obter dados em tempo real”. Essa inscrição será então confirmada por outra mensagem informando qual feed você assinou.

Em seguida, você receberá a cotação em tempo real do código da ação selecionado. Se desejar se inscrever em outro canal, fique à vontade para fazê-lo. Além disso, caso queira alterar o código da ação, envie uma mensagem com o novo código: a solicitação será confirmada e o fluxo de dados será atualizado de acordo.

O código principal para implementar isso está localizado na função proc_inbound_msg em app_funcs.py.

No WhatsApp, você teria uma etapa adicional em que precisaria enviar um Mensagem MTM ao usuário antes que ele possa se cadastrar para receber dados. Por uma questão de simplicidade, isso é fornecido como um trecho de código separado.

Testando o aplicativo

Você pode executar o aplicativo com:

python3 app.py APP_ID

Onde APP_ID é o ID do aplicativo Vonage do seu aplicativo “Mensagens”.

SMS

Para testar o envio de SMS, envie uma mensagem como fez anteriormente. Você receberá uma mensagem de ajuda. Responda com o código da ação de uma das seguintes opções: MSFT ou GOOGL. Você receberá então, periodicamente, uma atualização (simulada) de preços. Atualmente, é preciso sair do aplicativo para deixar de receber essas notificações, mas seria possível adicionar a opção de desativar essas mensagens, conforme demonstrado em este tutorial.

Facebook Messenger

Para realizar testes com o Facebook Messenger, são necessárias algumas etapas adicionais. Elas foram abordadas em detalhes em este tutorial, por isso essa informação não foi repetida aqui.

Viber

Você precisaria de um account empresarial válido do Viber para testar isso. Haveria uma parte do seu aplicativo web que solicitaria ao usuário fornece o número de telefone e o símbolo que lhes interessem. O usuário poderia então receber uma mensagem inicial, que teria a opção de aceitar ou recusar. A pequeno programa de teste é fornecido para demonstrar como testar o cliente genérico com o Viber.

O WhatsApp exige uma etapa adicional para que o teste seja completo. É necessário enviar ao usuário um MTM (modelo) do WhatsApp antes que ele possa receber qualquer mensagem. O código para fazer isso não foi descrito neste tutorial, mas há um código de exemplo disponível aqui. Você pode então usar o cliente genérico fornecido neste tutorial para enviar mensagens subsequentes pelo WhatsApp.

Resumo

Neste tutorial, você viu um caso de uso em que o usuário pode receber dados em tempo real em qualquer canal compatível com a Messages API.