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¶
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.
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.
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.
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.
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:
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.
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.
Downloading received media content¶
For messages that have been received and have media content, we were able to save this files on disk.
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 |