rapidsms-twilio

Twilio backend for the RapidSMS project. Uses python-twilio to communicate with Twilio.

Build Status

Features

  • Incoming (MO) and Outgoing (MT) SMS support.
  • Support for Twilio’s status callback

Requirements

  • Python 2.7 or Python 3.3+
  • Django 1.7+
  • RapidSMS v0.18.0+

Future versions: We currently support Django 1.8 with no pending deprecation warnings in our 1.0 release. We expect each future point release to similarly support the next version of Django, so our 1.1 release would support Django 1.9 with no pending deprecation warnings. Support for older Django versions may be dropped when the period of ‘mainstream support’ expires. See Django’s supported versions documentation for those timelines.

Installation

rapidsms-twilio requires Django >= 1.7 and Python >= 2.7.

To install from PyPi:

pip install rapidsms-twilio

Documentation

Documentation on using rapidsms-twilio is available on Read The Docs.

License

rapidsms-twilio is released under the BSD License. See the LICENSE file for more details.

Contributing

If you think you’ve found a bug or are interested in contributing to this project check out rapidsms-twilio on Github.

Development by Caktus Consulting Group.

Contents

Getting Started and Setup

Below are the basic steps need to get rapidsms-twilio integrated into your RapidSMS project.

Install rapidsms-twilio:

pip install rapidsms-twilio

Add rtwilio to your INSTALLED_APPS in your settings.py file:

INSTALLED_APPS = (
    # other apps
    'rtwilio',
)

Add the following to your existing INSTALLED_BACKENDS configuration in your settings.py file:

INSTALLED_BACKENDS = {
    # ...
    # other backends, if any
    "twilio-backend": {
        "ENGINE": "rtwilio.outgoing.TwilioBackend",
        'config': {
            'account_sid': 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  # (required)
            'auth_token': 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY',  # (required)
            'number': '(###) ###-####',  # your Twilio phone number (required)
            # optional callback URL
            # 'callback': 'http://<public-django-instance>/backend/twilio/status-callback/',
        }
    },
}

Next, you need to add an endpoint to your urls.py for the newly created backend. You can do this like so:

from django.conf.urls import include, url

urlpatterns = [
    # ...
    url(r'^backend/twilio/', include('rtwilio.urls')),
]

Now inbound Twilio messages can be received at <your-server>/backend/twilio/ and outbound messages will be sent via the Twilio backend.

Status Callback

RapidSMS can take advantage of Twilio’s status callback. This is useful if you’d like to track the status of a message after it’s been passed to Twilio for processing. Twilio will use a callback URL to notify us. Enabling this feature will allow you to view delivery reports, for each message, in the Django admin.

  1. Make sure rtwilio is in INSTALLED_APPS:

    INSTALLED_APPS = (
    # other apps
    'rtwilio',
)

2. Add the callback view to your urlconf. If you are including all of the urls this is already handled for you:

urlpatterns = [
    # ...
    url(r'^backend/twilio/', include('rtwilio.urls')),
]

  1. Add the necessary database tables:

    python manage.py migrate rtwilio

  2. Add the full callback URL to your settings:

    INSTALLED_BACKENDS = {
    # ...
    # other backends, if any
    "twilio-backend": {
        "ENGINE": "rtwilio.outgoing.TwilioBackend",
        'config': {
            # same as before..
            'callback': 'http://<public-django-instance>/backend/twilio/status-callback/',
        }
    },
}

You can view delivery reports in the Django admin.

Release History

Release and change history for rapidsms-twilio

v1.0.1 (Released 2015-09-24)

  • Allow custom backends to be used with status callback (#24)

v1.0.0 (Released 2015-08-02)

This is a clean up and stablizing release for rapidsms-twilio. This removes support for old versions of Django and RapidSMS. The setup has been streamlined by changing some of the defaults.

  • Fix Twilio warning when returning data in callback response. Thanks to @lsgunth.
  • Tox and Travis improvements (#16, #20)
  • Report failed messages back to RapidSMS (#8, #22)

Backwards Incompatible Changes

  • Support for Django < 1.7 has been dropped.
  • Support for RapidSMS < 0.18 has been dropped.
  • The default url patterns have been renamed. status-callback is now twilio-status-callback to be consistent internally and with the package naming.
  • The default backend name is now twilio-backend if using the default views and url patterns.
  • The url setup in the quick start now uses an include and defaults to using /backend/twilio/ and /backend/twilio/status-callback/ for the urls. If you were including the urls manually you are not affected by this change. Otherwise you need to ensure the setup is changed in the Twilio configuration as well.

v0.3.1 (Released 2015-04-05)

Fixes a regression from the v0.3 release where the view was not marked as CSRF except.

v0.3.0 (Released 2015-03-27)

This is a minor release following up on the previous security release to turn the request validation on by default.

Backwards Incompatible Changes

  • Twilio validation is now enforced by default. To turn this off you can set validate to False in your backend configuration. This is not recommended.

v0.2.1 (Released 2015-03-27)

Security release to add support for validating incoming requests from Twilio. For backwards compatibility this is not enabled by default. You should update your backend configuration to include the new validate configuration. See the quick-start for an example configuration.

  • Improved tox testing support for RapidSMS and Django version combinations.
  • Relaxed twilio requirement.
  • Added Twilio request signature validation.

v0.2.0 (Released 2013-06-21)

Improved callback functionality and added needed tests:

  • Remove callback URL field. It’s not needed.
  • Require POST on callback view.
  • Add tests to callback view.

Bug Fixes

  • Fixed issue where using a port with the callback URL caused an error.

v0.1.0 (Released 2013-06-10)

Update for RapidSMS 0.13+.

v0.0.1 (Released 2010-07-26)

  • Initial public release.

Indices and tables

© Copyright 2007-2015, Caktus Consulting Group, LLC. Created using Sphinx 1.3.1.