RapidSMS Routers

The router is the message processing component of RapidSMS. It provides the infrastructure and defines the workflow to receive, process and send text messages. Each RapidSMS project can use only one router, which should be chosen based on the needs of the project.

The basics:

  • You may use any router, but only one router can be used per project.

  • Each router contains a collection of installed apps and backends.

  • All routers will trigger a set of phases for message processing.

Application and router behavior in RapidSMS are intertwined. In this section, we focus on the behavior specific to the router, with references to some key areas where this behavior is tied to applications. For more information about processing messages in applications, see the applications documentation.

Choosing a Router

Each RapidSMS project can use only one router, which should be chosen based on the needs of the project. The path to your chosen router must go in the RAPIDSMS_ROUTER setting:

RAPIDSMS_ROUTER = 'path.to.your.RouterClass'

The default router is rapidsms.router.blocking.BlockingRouter.

The choice of router is an important decision that will affect your message processing performance. For example, some routers are easy to set up but will struggle with large message volumes. More complex routers may process messages more efficiently, but require more work to set up.

Supplied Routers

RapidSMS includes several routers for you to use:

  • BlockingRouter - Default router that processes messages synchronously within the HTTP thread.

  • CeleryRouter - Celery-enabled router that processes messages asynchronously.

  • DatabaseRouter - Database, Celery-enabled router that queues messages in the database for asynchronous processing.

Here are some characteristics of the supplied routers. B is the blocking router, C is the Celery router, and D is the database router.

B

C

D

Characteristic

n

n

y

Stores messages in database

n

y

y

Requires Celery

y

n

n

Delays in one operation can block all other operations

n

n

y

Can recover and retry failed sends

n

n

y

Keeps a record of which messages have been sent and whether the send was successful

If you can’t find a router that’s suitable for your needs, you can write a custom router.

Using a custom router

While RapidSMS includes support for a number of routers out-of-the-box, sometimes you may want to use a customized router. To use a custom router with RapidSMS, use the dotted Python path to the router class for the RAPIDSMS_ROUTER setting, like so:

RAPIDSMS_ROUTER = 'path.to.RouterClass'

If you’re building your own router, you can use the standard routers as reference implementations. All routers should extend from BlockingRouter.

Applications and Backends

While the router provides the foundation for messaging processing, applications and backends actually perform the message processing:

  • Applications: The router maintains a collection of related applications through which it routes incoming and outgoing messages. Applications are defined in INSTALLED_APPS and loaded, by default, when the router is instantiated via add_app.

  • Backends: The router also maintains a collection of related backends to send outgoing messages. Backends are defined in INSTALLED_BACKENDS and loaded, by default, when the router is instantiated via add_backend.

Message Processing

The Messaging API defines send and receive to route messages through the router. Messages are processed via a series of phases, depending on direction. These phases are outlined below.

Incoming Messages

Note

See also the application documentation on incoming message processing.

Incoming messages are processed in five phases. Each application provides code for executing the phases. The router method defines hooks which allow an application to filter out a message, skip phases, or stop further processing.

  1. filter - Optionally abort all further processing of the incoming message (including cleanup).

  2. parse - Modify the message in a way that is globally useful.

  3. handle - Respond to the incoming message.

  4. default - Execute a default action if no application returns true during the handle phase.

  5. cleanup - Clean up work from previous phases.

The order in which the router chooses applications to process messages is extremely important, because each application will have the opportunity to block subsequent applications from processing a message. receive_incoming processes messages in the order they are listed in INSTALLED_APPS.

Outgoing Messages

Note

See also the application documentation on outgoing message processing.

send_outgoing processes messages sequentially, in the order they are listed in INSTALLED_APPS. However, the applications are called in reverse order, so the first application called to process an incoming message is the last application that is called to process an outgoing message. If any application returns False during the outgoing phase, all further processing of the message will be aborted.