Forwarding SMSs from an SMPP bind to a URL

A simple use case for Vumi is to aggregate incoming SMSs and forward them via HTTP POST to a URL.

In this use case we are going to:

  1. Use a SMSC simulator for local development.
  2. Configure Vumi accept all incoming and outgoing messages on an SMPP bind.
  3. Setup a worker that forwards all incoming messages to a URL via HTTP POST.
  4. Setup Supervisord to manage all the different processes.


Vumi relies for a large part on AMQP for its routing capabilities and some basic understanding is assumed. Have a look at for a more detailed explanation of AMQP.

Installing the SMSC simulator

Go to the ./utils directory in the Vumi repository and run the bash script called This will install the SMSC simulator from on your local machine. This simulator does exactly the same as a normal SMSC would do with the exception that it doesn’t actually relay the messages to mobile networks.:

$ cd ./utils
$ ./

This will have installed the application in the ./utils/smppsim/SMPPSim directory.

By default the SMPP simulator tries to open port 88 for it’s HTTP console, since you often need administrative rights to open ports lower than 1024 let’s change that to 8080 instead.

Line 60 of ./utils/smppsim/SMPPSim/conf/smppsim.props says:


Change this to:


Another change we need to make is on line 83:


Needs to be changed to, FALSE:


Having this set to True sometimes causes the SMSC and Vumi to bounce messages back and forth without stopping.


The simulator is a Java application and we’re assuming you have Java installed correctly.

Configuring Vumi

Vumi applications are made up of at least two components, the Transport which deals with in & outbound messages and the Application which acts on the messages received and potentially generates replies.

SMPP Transport

Vumi’s SMPP Transport can be configured by a YAML file, ./config/example_smpp.yaml. For this example, this is what our SMPP configuration looks like:

transport_name: smpp_transport
system_id: smppclient1  # username
password: password      # password
host: localhost         # the host to connect to
port: 2775              # the port to connect to

The SMPP Transport publishes inbound messages in Vumi’s common message format and accepts the same format for outbound messages.

Here is a sample message:

    "message_id": "message1",
    "to_addr": "1234",
    "from_addr": "27761234567",
    "content": "This is an incoming SMS!",
    "transport_name": "smpp_transport",
    "transport_type": "sms",
    "transport_metadata": {
        // this is a dictionary containing
        // transport specific data

HTTP Relay Application

Vumi ships with a simple application which forwards all messages it receives as JSON to a given URL with the option of using HTTP Basic Authentication when doing so. This application is also configured using the YAML file:

Setting up the webserver that responds to the HTTP request that the HTTPRelayApplication makes is left as an exercise for the reader. The HTTPRelayApplication has the ability to automatically respond to incoming messages based on the HTTP response received.

To do this:

  1. The resource must return with a status of 200
  2. The resource must set an HTTP Header X-Vumi-HTTPRelay-Reply and it must be set to true (case insensitive)
  3. Any content that is returned in the body of the response is sent back as a message. If you want to limit this to 140 characters for use with SMS then that is the HTTP resource’s responsibility.


Let’s use Supervisord to ensure all the different parts keep running. Here is the configuration file supervisord.example.conf:

[inet_http_server]         ; inet (TCP) server disabled by default
port=        ; (ip_address:port specifier, *:port for all iface)

pidfile=./tmp/pids/ ; (supervisord pidfile;default

supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

serverurl= ; use an http:// url to specify an inet socket

command=twistd -n

command=twistd -n

    -jar smppsim.jar

Ensure you’re in your python virtualenv and start it with the following command:

$ supervisord -c etc/supervisord.example.conf

You’ll be able to see the HTTP management console at http://localhost:9010/ or at the command line with:

$ supervisorctl -c etc/supervisord.example.conf

Let’s give it a try:

  1. Go to http://localhost:8080 and send an SMS to Vumi via “Inject an MO message”.
  2. Type a message, it doesn’t matter what destination_addr you chose, all incoming messages will be routed using the SMPP Transport’s transport_name to the application subscribed to those messages. The HTTPRelayApplication will HTTP POST to the URL provided.