Routes

The SMS functionality is controlled with a routes dict, with string keys (commands) and function values (routes). Each command is a single word that is texted to your safehouse number. Words following the command are passed through a lexer to determine function params for the routes. For example, texting 'echo this sentence' would call route echo('this', 'sentence'). Routes may have different names from their commands.

• Anything in curly braces is a required 'token'. A token is a single word, a single number, or a string in quotes. For example, for a command listed as foo {bar}, you could text foo hello, foo 13, or foo "this is multiple words".

• Anything in brackets is an optional token. If the token is not provided, a default will be used instead. For example, for a command listed as foo [bar], if bar is listed has having a default of "15", You could text foo to use foo with a bar of 15, or foo 11 to use foo with a bar of 11.

• Anything with an asterisk is multiple tokens. For example, foo {*bar} can be called with foo bar, foo bar baz, foo bar baz YESOCH, etc. Tokens may not have apostrophes in them unless they are surrounded by quotes. Otherwise the command will throw an error.

A note on modes: Safehouse SMS runs in two modes: forwarding mode, where all outsider messages are forwarded to you, and save mode, where all outsider messages are saved with a given tag. The mode is determined by the presence of a "tag" value in the config model, which resides in the database. This means that the mode will persist across server instances and can only be changed with the "set" and "unset" commands (or 'panic', see below.)

SMS Routes

"Echo {*args}"

Sends your message back to you. If the first word of your sms is not a recognized command, Safehouse will default to this.

"Set tag {tag} / Unset tag"

Converts the server to save mode with tag {tag} / convert the server to forwarding mode. If the server is already in save mode when you call "set tag", it changes the tag it saves to instead.

Note this is the same format as the next route, but is listed independently due to the significant effect it has on how Safehouse works.

Side effect: Changes server mode.

"Set {name} {value} / Unset {name}"

Adds the configuration option {name} with {value} / removes the configuration option {name}. See Config for more information.

Side effect: Changes server mode.

"Save-sms-template {template}"

Creates an sms template {template} for later use. {template} should be in quotes for proper parsing. You can use django template markup, although the only contexts supported are {{name}}, {{my_number}}, and {{my_name}}.

Side effect: Creates an SMS template.

"Info [command]"

If [command] is not provided, will list all available commands. If [command] is provided, will return the internal documentation for that command.

Contact Routes

"Inform"

Sets every uninformed contact in the database to 'informed', and texts them the 'inform' template.

Side effect: Sets everyone to inform.

"Say [template] [number]"

Finds template [template] and sends [number] random informed people the template. First looks for the templates in the "templates" directly (consisting of inform, panic, and talk), then in the templates model in the database. This is for legacy reasons- once we have a seed file, we'll migrate the three base templates into the database.

Templates are rendered as django templates and automatically fill in {{name}} (with the contact's first name), {{my_name}}, and {{my_number}}. [template] defaults to 'talk'. [number] defaults to 3.

"Panic [number]"

Sends [number] random people the panic template. [number] defaults to three.

Side effect: "Panic" differs from "Say panic" in that it will automatically convert the server to forwarding mode. We don't want to be saving messages when you need to read them the most, do we.

"Listen {tag}"

Pops the oldest messaged saved with tag "tag" and forwards it to you.

Side effect: Deletes the message from the saved_messages model. A copy of the message (sans tag) will have already been logged by log_message in the index view, so the only lost information is the message's tag.

"Outside {number} {message}"

Note: You really shouldn't need to call this unless you're trying to debug something. It's used internally to handle messages people send you. Functionality is provided below for debugging purposes.

If in save mode, saves the message with the appropriate tag. If in forwarding mode, tries to see if the number matches a Contact. If so, forwards the message to you with the name prepended. Otherwise, forwards the message to you with the number prepended.

Side effect: In save mode, adds a message to the saved_messages model.

Journal Routes

"Write {name} [rating] [*comment]"

Creates a journal entry with {name}, rating of [rating], comment of [*comment]. [rating] defaults to null. [*comment] defaults to null.

Will try to be smart about the rating and comment, so if the token immediately following {name} is not a number, it will be added to the comment and [rating] will be considered null.

Side effect: Adds an entry to the entry model.

"Read {name} [offset]"

Reads the [offset] most recent journal entry with name {name}. {offset} defaults to 1 (most recent). {offset} is in human format, so given two entries with the name "foo", "read foo 1" will retrieve the most recent entry, and "read foo 2" will retrieve the second most recent one.