Abstract
This document describes ARTIO VM SMS component for Joomla! CMS, its functionality, requirements, installation procedure and usage.
You can also 
download VM SMS documentation as PDF.
Table of Contents
List of Figures
List of Tables
Table of Contents
ARTIO VM SMS is a Joomla! CMS component which can automatically send notification SMS messages to you or your customers when their VirtueMart orders status changes. You can select whether an SMS message should be sent to you and/or your customer for each order status and define your own SMS messages texts, which can contain some dynamic data like customer name, order number or total order amount. You can even filter allowed and restricted customers phone numbers, so SMS messages can be sent only to specific countries or network operators.
ARTIO VM SMS is a component for Joomla! CMS so it requires Joomla! to run. Joomla! CMS can be obtained at http://www.joomla.org/.
ARTIO VM SMS is available in two editions:
-
VM SMS 1.x is compatible with Joomla! 1.5 and VirtueMart 1.1.x and 2.x
-
VM SMS 2.x is compatible with Joomla! 2.5 and VirtueMart 2.x only
Other Requirements:
-
PHP 5.2.x or newer - at least PHP 5.2.9 is required
-
PHP JSON extension - since PHP 5.2.0 it is enabled by default
ARTIO VM SMS is released under the GNU/GPL v3 license, see: http://www.artio.net/license/gnu-general-public-license
Table of Contents
Before you can use ARTIO VM SMS component to send SMS messages to your customers, you first need to have a valid user account registered on ARTIO website. Then you need to log in to our website and activate ARTIO SMS Services. After the activation you will be assigned a unique API key which you can use along with your ARTIO username to access SMS Services from VM SMS component.
For a simple guide for ARTIO SMS Services activation please visit the First Steps with ARTIO SMS Gateway page on our website.
You can also visit the SMS Gateway Overview page for more information about ARTIO SMS Services.
ARTIO VM SMS can be downloaded free of charge from the Downloads section of ARTIO website. Please make sure that you download correct version for your Joomla! CMS - version 1.x works only with Joomla! 1.5 and version 2.x works only with Joomla! 2.5.
When you have the installation ZIP package ready its installation is completely straightforward. You can install it just like any other Joomla! CMS component using the Extensions Manager from main menu of your Joomla!. All the required plugins are installed and enabled automatically during the component installation.
If you don't want to use our component for any reason anymore, just open the Extensions Manager in your Joomla! CMS, select either the VM SMS component in Joomla 1.5 or the ARTIO VM SMS Package in Joomla 2.5 and click the Uninstall button in the toolbar. This will uninstall all the data and configuration and also all the related plugins, so there's no need to uninstall them manually.
Table of Contents
Dashboard is the main page of ARTIO VM SMS. It provides you with basic information about your ARTIO SMS Services account and currently installed VM SMS component version and it allows you to manually send custom SMS messages.
Provides basic information about your ARTIO SMS Services account.
- ARTIO Username
-
Your ARTIO Username currently set up in Configuration. This is the username you used to register to ARTIO website.
- ARTIO SMS API Key
-
Your API key for ARTIO SMS Services currently set up in Configuration. You can find your API key in your ARTIO SMS Services Dashboard when you log in to ARTIO website.
- Available credit
-
The credit currently available on your ARTIO SMS Services account.
- Estimated exhaustion
-
Estimated time remaining until your available credit is exhausted. Currently the data about your ARTIO SMS Services usage for the last 14 days are used to estimate it.
- Charge credit
-
Use this field to directly purchase more credits for your account. Just select the desired amount of credits and click the submit button - a pre-filled checkout page on ARTIO website will be opened for you in a new web browser tab.
Allows you to send a custom SMS message to any international phone number.
- Phone number
-
Recipient phone number. It must be a valid phone number in international format with country dialling code but without the leading plus symbol or zeroes. It can also contain only numeric characters - no spaces or dashes are allowed. For example:
Correct phone number format: 420123456789
Incorrect phone number formats: 555-555-555 or +44 11 12 13 14
- SMS text
-
SMS message text. The current number of characters and number of SMS messages the text will be split to is displayed under the field. There are some rules for SMS message text that you should get familiar with - please see Appendix A.
When you fill the Phone number and SMS text fields, use the send button to send your SMS message.
Allows you to set up access credentials to your ARTIO SMS Services account and some basic options for SMS sending.
- ARTIO Username
-
Set your ARTIO website account username.
- ARTIO SMS API Key
-
Set your ARTIO SMS Services account API key. You can find it in your ARTIO SMS Services Dashboard when you log in to ARTIO website.
- Phone field (primary)
-
Which VirtueMart user field should be primarily used as a recipient phone number for SMS messages to your customers.
- Phone field (secondary)
-
Which VirtueMart user field should be used as a recipient phone number for SMS messages to your customers if the primary phone field is not set.
- Allow Unicode SMS
-
Whether Unicode SMS messages can be sent if the SMS message contain some non-standard characters. Unicode SMS messages can contain any characters, but must be shorter. Non-Unicode SMS messages can contain only some predefined characters, but can be longer. If Unicode SMS are disabled, all non-standard characters will be either converted to standard ones if possible or removed.
If Unicode SMS messages are allowed, messages that don't contain any Unicode characters are sent as standard SMS.
For the list of characters allowed for standard SMS messages and the messages length limits see Appendix A.
Provides options to correctly handle local phone numbers (without country dialling code) and easy-to-use interface to set up phone numbers filters to allow or disallow specific phone numbers.
- Local Country
-
Choose a country you want to use for your local phone numbers. This country's dialling code will be added to phone numbers which don't contain any country dialling code.
- Add local country code to numbers with digits less than or equal to
-
Select how many digits can a phone number contain for the local country dialling code to be prepended to it. If a phone number contains more digits than the selected value, it will be assumed that it already starts with a country dialling code.
This option is useful if you have many local customers who enter their phone number without your country dialling code, so it can be added automatically.
- Allow Phone Numbers
-
You can set up rules for specific countries to allow sending of SMS messages to some phone numbers only. If you leave the rules for some country empty, all the phone numbers for that country will be allowed.
- Disallow Phone Numbers
-
Here you can specify rules for specific countries to disallow sending of SMS messages to specific phone numbers. These rules are stronger than the Allow Phone Numbers rules, meaning that an SMS is never sent to a phone number which matches some Disallow Phone Numbers rule, even if it would be otherwise allowed by specified Allow Phone Numbers rules.
Both the Allow Phone Numbers and Disallow Phone Numbers filters use the same logic:
You can add a new rule to currently selected country by clicking the plus icon. There are two types of rules - pattern and range. Both types match phone numbers from the left, so you can specify a rule for "number starting with ..." but not a rule for "number ending with ...". You build the rules from left to right by individual phone number digits. For each position, you can match a specific digit or use a ? character to match any digit. Use * character to indicate end of the rule (matches any rest of the phone number).
Use a pattern rule to specify simpler condition like "number that starts with 6, then contains any digit, and then contains 7". This rule can be represented by 6?7*.
Use a range rule to specify sophisticated condition like "all phone numbers starting from 602 to 608". This rule can be represented by 602* - 608*.
To simplify usage of this feature, only the rules for selected country are displayed at one time and countries with some rules already defined are listed first with the green background. This helps you to see which countries already have some rules assigned, and which don't, very quickly.
In our image above, there will be only phone numbers starting from 602 to 608 and from 771 to 779 allowed for the Czech Republic, but except the phone numbers starting with 774.
In this section, you can select when SMS notifications should be sent to you or your customers. For each of your VirtueMart order statuses you can set whether and what SMS to send when an order is switched to that status.
- Send SMS to you
-
Whether an SMS should be sent for this status to your own phone number defined in your ARTIO SMS Servies account.
- Send SMS to customer
-
Whether an SMS should be sent for this status to your customer.
- Your SMS text
-
Text of the SMS message that will be sent to you. See Appendix A for more details on the allowed characters and length limits.
- Customer SMS text
-
Text of the SMS message that will be sent to your customer. You can define different texts for different customers languages to achieve even better user experience. See Appendix A for more details on the allowed characters and length limits.
You can also use special placeholders in both Your SMS text and Customer SMS text fields for improved personalization of your SMS messages:
- %customer%
-
Will be replaced with a name of the customer who placed the order.
- %order_nr%
-
Will be replaced with the order number.
- %order_total%
-
Will be replaced with the order total amount.
Provides you with some options you can use should you need any help with our component. Use this page to access this documentation online, see the list of changes in the ARTIO VM SMS component, read the Frequently Asked Questions, visit our Support forums or ask for our professional paid support services.
Due to inner implementation of SMS messaging protocol, there are some limitations on the characters you can use and the length of the messages.
Each SMS message can be transferred either as standard SMS or Unicode SMS. Standard SMS can contain following standard characters (SP stands for space) and extended characters:
Table A.1. Standard SMS characters
| SP | ! | " | # | % | & | ' | ( | ) | * | + | , | - | . | / | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | : | ; | < | = | > |
| ? | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | a | b | c |
| d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | t | u | v | w | x | y | z | @ | $ | è | é | ù | ì | ò |
| £ | ¥ | ¤ | Ø | ø | Ç | Å | å | | ¦ | | | © | ¨ | £ | | | Æ | æ | ß | É | ¡ | ¿ | Ä | Ö | Ñ | Ü | ä | ö | |
| ñ | ü | à | § | _ |
One standard SMS message can contain up to 160 characters, but extended characters are counted as two characters each.
If you need to use other characters in your SMS messages, the only other option is to send them as Unicode. Such SMS can contain any unicode characters (which is pretty much any character), but their length is limited to 70 characters only.
Furthermore, you can also send longer messages split to multiple SMS. However, you are still limited to 3 messages length only and this feature decreases one message length by 7 characters. So split standard SMS can contain 153 characters each and split Unicode SMS only 63 characters each. This gives you a maximum length limit of 459 characters for standard SMS and 189 characters for Unicode SMS. Please note that each SMS will be charged separately, so a message split to 3 SMS will cost three times the price of a single SMS.
If you are further interested in SMS protocol's inner workings, you can check this article on Wikipedia: http://en.wikipedia.org/wiki/GSM_03.38.
If you plan to use ARTIO VM SMS version 1.x on Joomla! 1.5 with VirtueMart 1.1.x, there are certain limitations due to lack of required functionality in VirtueMart 1.1.x.
Because this older version of VirtueMart doesn't support any system of notification when an order is placed or its status is changed, our component installs a system plugin by default, which tries to check for order status changes every 10 minutes. However, this check can't occur fully automatically - it is only initiated when your website is accessed.
To overcome this limitation, our component also provides an interface for Unix cron system, which allows you to run the check independently in specified time intervals. The check can be initiated from cron by accessing the following URL: http://www.yoursite.com/index.php?option=com_vmsms&task=cron. You can use for example wget command to access the URL from cron.
For more information about cron please see it's manual pages in Unix or this article on Wikipedia: http://en.wikipedia.org/wiki/Cron.
