Setting up RapidSMS with Vumi¶
Vumi is a free and open source super scalable messaging platform written in Python. Vumi can connect to third party gateways via protocols like HTTP and SMPP. Please read Vumi’s documentation for additional information.
The following guide will help you setup Vumi on Ubuntu to talk to a SMPP simulator and RapidSMS installation.
Using an SMPP simulator¶
For local development, it’s easy to setup an SMPP simulator for testing purposes. Vumi suggests using SMPPSim. SMPPSim is a testing utility which mimics the behavior of the Short Message Peer to Peer Protocol (SMPP) based Short Message Service Center (SMSC).
Note
SMPPSim requires Java. Please install Java before proceeding with these instructions.
To download SMPPSim, run the following commands:
wget http://www.seleniumsoftware.com/downloads/SMPPSim.tar.gz
tar zxf SMPPSim.tar.gz
SMPPSim runs on port 80 by default. Let’s set this to a higher port to make it
easier to run without superuser privileges. Open conf/smppsim.props
and
change the HTTP_PORT
line to:
HTTP_PORT=8080
You can use the provided shell scripts to start SMPPSim:
chmod +x startsmppsim.sh
./startsmppsim.sh
Now visit http://localhost:8080 to use SMPPSim’s web interface. You’ll use this interface to create mobile-originated (MO) messages to send to Vumi.
Installing and setting up Vumi for the first time¶
Note
As of this writing, the RapidSMS/Vumi integration is planned for merge into
an official Vumi release, but currently resides in the
develop
Vumi branch. When complete, we
will update this documentation accordingly.
Clone the Vumi GitHub repository:
git clone git@github.com:praekelt/vumi.git
cd vumi
git checkout develop
Install Vumi’s Python dependencies:
pip install -r requirements.pip
Setup the proper RabbitMQ user/vhost using the provided utility script:
sudo ./utils/rabbitmq.setup.sh
Create config/rapidsms.yaml
using the following configuration:
smpp_transport:
transport_name: "transport"
system_id: smppclient1 # username
password: password # password
host: localhost # the host to connect to
port: 2775 # the port to connect to
rapidsms_relay:
transport_name: 'transport'
rapidsms_url: "http://127.0.0.1:8000/backend/vumi-fake-smsc/"
web_path: "/send/"
web_port: 9000
send_to:
default:
transport_name: 'transport'
from_addr: '1234' # not set automatically by SMSC
workers:
smpp_transport: vumi.transports.smpp.SmppTransport
rapidsms_relay: vumi.application.rapidsms_relay.RapidSMSRelay
This configures a Vumi SmppTransport
to communicate to
SMPPSim and a Vumi RapidSMSRelay
to communicate to
RapidSMS. While not required for this setup, you’ll need to set from_addr
to your phone number if using a real SMSC.
Now we can start Vumi using our config file:
twistd -n start_worker --worker-class vumi.multiworker.MultiWorker --config config/rapidsms.yaml
Adding a backend for the fake SMSC to RapidSMS¶
Now that Vumi is installed and configured correctly, adding support for the
Vumi backend to your existing RapidSMS project is not difficult. To begin,
simply add the following to your existing INSTALLED_BACKENDS
:
INSTALLED_BACKENDS = {
# ...
# other backends, if any
"vumi-fake-smsc": {
"ENGINE": "rapidsms.backends.vumi.VumiBackend",
"sendsms_url": "http://127.0.0.1:9000/send/",
},
}
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.defaults import *
from rapidsms.backends.vumi.views import VumiBackendView
urlpatterns = patterns('',
# ...
url(r"^backend/vumi-fake-smsc/$",
VumiBackendView.as_view(backend_name="vumi-fake-smsc")),
)
You can make the Django URL pattern whatever you like, but the convention is to
make it backend/
followed by the name of your backend (from the settings
file) and a final /
.
Now, you should be able to start RapidSMS like so:
./manage.py runserver
That’s it! Now you can use SMPPSim to send mobile-originated (MO) messages through Vumi to RapidSMS.
Authentication¶
Vumi can be protected with basic authentication. To enable it on the Vumi side,
create a passwords
directive in the rapidsms_relay
configuration:
rapidsms_relay:
transport_name: 'transport'
rapidsms_url: "http://127.0.0.1:8000/backend/vumi-fake-smsc/"
web_path: "/send/"
web_port: 9000
send_to:
default:
transport_name: 'transport'
from_addr: '1234' # not set automatically by SMSC
vumi_username: 'username'
vumi_password: 'password'
Then you can update INSTALLED_BACKENDS
with sendsms_user
and
sendsms_pass
:
INSTALLED_BACKENDS = {
"vumi-fake-smsc": {
"ENGINE": "rapidsms.backends.vumi.VumiBackend",
"sendsms_url": "http://127.0.0.1:9000/send/",
"sendsms_user": "username",
"sendsms_pass": "password",
},
}