Skip to content

Twilio - SMS

Twilio two-way SMS and MMS messages allow you to carry on a conversation by both sending and receiving text and multimedia messages.


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-sms-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.sms import BotTwilioSMSPlugin

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>"
phone_number = "+19403534611"

# Instantiate the plugin for SMS messages
twilio_sms = BotTwilioSMSPlugin(account_sid, auth_token, phone_number)

Sending SMS messages

With a phone number obtained through your Twilio account, we can easily send SMS messages. The phone numbers provided must follow some specific formats, as shown below.


If you have more than one phone number configured on your Twilio account, you can change the phone number property at any time during the process to define which number will be used.

sms = BotTwilioSMSPlugin(account_sid, auth_token, phone)
print("Current number to be used: ", sms.phone_number)
sms.phone_number = "<YOUR_SECOND_NUMBER>"
from botcity.plugins.twilio.sms import BotTwilioSMSPlugin

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]
my_phone = "+19403534611"
to_phone = "+5519987654321"

# Sending a simple message
sms = BotTwilioSMSPlugin(account_sid, auth_token, my_phone)
    msg_content="Hey! Sending to you a simple SMS"

If your Twilio number supports MMS, we are able to send some media content in messages. The media content must be a publicly accessible URL, this way we are able to pass that URL as a list to the media urls parameter.

# List containing the URL of the images
images = ["", ""]

    msg_content="Sending 2 images!",

Retrieving messages

With this plugin we can also get messages associated with a configured phone 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.

sms = BotTwilioSMSPlugin(account_sid, auth_token, my_phone)

# Collects all messages that were received from this specific number
received_sms = sms.get_received_messages(from_number="+5519987654321")

# For each sms found, prints:
# The sending date
# The message content
for msg in received_sms:

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.

from datetime import datetime
from botcity.plugins.twilio.sms import BotTwilioSMSPlugin

account_sid = "<YOUR_ACCOUNT_SID>"
auth_token = "<YOUR_AUTH_TOKEN>"
my_phone = "+19403534611"

sms = BotTwilioSMSPlugin(account_sid, auth_token, my_phone)

# Get all messages received before 05/31/2022
messages = sms.get_received_messages(before_date=datetime(2022, 5, 31))

# Reply to all returned messages
for msg in messages:
    sms.reply_sms(msg, "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 sms 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>"
my_phone = "+19403534611"

sms = BotTwilioSMSPlugin(account_sid, auth_token, my_phone)

# Wait for a new message from a specific number
new_sms = sms.wait_for_new_sms(from_number="+5519987654321")


Downloading received media content

For messages that have been received and have media content, we were able to save this files on disk.

# Wait for a new message
new_sms = sms.wait_for_new_sms(from_number="+5519987654321", timeout=60)

# If the message was received, save the media content
if new_sms:
    sms.download_media_file(new_sms, 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
image/gif .gif
audio/mp4 .mp4
audio/mpeg .mpeg
video/mp4 .mp4
video/mpeg .mpeg
video/3gpp .3gpp
application/pdf .pdf