A clean, simple API is provided to send and receive messages in RapidSMS. For
most cases, you’ll just need to use the
receive(text, connection, **kwargs)¶
Creates an incoming message and passes it to the router for processing.
IncomingMessageobject 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
To receive a message, you can use the
receive function, which will
automatically create an
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
from rapidsms.router import receive receive("echo hello", connection)
Inbound message that provides an API to handle responses.
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
dictionary with the arguments that will be passed to
rapidsms.router.send()to send this response.
list of messages created by IncomingMessage.respond()
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
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
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
from rapidsms.router import send send("hello", connections)
hello to each identity and backend associated with the
connections object. You can find more examples of
send in the official
Outbound message that can easily be sent to the router.
Specific metadata to be included when passed to backends.
Send the message. Equivalent to
Both incoming and outgoing message classes inherit from a common class, MessageBase.
MessageBase(connections=None, text=None, id_=None, in_response_to=None, fields=None, connection=None)¶
Basic message representation with text and connection(s).
fields can be used to pass along arbitrary metadata
Create a random unique ID for this message object.
a message can be marked “handled” by any app, which will short-circuit the default phase in the router.
a unique ID for this message
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
a message is considered “unprocessed” until rapidsms has dispatched it to all apps.
save original text for future reference
There’s also an ErrorMessage class that can be used when sending error messages.
RapidSMS represents entities that it can communicate with
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.
This model represents a person with a name
Most of a Contact is represented in the ContactBase class:
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: http://www.w3.org/International/articles/language-tags/Overview reference: http://www.iana.org/assignments/language-subtag-registry
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
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
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.
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.
Most of a Connection is represented in the ConnectionBase class:
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
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
- identities – list of identities to find associated with the backend
- backend – backend name (as a string) or
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
from rapidsms.router import send, lookup_connections connections = lookup_connections(backend="example-backend", identities=['1112223333']) send("hello", connections=connections)