Keywords is where you create create Autoreplies, subscriber lists, manage SMS-to-email settings and configure FrontlineSMS advanced features

What can I do in Keywords?

Keywords is an extremely powerful module which allows you to automatically trigger actions within FrontlineSMS. This section of FrontlineSMS Help will guide you through the features in the Keywords module. Please take your time - there's a lot here

Keyword Actions

Keywords are simply predefined words which, when users or members of the public text them in, cause FrontlineSMS to carry out a specific action. This action can be one of several things:

Auto Reply
FrontlineSMS will automatically send a pre-determined SMS back to the sender of the keyword/message (maybe a "Thank you for your message", for example)

Auto Forward
FrontlineSMS will automatically forward the incoming message to all members of a pre-determined Group. This can be useful when you want Group members to be able to contact each other via SMS with latest news, or urgent announcements. (Auto Forward does a similar thing to Twitter, which you may have heard of)

Join Group
FrontlineSMS will automatically add the person sending in the SMS to a pre-determined Group. Again, this is useful if you are running a series of user Groups or clubs, and want people to be able to join automatically by publicising the keyword without them having to contact you directly. A campaign, for example, could say "To join our Control Arms Campaign, text in the word JOIN to 650123456". Here, JOIN is the keyword

Leave Group
Members of Groups can leave any time they like by sending an SMS with a pre-determined keyword or phrase (for example, LEAVE GROUP)

Email
Keywords can be used to instruct FrontlineSMS to automatically forward an incoming text message to a pre-determined recipient, by email. This might be useful if you want a Project Manager, or someone in a different country or office, to receive (free) email notifications of incoming Survey or campaign text messages, or if you'd like some of your text messages to be backed up in an email system such as Outlook or Google Mail

External Command
Although a particularly advanced feature, and one most likely to be used by more technical users, keywords can be set up to trigger the running of external commands or programs (for example, a batch file or a script). For example, a batch file could be written which finds out how much free disk space is left on the computer. An incoming SMS with, say, the keywords FREE SPACE could then be set to trigger the running of this batch file, with FrontlineSMS texting the result (i.e. the amount of free disk space) back to the message sender. The External Command function can also be used to instruct FrontlineSMS to send incoming messages to remote servers over the internet (using HTTP POST), which may be useful as a method of backing up data, or for a website with a news ticker which needs to display all incoming messages for a campaign or event

Keywords can also be set to have multiple actions. So, for example, the Keyword JOIN could be set to allow people to remotely Join Groups, and to also do an Auto Reply to the message sender with a "Thank you for joining our Group. We will be in touch" message. If you really wanted to, you could also set the JOIN Keyword to Auto Forward the joining message to all other members of the Group, in case you wanted them all to know that there was a new member. There is no limit to the number of actions that can be set for a Keyword

Adding a new Keyword

All current FrontlineSMS keywords appear in the main Keyword window [1]. To add a new Keyword, click on New [5] and enter a name (and a description, if you need one - this is not essential). Your keyword will then appear in the main window [1]. After highlighting the new keyword you can edit any of the fields to the right [2]. See below for the various options

Adding an "Auto Reply" action

If you want an automatic message to be sent back to the message sender (perhaps a "Thank you for contacting us" message, or similar), tick the check box and type this message in the "Send this message as an auto reply" field [2]

Adding a "Join Group" action

If you want this keyword to automatically instruct FrontlineSMS to add the sender of the message to a specific Group, select the Group name from the list under "Add message sender to group" [2]

Adding a "Leave Group" action

If you want this keyword to automatically instruct FrontlineSMS to remove the sender of the message from a specific Group, select the Group name from the list under "Remove message sender from group" [2]

When you are finished adding these initial actions, click the Save button [3]

NOTE: When testing your keywords for the first time, bear in mind that it can take a couple of minutes for FrontlineSMS to pick up the incoming text message, and a minute or two for the event to be triggered

NOTE: There are other Advanced keyword actions that can be set. See the section below for further details

Using the <None> keyword

When you start FrontlineSMS for the first time, you will notice a single entry - <None> - in the main Keyword window [1]. If you want every incoming SMS to trigger an action - perhaps a thank you message - regardless of message content, then use the <None> keyword entry. You can use <None> to forward every incoming message to a website, or to services such as Twitter or Facebook, for example
 

Adding further actions in the Advanced View

If you'd like to add further actions to any of your Keywords, selecting the Keyword from the Keyword window [1] brings up an additional menu function [4]. Click on "Click here to go to advanced view" to open up a new screen (below)

This "advanced view" allows you to add additional actions to your Keyword. A list of available actions are listed in the pop-up menu [1]. Select the new action which you'd like to add, and then click on the settings button [2]. A different dialogue box will appear next, depending on which action you select

Auto Reply settings

The Auto Reply screen allows you to add or edit the automated message being sent back in return, to include the Senders Name in the message (if their number is recognised by Contacts), and to set Start and End Dates if you only want the Auto Reply to run for a set time

Auto Forward settings

The Auto Forward screen allows you to add or edit the automated message being forwarded to the specified Group, to include the Senders Name in the message (if their number is recognised by Contacts), and/or to include the body of the original message. This feature is useful if Group members are sending messages to other Group members. For example, here the Forwarded Message could read "From: ${sender_name}.  Message: ${message_content}". You can also set Start and End Dates if you only want the Auto Forward to run for a set time

Join/Leave Group settings

The Join Group and Leave Group screens allow you to instruct FrontlineSMS to add people sending in the chosen Keyword to a pre-determined Group, or to remove them from that Group. Start and End Dates can also be set if you only want the action to run for a set time

E-mail settings

NOTE: You need to set up an email account in FrontlineSMS if you want to use this function. Click on "E-mail Accounts Settings" and enter the name of your SMTP server, your full email address and your email password. You should have these settings - if not refer to your email provider. You may also want to create a unique email address for FrontlineSMS to use. Successfully added email accounts display in the 'From' window

The E-mail screen allows you to tell FrontlineSMS to automatically forward incoming text messages starting with your pre-determined keyword to an email recipient. On the E-mail screen, type in the Subject for the email, followed by an email Message (you can include fields such as Senders Name and the Message Content within the body of the email message - if you like - by clicking on the relevant Click to include button). Select the email account you want to send the messages through in the From window, and the email address of the person you want the emails to be sent to. Again, you can set Start and End Dates if you only want the emails to be sent during a set time period

External Command settings

The External Command screen is where you tell FrontlineSMS to run another program on your computer, execute a set of commands, or send incoming messages over the internet to a web server whenever a text message containing a pre-determined Keyword is received. Please note that this is advanced functionality and you will likely need technical skills to make any use of it

HTTP Request

If you have an internet connection, FrontlineSMS can automatically send incoming messages over the internet to a web server (this is the functionality used by many Ushahidi deployments). This can be useful in a number of ways. For example, it can be helpful if you want to back-up messages off-site in case of data loss. Or, if you're running a campaign and want to display SMS feedback from supporters on the homepage of your website, FrontlineSMS can 'pass' this information on (although your web developer will need to write a script to 'listen out' for incoming messages). The messages could then be displayed as a scrolling 'ticker'

To set up a HTTP Request, select the option at the top of the screen. Along the Command line, enter the URL (website address) for the server you want to pass incoming messages to. Depending on how you configure the 'listening' server, you can attach certain bits of information to the end of the Command by clicking on any of the Click to include buttons, which adds the relevant field names in for you. Once a message has been successfully received by the server, you will most likely get a response confirming its arrival. Again, depending on your remote server, the Response Type will most likely be Plain Text. You can decide whether or not you want to do anything further (if not, select Do Not Wait For Response) but you can, if you like, send a reply back to the original message sender (or an entire Group), notifying them that their message has been successfully posted to your website, or successfully received. To do this, type your auto-reply message in the Message window and then, if you also decide to send this message to an entire Group, select the Group name from the list in window under the Forward to Group tick box. Finally, you can set Start and End Dates if you only want the HTTP Request to be active during a set time period

TIP: You can also insert the response text that you get back from the remote server by clicking the Include Response button while compiling your message

Command Line Execution

Software developers and advanced users can write batch files or scripts, and then instruct FrontlineSMS to run them when the pre-determined keyword is detected. These scripts can be programmed to do pretty-much anything, depending on the programmer. To run an external command, follow the instructions above, selecting Command Line Execution from the top menu