Twilio - WhatsApp¶
Simply and securely send WhatsApp messages with Twilio APIs.
This plugin assumes that you already have a Twilio account created and configured to use phone numbers features. If you don't already have an account set up, please follow the steps through the Twilio documentation.
pip install botcity-twilio-whatsapp-plugin
Importing the Plugin¶
After you installed this package and set up your Twilio account, the next step is to import the package into your code and start using the functions.
from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin
Instantiating the plugin¶
First, let's instantiate the plugin by passing in some information from your Twilio account. All we need is the ACCOUNT SID and the AUTH TOKEN of the account, you can get this information from the Account Info section on your Twilio dashboard.
account_sid = "<YOUR_ACCOUNT_SID>" auth_token = "<YOUR_AUTH_TOKEN>" wpp_number = "+14155238886" # Instantiate the plugin for WhatsApp messages twilio_wpp = BotTwilioWhatsappPlugin(account_sid, auth_token, wpp_number)
Sending WhatsApp messages¶
We are able to send messages via WhatsApp in the same way we do for sending SMS messages. All we need is a properly configured number. In this example we are using a test number provided by Twilio, but you can configure and use your own numbers that have been approved by WhatsApp (details here).
If you have more than one WhatsApp number configured on your Twilio account, you can change the
whatsapp number property at any time during the process to define which number will be used.
wpp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number) print("Current number to be used: ", wpp.whatsapp_number) wpp.whatsapp_number = "<YOUR_SECOND_NUMBER>"
from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin account_sid = "<YOUR_ACCOUNT_SID>" auth_token = "<YOUR_AUTH_TOKEN>" # Phone numbers must be used in E.164 format # [+][country code][phone number including area code] whatsapp_number = "+14155238886" to_phone = "+5519987654321" whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number) whatsapp.send_message( to_number=to_phone, msg_content="Hello from WhatsApp! 😃" )
It is also possible to send media content, but in WhatsApp it is limited to one media per message using Twilio API. The media content must be a publicly accessible URL, just pass the URL of the media that will be attached to the message.
photo = "https://i.imgur.com/7qqUvQR.jpg" whatsapp.send_message( to_number=to_phone, msg_content="A dog photo", media_url=photo )
With this plugin we can also get messages associated with a configured WhatsApp number. We can return messages that have been sent and received by this number.
You can use filters to search for specific messages, such as the date the message was sent or the number that sent it. A list of messages will be returned and for each message it is possible to access some properties and perform some actions later.
# Instantiating the plugin whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number) # Only collects messages that have been received from a specific number. messages = whatsapp.get_received_messages(from_number="+5519987654321") # For each message found, prints: # The sender's number # The sending date # The message content for msg in messages: print(msg.from_) print(msg.date_sent) print(msg.body)
It is possible to reply to messages that were returned with the
get received messages method, we can reply to a single message or go through the list and reply to each message retrieved.
from datetime import datetime from botcity.plugins.twilio.whatsapp import BotTwilioWhatsappPlugin account_sid = "<YOUR_ACCOUNT_SID>" auth_token = "<YOUR_AUTH_TOKEN>" whatsapp_number = "+14155238886" whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number) # Get only messages that were received on 05/27/2022 msgs_to_reply = whatsapp.get_received_messages(on_date=datetime(2022, 5, 27)) # Reply for all messages with a standard message. for msg in msgs_to_reply: whatsapp.reply_message(msg, "Your message was received!")
Waiting for new messages¶
In cases where we have to wait for a new message to arrive and we don't know how long it will take, we can use the
wait for new message method. In this way, it is possible to define a maximum waiting time and the number that will send the message, when necessary.
account_sid = "<YOUR_ACCOUNT_SID>" auth_token = "<YOUR_AUTH_TOKEN>" whatsapp_number = "+14155238886" whatsapp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number) # Wait for a new message from a specific number new_msg = whatsapp.wait_for_new_message(from_number="+5519987654321") print(new_msg.body)
Downloading received media content¶
For messages that have been received and have media content, we were able to save this file on disk.
The Twilio API for WhatsApp has the limitation of one media per message. Thus, in messages that are received and have more than one media content, the API considers in the message object only the first media that was sent, discarding the others (see more details here).
# Wait for a new message new_msg = whatsapp.wait_for_new_message(from_number="+5519987654321", timeout=90) # If the message was received, save the media content if new_msg: print(new_msg.body) whatsapp.download_media_file(new_msg, download_folder_path="downloads/media")
The currently supported media content types used to save the files are defined in the table below:
|MIME type supported||Extension used to save the file|