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.
Creates an incoming message and passes it to the router for processing.
Parameters: |
|
---|---|
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 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.
Bases: rapidsms.messages.base.MessageBase
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 send() method.
Parameters: |
|
---|---|
Returns: | dictionary with the arguments that will be passed to rapidsms.router.send() to send this response. |
list of messages created by IncomingMessage.respond()
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: |
|
---|---|
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.
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.
Basic message representation with text and connection(s).
The first Connection - deprecated.
The connections this message was received from or sent to. A list of Connection
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
the message
There’s also an ErrorMessage class that can be used when sending error messages.
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.
Bases: rapidsms.models.ContactBase
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 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.
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.
Most of a Connection is represented in the ConnectionBase class:
foreign key to this connection’s BackendBase
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.
Parameters: |
|
---|---|
Returns: | 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",
identities=['1112223333'])
send("hello", connections=connections)