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.
- 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 = 'path.to.your.RouterClass'
The default router is
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.
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.
|n||n||y||Stores messages in database|
|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
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_APPSand loaded, by default, when the router is instantiated via
- Backends: The router also maintains a collection of related backends to send outgoing messages. Backends are defined in
INSTALLED_BACKENDSand loaded, by default, when the router is instantiated via
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.
- filter - Optionally abort all further processing of the incoming message (including cleanup).
- parse - Modify the message in a way that is globally useful.
- handle - Respond to the incoming message.
- default - Execute a default action if no application returns true during the handle phase.
- 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
See also the application documentation on outgoing message processing.
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
False during the outgoing phase, all further
processing of the message will be aborted.