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.

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

PythonJava

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.

PythonJava

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.

Tip

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.

PythonJava

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

PythonJava

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)
sms.send_sms(
    to_number=to_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.

PythonJava

# List containing the URL of the images
images = ["https://i.imgur.com/70fV8e4.png", "https://i.imgur.com/7qqUvQR.jpg"]

sms.send_sms(
    to_number=to_phone,
    msg_content="Sending 2 images!",
    media_urls=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.

PythonJava

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

PythonJava

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

print(new_sms.body)

Downloading received media content¶

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

PythonJava

# 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:
    print(new_sms.body)
    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`