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.
Parameters: - text – text message
- connection – RapidSMS
Connection
object - kwargs – Extra kwargs to pass to
IncomingMessage
constructor
Returns: 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 inRAPIDSMS_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.Parameters: - text (string) – 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.
Returns: 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()
.Parameters: - text – text message
- connections – list or QuerySet of RapidSMS
Connection
objects - kwargs – Extra kwargs to pass to
OutgoingMessage
constructor
Returns: 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.
-
extra_backend_context
()¶ Specific metadata to be included when passed to backends.
-
send
()¶ Send the message. Equivalent to
rapidsms.router.send(text, connections)
.
-
MessageBase¶
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).
-
connection
¶ The first
Connection
- deprecated.
-
connections
= None¶ The connections this message was received from or sent to. A list of
Connection
-
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
-
peer
¶ 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
-
ErrorMessage¶
There’s also an ErrorMessage class that can be used when sending error messages.
-
class
rapidsms.messages.error.
ErrorMessage
(*args, **kwargs)¶
Contacts¶
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)¶ -
created_on
¶ when the contact was created
-
default_connection
¶ Return the default connection for this person. Currently this arbitrarily returns the first connection.
-
is_anonymous
¶ Return True if the individual has no name
-
language
¶ 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
-
modified_on
¶ when the contact was last modified
-
name
¶ The individual’s name (optional)
-
Connections¶
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
¶
-
exception
MultipleObjectsReturned
¶
-
exception
Most of a Connection is represented in the ConnectionBase class:
-
class
rapidsms.models.
ConnectionBase
(*args, **kwargs)¶ -
backend
¶ foreign key to this connection’s
BackendBase
-
created_on
¶ when this connection was created
-
identity
¶ unique identifier for this connection on this backend (e.g. phone number, email address, IRC nick, etc.)
-
modified_on
¶ 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.
Parameters: - backend – backend name (as a string) or
BackendBase
object - identities – list of identities to find associated with the backend
Returns: List of
Connection
objects- 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
lookup_connections
:
from rapidsms.router import send, lookup_connections
connections = lookup_connections(backend="example-backend",
identities=['1112223333'])
send("hello", connections=connections)