Clone wiki

samosa / Home


Samosa is an SMS application framework inspired by web frameworks like Django or Rails. Unlike Rapid SMS, Samosa is a stand-alone framework with no web administration component. This greatly simplifies development of SMS apps, allowing someone with only basic Python knowledge to spin up complex apps without needing to learn the intricacies of developing for the web.

Here is a presentation about Samosa.


We will now attempt to explain the structure of Samosa through the literary art of bullet-point narrative:

  • Agnes picks up her phone and texts "#joke" to a certain phone number.
  • The provider of this phone number takes Anges' message and waits for a client to check for new messages.
  • A little time goes by and a Samosa connection module decides it's time to check that number.
  • The provider passes the message to the connection module, which in turn passes it to its router.
  • The connection's router knows that only the joke app should be notified of new messages from that particular connection, and sends the message along to that app's controller (and not to any other apps).
  • The joke app's controller looks at some attributes of the message, as well as some other information recorded in the app's models, such as:
    • Have I not seen this exact message before?
    • Was this message sent from an approved number?
    • Does the message have the exact phrase "#joke" in its text body?
  • If all these tests pass, the controller passes the message to the right responder.
  • That responder pulls a joke from the Joke model, makes a new message with the text of that joke in its body, and addresses that message to Agnes.
  • The responder sends the new message to the connection.
  • The connection sends the new message to the provider.
  • The provider sends the new message to Agnes.
  • Agnes LOLs.


The Connections modules provide methods to interface with specific SMS service providers, such as GoogleVoice, Twilio, andTropo.


Models define the environment and data that an App uses.


Controllers define what kind of response(s) are to be performed after recieving messages.


Responders define the actual content of an app's response to a message input.

Example Apps

The following example apps download with Samosa:

  • basic_game
  • beowulf
  • group_demo
  • joke
  • weekender

Getting Started

  • Install dependencies
  • Clone the repository
    • hg clone
  • Check out the tutorial