Messaging API

A clean, simple API is provided to send and receive messages in RapidSMS. For most cases, you’ll just need to use the send and receive functions outlined below.

Receiving Messages

rapidsms.router.receive(text, connection, **kwargs)

Creates an incoming message and passes it to the router for processing.

  • text – text message
  • connection – RapidSMS Connection object
  • kwargs – Extra kwargs to pass to IncomingMessage constructor

IncomingMessage object constructed by router. A returned message object does not indicate that router processing has finished or even started, as this depends on the router defined in RAPIDSMS_ROUTER.

Return type:


To receive a message, you can use the receive function, which will automatically create an IncomingMessage and pass it to your router to be processed. Typically, backends will make the most use of receive, but it can be used anywhere within your application to route an incoming message (such as from a Django view).

Here’s an example using receive:

from rapidsms.router import receive
receive("echo hello", connection)

This sends a message to the router saying echo hello was received from a Connection object. You can find more examples of receive in the official RapidSMS backends.

class rapidsms.messages.incoming.IncomingMessage(*args, **kwargs)

Bases: rapidsms.messages.base.MessageBase

Inbound message that provides an API to handle responses.

respond(text, **kwargs)

Respond to this message, sending the given text to the connections that this message came from.

Responses are saved, and sent after incoming processing phases are complete.

Arbitrary arguments are passed along to the send() method.

  • text (str) – The text of the message
  • connections (list of Connection) – (optional) send to a different set of connections than were in the incoming message.
  • in_response_to (MessageBase) – (optional) the message being responded to.

dictionary with the arguments that will be passed to rapidsms.router.send() to send this response.

responses = None

list of messages created by IncomingMessage.respond()

Sending Messages

rapidsms.router.send(text, connections, **kwargs)

Creates an outgoing message and passes it to the router to be processed and sent via the respective backend.

Arbitrary arguments are passed along to new_outgoing_message().

  • text – text message
  • connections – list or QuerySet of RapidSMS Connection objects
  • kwargs – Extra kwargs to pass to OutgoingMessage constructor

message constructed by router. A returned message object does not indicate that router processing has finished or even started, as this depends on the router defined in RAPIDSMS_ROUTER.

Return type:


It’s just as easy to send a message using RapidSMS. You can send a message from anywhere within your application. Here’s an example using send:

from rapidsms.router import send
send("hello", connections)

This sends hello to each identity and backend associated with the connections object. You can find more examples of send in the official RapidSMS backends.

class rapidsms.messages.outgoing.OutgoingMessage(*args, **kwargs)

Bases: rapidsms.messages.base.MessageBase

Outbound message that can easily be sent to the router.


Specific metadata to be included when passed to backends.


Send the message. Equivalent to rapidsms.router.send(text, connections).


Both incoming and outgoing message classes inherit from a common class, MessageBase.

class rapidsms.messages.base.MessageBase(connections=None, text=None, id_=None, in_response_to=None, fields=None, connection=None)

Basic message representation with text and connection(s).


The first Connection - deprecated.

connections = None

The connections this message was received from or sent to. A list of Connection


The first connection’s Contact - deprecated

fields = None

fields can be used to pass along arbitrary metadata

static generate_id()

Create a random unique ID for this message object.

handled = None

a message can be marked “handled” by any app, which will short-circuit the default phase in the router.

id = None

a unique ID for this message

in_response_to = None

link back to original message if this is a response


Return the identity (eg. a phone number, email address, irc nickname) on the other end of this message. But you shouldn’t use this method. It only seems to encourage people to ignore the distinction between backends and identities, and create fields like “mobile_number”, which is all kinds of wrong. deprecated

processed = None

a message is considered “unprocessed” until rapidsms has dispatched it to all apps.

raw_text = None

save original text for future reference

text = None

the message


There’s also an ErrorMessage class that can be used when sending error messages.

class rapidsms.messages.error.ErrorMessage(*args, **kwargs)

Bases: rapidsms.messages.outgoing.OutgoingMessage


RapidSMS represents entities that it can communicate with using a Contact object. Each Contact has a name. A Contact could represent a person, an organization, or any other entity that might have a phone, email account, etc.

class rapidsms.models.Contact(*args, **kwargs)

Bases: rapidsms.models.ContactBase

This model represents a person with a name

Most of a Contact is represented in the ContactBase class:

class rapidsms.models.ContactBase(*args, **kwargs)

when the contact was created


Return the default connection for this person. Currently this arbitrarily returns the first connection.


Return True if the individual has no name


The contact’s preferred language. the spec: reference:


when the contact was last modified


The individual’s name (optional)


RapidSMS might be able to communicate with an entity represented by a Contact in multiple ways. The entity could have several phone numbers, email addresses, etc.

RapidSMS uses a Connection to represent each way of communicating with a Contact. Each Connection specifies a backend to use, and how the entity is identified on that backend. The identifier is called an identity, and depending on the backend, it could be a phone number, email address, or something else. Most RapidSMS code should not make any assumptions about the format of identities.

class rapidsms.models.Connection(*args, **kwargs)

Bases: rapidsms.models.ConnectionBase

This model pairs a Backend object with an identity unique to it (eg. a phone number, email address, or IRC nick), so RapidSMS developers need not worry about which backend a messge originated from.

exception DoesNotExist

Bases: django.core.exceptions.ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: django.core.exceptions.MultipleObjectsReturned

Most of a Connection is represented in the ConnectionBase class:

class rapidsms.models.ConnectionBase(*args, **kwargs)

foreign key to this connection’s BackendBase


(optional) associated Contact


when this connection was created


unique identifier for this connection on this backend (e.g. phone number, email address, IRC nick, etc.)


when this connection was last modified

Connection Lookup

rapidsms.router.lookup_connections(backend, identities)

Find connections associated with backend and identities. A new connection object will be created for every backend/identity pair not found.

  • backend – backend name (as a string) or BackendBase object
  • identities – list of identities to find associated with the backend

List of Connection objects

Since most of the time you’ll need to find connections for a backend and phone number, RapidSMS has a helper function, lookup_connections, to do the lookup for you. Additionally, if the backend and phone number connection doesn’t exist, it’ll be created automatically. Here’s an example of lookup_connections:

from rapidsms.router import send, lookup_connections
connections = lookup_connections(backend="example-backend",
send("hello", connections=connections)