Como receber mensagens do WhatsApp em Python usando Django e Twilio

Tempo de leitura: 7 minutos

April 06, 2021

Escrito por

Miguel Grinberg

Twilion

Revisado por

Diane Phan

Twilion

Como receber mensagens do WhatsApp em Python usando Django e Twilio

A API do WhatsApp Business do Twilio é um serviço eficiente e fácil de usar que possibilita a comunicação com os usuários no popular app de mensagens. Neste tutorial, você aprenderá a criar um aplicativo Python, baseado na estrutura Web do Django com o qual é possível receber e gerenciar mensagens do WhatsApp.

Pré-requisitos

Para seguir este tutorial, será necessário cumprir os seguintes requisitos:

Python 3.6 ou mais recente. Se o seu sistema operacional não fornecer um interpretador Python, você pode acessar python.org para fazer o download de um instalador.
Uma conta da Twilio. Se você é novo na Twilio, clique aqui para criar uma conta gratuita e receba 10 dólares de crédito ao atualizar para uma conta paga. Confira os recursos e as limitações de uma conta gratuita da Twilio.
Um smartphone com uma conta WhatsApp ativa para testar o projeto.

O sandbox da Twilio para WhatsApp

A Twilio oferece uma área restrita para o WhatsApp, onde é possível facilmente desenvolver e testar seu aplicativo. Depois que seu aplicativo estiver finalizado, você poderá solicitar o acesso de produção para o número de telefone da Twilio, que exige a aprovação pelo WhatsApp.

Nesta seção, você conectará seu smartphone ao sandbox. No console da Twilio, selecione Messaging (Mensagens) e clique em "Try it Out" (Experimentar). Escolha a seção WhatsApp na barra lateral à esquerda. A página da sandbox do WhatsApp mostrará o número da sandbox atribuído à sua conta e um código de ingresso.

Para ativar o sandbox do WhatsApp no smartphone, envie uma mensagem pelo WhatsApp com o código fornecido para o número atribuído à sua conta. O código começa com a palavra "join", seguida por uma frase de duas palavras gerada aleatoriamente. Logo após enviar a mensagem, você deverá receber uma resposta do Twilio indicando que seu número de celular está conectado à sandbox e já pode começar a enviar e receber mensagens.

Se pretende testar seu aplicativo com outros smartphones, repita o processo de cadastro do sandbox com cada um deles.

Configuração do projeto

Nesta seção, você configurará um novo projeto em Django. Para manter a organização, abra um terminal ou prompt de comando, encontre um local adequado e crie um novo diretório onde o projeto que você está prestes a criar será armazenado:

mkdir whatsapp-messages
cd whatsapp-messages

Como criar um ambiente virtual

Seguindo as práticas recomendadas para Python, você criará um ambiente virtual, no qual instalará as dependências do Python necessárias para este projeto.

Se você estiver usando um sistema Unix ou MacOS, abra um terminal e digite os seguintes comandos para criar e ativar seu ambiente virtual:

python3 -m venv venv
source venv/bin/activate

Se você estiver seguindo o tutorial no Windows, digite os seguintes comandos em uma janela de prompt de comando:

python -m venv venv
venv\Scripts\activate

Agora você está pronto para instalar as dependências do Python usadas por este projeto:

pip install django twilio pyngrok

Os três pacotes do Python necessários para este projeto são:

A estrutura Django para criar o aplicativo da Web.
A biblioteca auxiliar para Python da Twilio, para o funcionamento com mensagens SMS.
Pyngrok, para tornar o aplicativo Django temporariamente acessível para testes na Internet por meio do utilitário ngrok.

Como criar um projeto do Django

Nesta etapa, você criará um aplicativo da web do Django novinho em folha. Digite os seguintes comandos no mesmo terminal usado para criar e ativar o ambiente virtual:

django-admin startproject messages .
django-admin startapp whatsapp
python manage.py migrate
python manage.py runserver

O primeiro comando acima cria um projeto do Django chamado messages. Você verá um subdiretório com esse nome criado no diretório de nível superior do seu projeto. O próximo comando define um aplicativo do Django chamado whatsapp. Depois de executar esse segundo comando, você também verá um subdiretório com esse nome adicionado ao projeto. Esse é o aplicativo no qual você criará a lógica para conversar com os usuários pelo WhatsApp.

O comando migrate executa as migrações de banco de dados do Django padrão, que são necessárias para configurar totalmente o projeto do Django. O comando runserver inicia o servidor da Web de desenvolvimento do Django.

Geralmente, é recomendável deixar o servidor da Web do Django em execução enquanto você escreve o código, pois ele detecta automaticamente as alterações de código e reinicia para incorporá-las. Portanto, deixe essa janela de terminal sozinha e abra um segundo terminal para continuar o tutorial.

Iniciando um túnel ngrok

O servidor da Web do Django só está disponível localmente no computador, o que significa que não pode ser acessado pela Internet. A conexão com o WhatsApp só é possível se a Twilio puder enviar solicitações da Web para esse servidor. Assim, durante o desenvolvimento, é necessário realizar um truque para disponibilizar o servidor local na Internet.

Na segunda janela do terminal, ative o ambiente virtual e, em seguida, execute o seguinte comando:

ngrok http 8000

Esta é a aparência da tela do ngrok:

Observe o URL de encaminhamento https://. Esse URL é temporariamente mapeado para o servidor da Web do Django e pode ser acessado de qualquer lugar do mundo. Todas as solicitações que chegarem a ele serão encaminhadas de forma transparente para seu servidor pelo serviço do ngrok. O URL ficará ativo enquanto você mantiver o ngrok em execução ou até que a sessão do ngrok expire. Cada vez que o ngrok for iniciado, um novo URL gerado aleatoriamente será mapeado para o servidor local.

Abra o arquivo settings.py no diretório messages no editor de texto ou IDE. Localize a linha que contém a variável ALLOWED_HOSTS e altere-a da seguinte forma:

ALLOWED_HOSTS = ['.ngrok.io']

Isso informará o Django que as solicitações recebidas de URLs do ngrok são permitidas.

Enquanto o servidor Django e o ngrok ainda estão em execução em dois terminais diferentes, digite https://xxxxxx.ngrok.io na barra de endereço do navegador da Web para confirmar que seu projeto do Django está em funcionamento. Substitua xxxxx pelo subdomínio gerado aleatoriamente em sua sessão do ngrok. Você verá esta mensagem:

Deixe o servidor do Django e o ngrok em execução enquanto continua trabalhando no tutorial. Se sua sessão do ngrok expirar, interrompa-a pressionando Ctrl-C e inicie-a novamente para iniciar uma nova sessão. Lembre-se de que cada vez que você reiniciar o ngrok, o URL público será alterado.

Como criar um webhook do WhatsApp

A Twilio usa o conceito de webhooks para permitir que o seu aplicativo execute ações personalizadas como resultado de eventos externos, por exemplo, receber uma mensagem de um usuário no WhatsApp. Um webhook nada mais é do que um endpoint HTTP que a Twilio invoca com informações sobre o evento. A resposta retornada à Twilio fornece instruções sobre como lidar com o evento.

O webhook de uma mensagem de WhatsApp recebida inclui informações como o número de telefone do usuário e o texto da mensagem. Na resposta, o aplicativo pode fornecer uma resposta que deve ser enviada de volta ao usuário. As ações que você deseja que a Twilio execute em resposta a um evento de entrada devem ser fornecidas em TwiML, uma linguagem personalizada definida pela Twilio, baseada em XML.

Como adicionar um novo endpoint

Abra novamente o arquivo settings.py no diretório messages. Localize a variável INSTALLED_APPS. Esta é uma lista de várias strings, que são módulos padrão da estrutura do Django. No final da lista, adicione mais uma entrada para registrar o aplicativo whatsapp que você criou anteriormente.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'whatsapp.apps.WhatsappConfig',   # ← new item
]

Abra views.py no subdiretório whatsapp. É aqui que você criará o endpoint que gerenciará suas mensagens de entrada do WhatsApp. Substitua o conteúdo desse arquivo pelo seguinte:

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt


@csrf_exempt
def message(self):
    return HttpResponse('Hello!')

A função message() é a função de endpoint que será executada quando a Twilio notificar o aplicativo de uma mensagem de WhatsApp recebida. Por enquanto, essa função retorna uma resposta simples com o texto "Hello!" (Olá!).

Para tornar esse endpoint acessível por meio do aplicativo da Web, um URL precisa ser atribuído a ele. Abra o arquivo urls.py no diretório messages e adicione uma nova entrada à lista urlpatterns conforme mostrado abaixo:

from django.contrib import admin
from django.urls import path
from whatsapp import views    # ← new import

urlpatterns = [
    path('admin/', admin.site.urls),
    path('message', views.message),    # ← new item
]

A linha path('message', views.message) informa ao Django que a função message() do views.py está mapeada para um URL /message no aplicativo da Web.

Para confirmar que tudo está funcionando, volte ao navegador da Web e anexe /message ao URL do ngrok testado anteriormente. Você verá a mensagem de "Hello!" (Olá!) que o endpoint retorna na página.

Como receber mensagens do WhatsApp

A próxima etapa é atualizar a lógica dentro do endpoint message() para extrair as informações sobre a mensagem recebida. Substitua o conteúdo do arquivo views.py no subdiretório whatsapp pelo seguinte:

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt


@csrf_exempt
def message(request):
    user = request.POST.get('From')
    message = request.POST.get('Body')
    print(f'{user} says {message}')

    return HttpResponse('Hello!')

A Twilio invocará o webhook como uma solicitação POST e passará informações sobre a mensagem como variáveis de formulário, que podem ser recuperadas no Django do diretório request.POST. Os dois valores mais interessantes fornecidos são o número de telefone do usuário e o texto da mensagem, nos campos From (De) e Body (Corpo do texto) respectivamente.

Esse breve exemplo de aplicativo extrai esses dois valores e os insere no console.

Como enviar uma resposta

Para concluir o webhook, você atualizará a resposta do endpoint de modo que ela retorne a linguagem TwiML. O pacote twilio instalado no ambiente virtual fornece classes auxiliares que simplificam a geração dessas respostas.

Atualize o arquivo views.py no subdiretório whatsapp pela última vez com o seguinte código:

from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from twilio.twiml.messaging_response import MessagingResponse


@csrf_exempt
def message(request):
    user = request.POST.get('From')
    message = request.POST.get('Body')
    print(f'{user} says {message}')

    response = MessagingResponse()
    response.message('Thank for your message! A member of our team will be '
                     'in touch with you soon.')
    return HttpResponse(str(response))

Essa implementação atualizada do endpoint usa a classe MessagingResponse do pacote twilio para criar a resposta enviada ao usuário. O método message() dessa classe instrui a Twilio a responder ao usuário com a mensagem fornecida como um argumento.

Como configurar o webhook do WhatsApp

Para conectar o webhook ao WhatsApp, configure seu URL no console da Twilio. Localize a página de configurações do sandbox do WhatsApp e edite o campo "When a message comes in" (Quando uma mensagem é recebida) com o URL do seu webhook. Este será o URL do ngrok temporário com /message anexado no final. Veja um exemplo abaixo:

Certifique-se de que o menu suspenso à direita do campo URL esteja definido como "HTTP Post" (Publicação HTTP) e não se esqueça de clicar no botão "Save" (Salvar) na parte inferior da página para registar essas alterações.

Como testar seu serviço de mensagens do WhatsApp

Chegou o momento da verdade! Certifique-se de que o servidor do Django e o ngrok ainda estejam em execução. No smartphone, envie uma mensagem para o número do sandbox. Após um breve momento, você receberá uma resposta.

Ao visualizar o terminal que está executando o servidor do Django, você verá que a mensagem e seu número de telefone foram recebidos e inseridos:

Ao usar o WhatsApp nas APIs de mensagens da Twilio, todos os números de telefone têm um prefixo whatsapp:.

Próximas etapas

Espero que este tutorial tenha sido útil. Agora que você aprendeu a receber e responder mensagens no WhatsApp, talvez queira assumir um projeto um pouco mais desafiador. Se esse for o caso, acesse o tutorial sobre como construir um chatbot do WhatsApp.

Adoraria ver o que você constrói com o WhatsApp e a Twilio!

Este artigo foi traduzido do original "How to Receive WhatsApp Messages in Python using Django and Twilio". Enquanto melhoramos nossos processos de tradução, adoraríamos receber seus comentários em help@twilio.com - contribuições valiosas podem render brindes da Twilio.