Developer

Short Codes, Long Codes, and Keywords

A short code or long code plus a keyword identifies an interactive application within a workspace.

Each workspace has a unique short or long code. For incoming messages, the processing engine compares the destination MSISDN with the short or long code list to find a matching workspace. Once a matching workspace is identified, the processing engine compares the message content with keywords assigned to applications in the workspace. A workspace can contain many applications, which should all have unique keywords. At runtime, the processing engine stops when it finds the first matching keyword, and calls the corresponding application.

A short code is a special telephone number, significantly shorter than a full telephone number that can be used to address SMS and MMS messages from some mobile phones or fixed phones, and is limited to national borders. A long code is a longer number and is available internationally.

SMS Builder uses short codes and long codes differently from how they are used in the mobile-operator world. Short codes are often associated with mobile services, such as interactive applications, and they are assigned by the mobile operator to the owner of the service.

For example, company XYZ wants to provide a mobile service for paying street-parking fines in the financial district of San Francisco. XYZ applies for an assigned short code from a mobile operator. Typically, the short code (9999)  is advertised on billboards in the financial district area: “To pay parking fines with your mobile phone, text “SFpay to 9999.” When a mobile subscriber texts SFpay to 9999, the message first reaches the mobile operator. The operator, in turn, routes it to SMS Builder. When SMS Builder receives the message, the processing engine maps the destination MSISDN (9999) to a workspace. Once the workspace is identified, the engine looks at the keyword SFpay and maps it to the corresponding interactive application in that workspace. The first matching application is chosen.

A keyword can be a simple string like “coupon,” or a regular expression. Optionally, you can associate a date range with a keyword, which controls the length of time a keyword remains active. A keyword's date range takes precedence over an application's date range: if an application's date range expires, but the keyword date range is still active, the application remains active until the keyword dates expire. When keyword dates are empty, the application defines the date range.

Best practices:
  • Verify that an interactive application acting as an entry point has at least one assigned keyword.
  • Use the keyword-search tool to verify that a keyword is assigned to only one application in the workspace.
  • If you define a regular expression as a keyword, verify that the regular expression does not overlap with keywords that are already in use by other applications. The keyword-search tool does not work for regular expressions.