Ir para o conteúdo

Twilio - WhatsApp

Simples e com segurança, envie mensagens do WhatsApp com APIs do Twilio.

Aviso

Este plugin assume que você já possui uma conta do Twilio criada e configurada para usar os recursos de números de telefone. Se você ainda não possui uma conta configurada, siga as etapas da documentação do Twilio.

Instalação

pip install botcity-twilio-whatsapp-plugin

Importando o plugin

Depois de instalar este pacote e configurar sua conta do Twilio, o próximo passo é importar o pacote para o seu código e começar a usar as funções.

from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin

Instanciando o plugin

Primeiro, vamos instanciar o plugin, passando algumas informações da sua conta do Twilio. Tudo o que precisamos é a ACCOUNT SID e o AUTH TOKEN da conta, você pode obter essas informações da seção Account Info no seu Twilio Dashboard.

account_sid = "<SUA_CONTA_SID>"
auth_token = "<SEU_AUTH_TOKEN>"
numero_wpp = "+14155238886"

# Instantiate the plugin for WhatsApp messages
twilio_wpp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)

Enviando mensagens do WhatsApp

Somos capazes de enviar mensagens via WhatsApp da mesma maneira que fazemos para enviar mensagens SMS. Tudo o que precisamos é de um número adequadamente configurado. Neste exemplo, estamos usando um número de teste fornecido pelo Twilio, mas você pode configurar e usar seus próprios números que foram aprovados pelo WhatsApp (detalhes aqui).

Dica

Se você tiver mais de um número do WhatsApp configurado na sua conta do Twilio, poderá alterar a propriedade whatsapp number a qualquer momento durante o processo para definir qual número será usado.

wpp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)
print("Número atual a ser usado: ", wpp.numero_wpp)
wpp.numero_wpp = "<SEU_SEGUNDO_NUMERO>"

from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin

account_sid = "<SUA_CONTA_SID>"
auth_token = "<SEU_AUTH_TOKEN>"

# Os números de telefone devem ser usados no formato E.164
# [+] [Código do país] [número de telefone, incluindo código de área]
numero_wpp = "+14155238886"
numero_destinatario = "+5519987654321"

whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)
whatsapp.send_message(
    to_number=numero_destinatario,
    msg_content="Olá do WhatsApp! 😃"
)

Também é possível enviar conteúdo de mídia, mas no WhatsApp é limitado a uma mídia por mensagem usando a API Twilio. O conteúdo da mídia deve ser um URL acessível ao público, basta passar a URL da mídia que será anexada à mensagem.

foto = "https://i.imgur.com/7qqUvQR.jpg"

whatsapp.send_message(
    to_number=numero_destinatario,
    msg_content="Uma foto de cachorro",
    media_url=photfotoo
)

Recuperando mensagens

Com este plugin, também podemos obter mensagens associadas a um número WhatsApp configurado. Podemos devolver mensagens que foram enviadas e recebidas por esse número.

Você pode usar filtros para procurar mensagens específicas, como a data em que a mensagem foi enviada ou o número que o enviou. Uma lista de mensagens será retornada e, para cada mensagem, é possível acessar algumas propriedades e executar algumas ações posteriormente.

# Instanciando o plug -in
whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)

# Apenas coleta mensagens que foram recebidas de um número específico.
mensagens = whatsapp.get_received_messages(from_number="+5519987654321")

# Para cada mensagem encontrada, imprimi:
# O número do remetente
# A data de envio
# O conteúdo da mensagem
for msg in mensagens:
    print(msg.from_)
    print(msg.date_sent)
    print(msg.body)

Respondendo mensagens

É possível responder a mensagens que foram retornadas com o método get received messages, podemos responder a uma única mensagem ou passar pela lista e responder a cada mensagem recuperada.

from datetime import datetime
from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin

account_sid = "<SUA_CONTA_SID>"
auth_token = "<SEU_AUTH_TOKEN>"
numero_wpp = "+14155238886"

whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)

# Obtenha apenas mensagens que foram recebidas em 27/05/2022
mensagens_para_responder = whatsapp.get_received_messages(on_date=datetime(2022, 5, 27))

# Responder para todas as mensagens com uma mensagem padrão.
for msg in mensagens_para_responder:
    whatsapp.reply_message(msg, "Sua mensagem foi recebida!")

Aguardando por novas mensagens

Nos casos em que precisamos esperar que uma nova mensagem chegue e não sabemos quanto tempo levará, podemos usar o método wait for new message. Dessa maneira, é possível definir um tempo de espera máximo e o número que enviará a mensagem, quando necessário.

account_sid = "<SUA_CONTA_SID>"
auth_token = "<SEU_AUTH_TOKEN>"
numero_wpp = "+14155238886"

whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, numero_wpp)

# Wait for a new message from a specific number
nova_msg = whatsapp.wait_for_new_message(from_number="+5519987654321")

print(nova_msg.body)

Baixando o conteúdo de mídia recebido

Para mensagens que foram recebidas e possuem conteúdo de mídia, conseguimos salvar esse arquivo no disco.

Aviso

A API do Twilio para o WhatsApp tem a limitação de uma mídia por mensagem. Assim, em mensagens que são recebidas e possuem mais de um conteúdo de mídia, a API considera o objeto de mensagem apenas a primeira mídia que foi enviada, descartando os outros (veja mais detalhes aqui).

# Espere por uma nova mensagem
nova_msg = whatsapp.wait_for_new_message(from_number="+5519987654321", timeout=90)

# Se a mensagem foi recebida, salve o conteúdo da mídia
if nova_msg:
    print(nova_msg.body)
    whatsapp.download_media_file(nova_msg, download_folder_path="downloads/media")

Os tipos de conteúdo de mídia atualmente suportados usados para salvar os arquivos são definidos na tabela abaixo:

Tipo MIME suportado Extensão usada para salvar o arquivo
image/jpg .jpg
image/jpeg .jpeg
image/png .png
audio/mp3 .mp3
application/pdf .pdf
video/mp4 .mp4