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:
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.
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.
RapidSMS includes several routers for you to use:
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.
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.
While the router provides the foundation for messaging processing, applications and backends actually perform the 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.
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.
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.
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.