You know how to receive and reply to incoming SMS messages. What if you receive an MMS message containing an image you'd like to download? Let's learn how we can grab that image and any other incoming MMS media using Django.
When Twilio receives a message for your phone number, it can make an HTTP call to a webhook that you create.
Twilio expects, at the very least, for your webhook to return a 200 OK
response if everything is peachy. Often, however, you will return some TwiML in your response as well. TwiML is just a set of XML commands telling Twilio how you'd like it to respond to your message. Rather than manually generating the XML, we'll use the twilio.twiml.messaging_response
module in the helper library that can make generating the TwiML and the rest of the webhook plumbing easy peasy.
To install the library, run:
_10pip install twilio
Add a new route in your urls.py file that handles incoming SMS requests.
_16from django.conf import settings_16from django.conf.urls import url_16from django.conf.urls.static import static_16_16from . import views_16_16urlpatterns = [_16 url(r'^$', views.index, name='index'),_16 url(r'^config/$', views.config, name='config'),_16 url(r'^images/$', views.get_all_media, name='images'),_16 url(r'^images/(?P<filename>[0-9A-Za-z\.]{0,50})$', views.handle_delete_media_file, name='delete_image'),_16 url(r'^incoming/$', views.handle_incoming_message, name='incoming'),_16]_16_16if settings.DEBUG:_16 urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
When Twilio calls your webhook, it sends a number of parameters about the message you just received. Most of these, such as the To
phone number, the From
phone number, and the Body
of the message are available as properties of the request body.
Since an MMS message can have multiple attachments, Twilio will send us form variables named MediaUrlX
, where X is a zero-based index. So, for example, the URL for the first media attachment will be in the MediaUrl0
parameter, the second in MediaUrl1
, and so on.
In order to handle a dynamic number of attachments, we pull the URLs out of the request body like this:
_56import os_56import sys_56import logging_56import mimetypes_56import requests_56_56from django.core import serializers_56from django.http import HttpResponse, JsonResponse_56from django.shortcuts import render_56from django.views.decorators.csrf import csrf_exempt_56from core.receive_mms import *_56_56_56logger = logging.getLogger(__name__)_56_56_56def index(request):_56 return render(request, 'receive_mms/index.html')_56_56_56def config(_):_56 return JsonResponse({'twilioPhoneNumber': os.getenv('TWILIO_NUMBER', '')})_56_56_56# /images/_56def get_all_media(_):_56 return JsonResponse({'data': fetch_all_media()})_56_56_56# /images/:filename_56@csrf_exempt_56def handle_delete_media_file(_, filename=None):_56 try:_56 media_content, mime_type = delete_media_file(filename)_56 return HttpResponse(media_content, content_type=mime_type)_56 except MMSMedia.DoesNotExist as err:_56 logger.error(err)_56 return JsonResponse({_56 'status': False,_56 'message': 'Could not find any media file with name: {}'.format(filename)_56 }, status=404)_56_56_56# /incoming/_56@csrf_exempt_56def handle_incoming_message(request):_56 message_sid = request.POST.get('MessageSid', '')_56 from_number = request.POST.get('From', '')_56 num_media = int(request.POST.get('NumMedia', 0))_56_56 media_files = [(request.POST.get("MediaUrl{}".format(i), ''),_56 request.POST.get("MediaContentType{}".format(i), ''))_56 for i in range(0, num_media)]_56_56 response = reply_with_twiml_message(message_sid, from_number, num_media, media_files)_56 return HttpResponse(response, content_type='application/xml')
Attachments to MMS messages can be of many different file types. JPG and GIF images as well as MP4 and 3GP files are all common. Twilio handles the determination of the file type for you and you can get the standard mime type from the MediaContentTypeX
parameter. If you are expecting photos, then you will likely see a lot of attachments with the mime type image/jpeg
.
_59import os_59import mimetypes_59import requests_59_59from twilio.rest import Client_59from twilio.twiml.messaging_response import MessagingResponse_59from core.models import MMSMedia_59_59# Python 2 and 3: alternative 4_59try:_59 from urllib.parse import urlparse_59except ImportError:_59 from urlparse import urlparse_59_59_59def reply_with_twiml_message(message_sid, from_number, num_media, media_files):_59 if not from_number or not message_sid:_59 raise Exception('Please provide a From Number and a Message Sid')_59_59 for (media_url, mime_type) in media_files:_59 file_extension = mimetypes.guess_extension(mime_type)_59 media_sid = os.path.basename(urlparse(media_url).path)_59 content = requests.get(media_url).text_59 filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)_59_59 mms_media = MMSMedia(_59 filename=filename,_59 mime_type=mime_type,_59 media_sid=media_sid,_59 message_sid=message_sid,_59 media_url=media_url,_59 content=content)_59 mms_media.save()_59_59 response = MessagingResponse()_59 message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)_59 response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))_59 return response_59_59_59def delete_media_file(filename=None):_59 m = MMSMedia.objects.get(filename=filename)_59 _twilio_client().api.messages(m.message_sid) \_59 .media(m.media_sid) \_59 .delete()_59 m.delete()_59_59 return m.content, m.mime_type_59_59_59def fetch_all_media():_59 return map(lambda mms: mms.filename, MMSMedia.objects.all())_59_59_59def _twilio_client():_59 account_sid = os.getenv('TWILIO_ACCOUNT_SID')_59 auth_token = os.getenv('TWILIO_AUTH_TOKEN')_59_59 return Client(account_sid, auth_token)
Depending on your use case, storing the URLs of the images (or videos or whatever) may be all you need. There are two key features to these URLs that make them very pliable for your use in your apps:
For example, if you are building a browser-based app that needs to display the images, all you need to do is drop an <img src="twilio url to your image">
tag into the page. If this works for you, then perhaps all you need is to store the URL in a database character field.
If you want to save the media attachments to a file, then you will need to make an HTTP request to the media URL and write the response stream to a file. If you need a unique filename, you can use the last part of the media URL. For example, suppose your media URL is the following:
_10https://api.twilio.com/2010-04-01/Accounts/ACxxxx/Messages/MMxxxx/Media/ME27be8a708784242c0daee207ff73db67
You can use that last part of the URL as a unique filename and look up the corresponding file extension for the mime type.
_59import os_59import mimetypes_59import requests_59_59from twilio.rest import Client_59from twilio.twiml.messaging_response import MessagingResponse_59from core.models import MMSMedia_59_59# Python 2 and 3: alternative 4_59try:_59 from urllib.parse import urlparse_59except ImportError:_59 from urlparse import urlparse_59_59_59def reply_with_twiml_message(message_sid, from_number, num_media, media_files):_59 if not from_number or not message_sid:_59 raise Exception('Please provide a From Number and a Message Sid')_59_59 for (media_url, mime_type) in media_files:_59 file_extension = mimetypes.guess_extension(mime_type)_59 media_sid = os.path.basename(urlparse(media_url).path)_59 content = requests.get(media_url).text_59 filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)_59_59 mms_media = MMSMedia(_59 filename=filename,_59 mime_type=mime_type,_59 media_sid=media_sid,_59 message_sid=message_sid,_59 media_url=media_url,_59 content=content)_59 mms_media.save()_59_59 response = MessagingResponse()_59 message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)_59 response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))_59 return response_59_59_59def delete_media_file(filename=None):_59 m = MMSMedia.objects.get(filename=filename)_59 _twilio_client().api.messages(m.message_sid) \_59 .media(m.media_sid) \_59 .delete()_59 m.delete()_59_59 return m.content, m.mime_type_59_59_59def fetch_all_media():_59 return map(lambda mms: mms.filename, MMSMedia.objects.all())_59_59_59def _twilio_client():_59 account_sid = os.getenv('TWILIO_ACCOUNT_SID')_59 auth_token = os.getenv('TWILIO_AUTH_TOKEN')_59_59 return Client(account_sid, auth_token)
Another idea for these image files could be uploading them to a cloud storage service like Azure Blob Storage or Amazon S3. You could also save them to a database, if necessary. They're just regular files at this point - let your DevOps creativity run free! In this case, we are saving them to the public directory in order to serve them later.
If you are downloading the attachments and no longer need them to be stored by Twilio, you can easily delete them. You can send an HTTP DELETE
request to the media URL, and it will be deleted, but you will need to be authenticated to do this. To make this easy, you can use the Twilio Python Helper Library. As shown here:
_59import os_59import mimetypes_59import requests_59_59from twilio.rest import Client_59from twilio.twiml.messaging_response import MessagingResponse_59from core.models import MMSMedia_59_59# Python 2 and 3: alternative 4_59try:_59 from urllib.parse import urlparse_59except ImportError:_59 from urlparse import urlparse_59_59_59def reply_with_twiml_message(message_sid, from_number, num_media, media_files):_59 if not from_number or not message_sid:_59 raise Exception('Please provide a From Number and a Message Sid')_59_59 for (media_url, mime_type) in media_files:_59 file_extension = mimetypes.guess_extension(mime_type)_59 media_sid = os.path.basename(urlparse(media_url).path)_59 content = requests.get(media_url).text_59 filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)_59_59 mms_media = MMSMedia(_59 filename=filename,_59 mime_type=mime_type,_59 media_sid=media_sid,_59 message_sid=message_sid,_59 media_url=media_url,_59 content=content)_59 mms_media.save()_59_59 response = MessagingResponse()_59 message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)_59 response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))_59 return response_59_59_59def delete_media_file(filename=None):_59 m = MMSMedia.objects.get(filename=filename)_59 _twilio_client().api.messages(m.message_sid) \_59 .media(m.media_sid) \_59 .delete()_59 m.delete()_59_59 return m.content, m.mime_type_59_59_59def fetch_all_media():_59 return map(lambda mms: mms.filename, MMSMedia.objects.all())_59_59_59def _twilio_client():_59 account_sid = os.getenv('TWILIO_ACCOUNT_SID')_59 auth_token = os.getenv('TWILIO_AUTH_TOKEN')_59_59 return Client(account_sid, auth_token)
Twilio supports HTTP Basic and Digest Authentication. Authentication allows you to password protect your TwiML URLs on your web server so that only you and Twilio can access them. Learn more about HTTP authentication and validating incoming requests here.
All the code, in a complete working project, is available on GitHub. If you need to dig a bit deeper, you can head over to our API Reference and learn more about the Twilio webhook request and the REST API Media resource. Also, you will want to be aware of the pricing for storage of all the media files that you keep on Twilio's servers.
We'd love to hear what you build with this.