Dispatchers are vumi workers that route messages between sets of transports and sets of application workers.

Vumi transports and application workers both have a single endpoint on which messages are sent and received (the name of the endpoint is given by the transport_name configuration option). Connecting sets of transports and applications requires a kind of worker with multiple endpoints. This class of workers is the dispatcher.

Examples of use cases for dispatchers:

  • A single application that sends and receives both SMSes and XMPP messages.
  • A single application that sends and receives SMSes in multiple countries using a different transport in each.
  • A single SMPP transport that sends and receives SMSes on behalf of multiple applications.
  • Multiple applications that all send and receive SMSes in multiple countries using a shared set of SMPP transports.

Vumi provides a pluggable dispatch worker BaseDispatchWorker that may be extended by much simpler routing classes that implement only the logic for routing messages (see Routers). The pluggable dispatcher handles setting up endpoints for all the transports and application workers the dispatcher communicates with.

\tikzstyle{place}=[double copy shadow,
                   shape=rounded rectangle,
                   inner sep=0pt,
                   outer sep=0.3ex,
                   minimum height=1.5em,
                   minimum width=8em,
                   node distance=8em,

                  line width=0.2ex,



\node[place,dispatcher] (dispatcher) {Dispatcher};
\node[place,transport] (smpp_transport) [above left=of dispatcher] {SMPP Transport};
\node[place,transport] (xmpp_transport) [below left=of dispatcher] {XMPP Transport};
\node[place,application] (my_application) [right=of dispatcher] {My Application};

\draw[link,transport_name] (smpp_transport) to node [route] {smpp\_transport} (dispatcher);
\draw[link,transport_name] (xmpp_transport) to node [route] {xmpp\_transport} (dispatcher);
\draw[link,exposed_name] (my_application) to node [route] {my\_application} (dispatcher);

A simple dispatcher configuration. Boxes represent workers. Edges are routing links between workers. Edges are labelled with endpoint names (i.e. transport_names).

A simple BaseDispatchWorker YAML configuration file for the example above might look like:

# dispatcher config

router_class: vumi.dispatchers.SimpleDispatchRouter

  - smpp_transport
  - xmpp_transport

  - my_application

# router config

  smpp_transport: my_application
  xmpp_transport: my_application

The router_class, transport_names and exposed_names sections are all configuration for the BaseDispatchWorker itself and will be present in all dispatcher configurations:

  • router_class gives the full Python path to the class implementing the routing logic.
  • transport_names is the list of transport endpoints the dispatcher should receive and publish messages on.
  • exposed_names is the list of application endpoints the dispatcher should receive and publish messages on.

The last section, routing_mappings, is specific to the router class used (i.e. vumi.dispatchers.SimpleDispatchRouter). It lists the application endpoint that messages and events from each transport should be sent to. In this simple example message from both transports are sent to the same application worker.

Other router classes will have different router configuration options. These are described in Builtin routers.


Router classes implement dispatching of inbound and outbound messages and events. Inbound messages and events come from transports and are typically dispatched to an application. Outbound messages come from applications and are typically dispatched to a transport.

Many routers follow a simple pattern:

  • inbound messages are routed using custom routing logic.
  • events are routed towards the same application the associated message was routed to.
  • outbound messages that are replies are routed towards the transport that the original message came from.
  • outbound messages that are not replies are routed based on additional information provided by the application (in simple setups its common for the application to simply provide the name of the transport the message should be routed to).

You can read more about the routers Vumi provides and about how to write your own router class in the following sections: