Twilio - WhatsApp¶

Simply and securely send WhatsApp messages with Twilio APIs.

Warning

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.

Installation¶

PythonJava

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.

PythonJava

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.

PythonJava

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).

Tip

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.

PythonJava

wpp = BotTwilioWhatsappPlugin(account_sid, auth_token, whatsapp_number)
print("Current number to be used: ", wpp.whatsapp_number)
wpp.whatsapp_number = "<YOUR_SECOND_NUMBER>"

PythonJava

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.

PythonJava

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

whatsapp.send_message(
    to_number=to_phone,
    msg_content="A dog photo",
    media_url=photo
)

Retrieving messages¶

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.

PythonJava

# 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)

Replying messages¶

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.

PythonJava

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.

PythonJava

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.

Warning

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).

PythonJava

# 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
`image/jpg`	`.jpg`
`image/jpeg`	`.jpeg`
`image/png`	`.png`
`audio/mp3`	`.mp3`
`application/pdf`	`.pdf`
`video/mp4`	`.mp4`