• Twilio Guides

Receive and Download Images on Incoming MMS Messages with Python and Django

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.

Create MMS Processing Project

Create a Django application

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:

pip install twilio

Create Router

Add a new route in your urls.py file that handles incoming SMS requests.

Loading Code Samples...
Language
from django.conf import settings
from django.conf.urls import url
from django.conf.urls.static import static

from . import views

urlpatterns = [
    url(r'^$', views.index, name='index'),
    url(r'^config/$', views.config, name='config'),
    url(r'^images/$', views.get_all_media, name='images'),
    url(r'^images/(?P<filename>[0-9A-Za-z\.]{0,50})$', views.handle_delete_media_file, name='delete_image'),
    url(r'^incoming/$', views.handle_incoming_message, name='incoming'),
]

if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
Handle Incoming SMS Routes - Django

Receive MMS Message and Images

Get Incoming Message Details

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.

Get URLs to the Media

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:

Loading Code Samples...
Language
import os
import sys
import logging
import mimetypes
import requests

from django.core import serializers
from django.http import HttpResponse, JsonResponse
from django.shortcuts import render
from django.views.decorators.csrf import csrf_exempt
from core.receive_mms import *


logger = logging.getLogger(__name__)


def index(request):
    return render(request, 'receive_mms/index.html')


def config(_):
    return JsonResponse({'twilioPhoneNumber': os.getenv('TWILIO_NUMBER', '')})


# /images/
def get_all_media(_):
    return JsonResponse({'data': fetch_all_media()})


# /images/:filename
@csrf_exempt
def handle_delete_media_file(_, filename=None):
    try:
        media_content, mime_type = delete_media_file(filename)
        return HttpResponse(media_content, content_type=mime_type)
    except MMSMedia.DoesNotExist as err:
        logger.error(err)
        return JsonResponse({
            'status': False,
            'message': 'Could not find any media file with name: {}'.format(filename)
          }, status=404)


# /incoming/
@csrf_exempt
def handle_incoming_message(request):
    message_sid = request.POST.get('MessageSid', '')
    from_number = request.POST.get('From', '')
    num_media = int(request.POST.get('NumMedia', 0))

    media_files = [(request.POST.get("MediaUrl{}".format(i), ''),
                    request.POST.get("MediaContentType{}".format(i), ''))
                   for i in range(0, num_media)]

    response = reply_with_twiml_message(message_sid, from_number, num_media, media_files)
    return HttpResponse(response, content_type='application/xml')
Handle Incoming SMS Views - Django

Determine Content Type of Media

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.

Loading Code Samples...
Language
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)
Map MIME Type To File Extension

Process MMS Images

Save the Media URLs

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:

  1. They are publicly accessible without any need for authentication which makes sharing easy.
  2. They are permanent (unless you explicitly delete the media).

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.

Save Media to Local File System

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:

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

Loading Code Samples...
Language
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)
Handle Incoming SMS Endpoints - Django

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. Go crazy. In this case, we are saving them to the public directory in order to serve them later.

Delete Media from Twilio

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:

Loading Code Samples...
Language
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)
Delete Media From Twilio Servers

What’s Next?

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.

Jose Oliveros
David Prothero
Kat King
Agustin Camino
Samuel Mendes

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
from django.conf import settings
from django.conf.urls import url
from django.conf.urls.static import static

from . import views

urlpatterns = [
    url(r'^$', views.index, name='index'),
    url(r'^config/$', views.config, name='config'),
    url(r'^images/$', views.get_all_media, name='images'),
    url(r'^images/(?P<filename>[0-9A-Za-z\.]{0,50})$', views.handle_delete_media_file, name='delete_image'),
    url(r'^incoming/$', views.handle_incoming_message, name='incoming'),
]

if settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)
import os
import sys
import logging
import mimetypes
import requests

from django.core import serializers
from django.http import HttpResponse, JsonResponse
from django.shortcuts import render
from django.views.decorators.csrf import csrf_exempt
from core.receive_mms import *


logger = logging.getLogger(__name__)


def index(request):
    return render(request, 'receive_mms/index.html')


def config(_):
    return JsonResponse({'twilioPhoneNumber': os.getenv('TWILIO_NUMBER', '')})


# /images/
def get_all_media(_):
    return JsonResponse({'data': fetch_all_media()})


# /images/:filename
@csrf_exempt
def handle_delete_media_file(_, filename=None):
    try:
        media_content, mime_type = delete_media_file(filename)
        return HttpResponse(media_content, content_type=mime_type)
    except MMSMedia.DoesNotExist as err:
        logger.error(err)
        return JsonResponse({
            'status': False,
            'message': 'Could not find any media file with name: {}'.format(filename)
          }, status=404)


# /incoming/
@csrf_exempt
def handle_incoming_message(request):
    message_sid = request.POST.get('MessageSid', '')
    from_number = request.POST.get('From', '')
    num_media = int(request.POST.get('NumMedia', 0))

    media_files = [(request.POST.get("MediaUrl{}".format(i), ''),
                    request.POST.get("MediaContentType{}".format(i), ''))
                   for i in range(0, num_media)]

    response = reply_with_twiml_message(message_sid, from_number, num_media, media_files)
    return HttpResponse(response, content_type='application/xml')
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)
import os
import mimetypes
import requests

from twilio.rest import Client
from twilio.twiml.messaging_response import MessagingResponse
from core.models import MMSMedia

# Python 2 and 3: alternative 4
try:
    from urllib.parse import urlparse
except ImportError:
    from urlparse import urlparse


def reply_with_twiml_message(message_sid, from_number, num_media, media_files):
    if not from_number or not message_sid:
        raise Exception('Please provide a From Number and a Message Sid')

    for (media_url, mime_type) in media_files:
        file_extension = mimetypes.guess_extension(mime_type)
        media_sid = os.path.basename(urlparse(media_url).path)
        content = requests.get(media_url).text
        filename = '{sid}{ext}'.format(sid=media_sid, ext=file_extension)

        mms_media = MMSMedia(
            filename=filename,
            mime_type=mime_type,
            media_sid=media_sid,
            message_sid=message_sid,
            media_url=media_url,
            content=content)
        mms_media.save()

    response = MessagingResponse()
    message = 'Send us an image!' if not num_media else 'Thanks for the {} images.'.format(num_media)
    response.message(body=message, to=from_number, from_=os.getenv('TWILIO_NUMBER'))
    return response


def delete_media_file(filename=None):
    m = MMSMedia.objects.get(filename=filename)
    _twilio_client().api.messages(m.message_sid) \
        .media(m.media_sid) \
        .delete()
    m.delete()

    return m.content, m.mime_type


def fetch_all_media():
    return map(lambda mms: mms.filename, MMSMedia.objects.all())


def _twilio_client():
    account_sid = os.getenv('TWILIO_ACCOUNT_SID')
    auth_token = os.getenv('TWILIO_AUTH_TOKEN')

    return Client(account_sid, auth_token)