PLUGIN README
Outgoing SMS - Sends text messages to cell phones, either immediately or via a
queue for bulk messaging. Uses an SMS gateway.
-------------------------------------------------------------------------------


OVERVIEW
-------------------------------------------------------------------------------
This plugin allows you to send SMS (text) messages from your website. While the
possibilities are limitless, some example uses include informing or reminding
users of time-sensitive promotions, their personal appointments, or important
news.

Messages can be sent either immediately, or queued to be sent at a later time
using a cronjob. This is useful for sending bulk messages without running into
timeout problems.

To send SMS messages, an SMS gateway service is required. These services
typically charge a few cents per message sent.

This plugin currently supports the txtlocal.com service, which is capable of
sending messages internationally. If you have another gateway service you'd like
to work with, we'll do our best to add support for it at no extra charge.


GETTING STARTED
-------------------------------------------------------------------------------
To get started, you'll need to add your SMS gateway information to the plugin
file. You'll find a place to add your username and password in the first few
lines of the plugin. Below are setup details for the three supported gateways:

txtlocal.com
------------
  1) Go to https://www.textlocal.com.
  2) Go to the Sign-up page and create an account.
  3) Confirm your account using the account confirmation email.
  4) Add your username (email address) to the global
     OUTGOING_SMS_GATEWAY_USERNAME_OR_API_KEY.
  5) Add your password to the global 
     OUTGOING_SMS_GATEWAY_PASSWORD_OR_API_KEY_SECRET.

twilio.com
----------
Twilio differs from other gateways as you have to purchase a phone number to send
SMS messages from. Prices start from $1.00 a month for a number, with text messages
costing $0.0075.

  1) Go to https://www.twilio.com/ and go through the account creation process.
  2) On login you'll be taken to the console, click the Account link in the left
     hand menu.
  3) This will take you to the Account Settings Page, which includes your live and
     Test API credentials. 
  4) If testing Twilio, copy the Test Account SID into the global 
     OUTGOING_SMS_GATEWAY_USERNAME_OR_API_KEY and the Test Authtoken into the
     global OUTGOING_SMS_GATEWAY_PASSWORD_OR_API_KEY_SECRET. Ensure that the
     Outgoing SMS plugin is in test mode to use Twilio's Test phone number. NOTE:
     No SMS messages are sent when Twilio is in test mode. But the functionality
     is the same. 
  5) Next you'll need to buy a phone number, go to: 
     https://www.twilio.com/console/phone-numbers/search and purchase a phone number
     that suites your requirements.
  6) GOING LIVE: Copy the Live Account SID into the global 
     OUTGOING_SMS_GATEWAY_USERNAME_OR_API_KEY and the Live Authtoken into the
     global OUTGOING_SMS_GATEWAY_PASSWORD_OR_API_KEY_SECRET.
  7) Add your phone number to the global OUTGOING_SMS_GATEWAY_PHONE_NUMBER and
     ensure that the global OUTGOING_SMS_GATEWAY_TESTMODE is set to false.
  8) You'll also need to upgrade your account to go live, this involves going 
     to https://www.twilio.com/console/billing/upgrade and entering your billing
     details.

amazon.com
----------
Note: SMS messages sent using amazon.com must start with a plus (+) and country code,
for example: +441234567890 or +11234567890. Amazon's API doesn't return errors
relating to number format issues. If a SMS is not received, ensure the phone number
is in the correct format.

  1) Go to https://aws.amazon.com/ and create an account. 
  2) After logging in, go to Amazon AWS console and find SES in the menu:
     All Services -> Messaging -> SES, doing this will enable the service on 
     your account.
  3) When doing the previous step, you might see an error message saying that
     your account needs to complete the setup process. Follow the link on this page
     to enter your billing details. 
  4) Select SNS from the menu: All Services -> Messaging -> SNS, this will take
     you SMS message interface. 
  5) Use the 'Public text message' link to ensure that you can send a test text
     message.
  5) Next you'll need to get your API keys. From the AWS Console, go the User menu
     and select the My Security Credentials option.
  6) Select Access Keys from the menu on the right hand side. Click the 'Create New
     Access Key' link. 
  7) A dialog box will appear, click the 'Show Access Key' link in it to find your
     access keys. 
  8) Copy the Access Key ID into the global OUTGOING_SMS_GATEWAY_USERNAME_OR_API_KEY.
  9) Copy the Secret Access Key into the global 
     OUTGOING_SMS_GATEWAY_PASSWORD_OR_API_KEY_SECRET.

After activating the plugin, click the Send Test SMS link on the Admin > Plugins
page and send yourself a test message to make sure everything is working
correctly.


USAGE
-------------------------------------------------------------------------------
This plugin lets you send SMS messages from the plugin menu by clicking on the
"Send Test SMS" link.

You can allow either editors or admin users to send SMS messages to matching
records from a CMS section by enabling the 'OUTGOING_SMS_SEND_ACCESS_REQ'
setting at the top of the plugin and specifying the field used to store mobile
numbers as 'OUTGOING_SMS_PHONE_FIELD'.

This will add a new "Send SMS (Search Results)" option to the "Advanced Commands"
pulldown on the list page for any section with a "mobile" field (or the fieldname
you have entered in 'OUTGOING_SMS_PHONE_FIELD'). For example, you can use this
to send SMS messages to users in your User Accounts section.


ADVANCED USAGE
-------------------------------------------------------------------------------
You can also use the following functions in your viewer pages to send SMS
messages:

list($errors, $response) = outgoingSMS_sendMessage($from, $to, $text);
list($errors, $response) = outgoingSMS_queueMessage($from, $to, $text);

Please note that your SMS gateway may require phone numbers in the $to argument
to be numbers-only (i.e. no hyphens, spaces, or parenthesis.) You can remove all
non-numbers from a string with this code:

$to = preg_replace('/[^\d]/', '', $to);


SENDING QUEUED MESSAGES
-------------------------------------------------------------------------------
You can setup the CMS to send the messages automatically via the CMS Background
Tasks system. You can find instructions on setting the CMS Background Task 
System up by logging in to the CMS and go to Admin Menu -> Background Tasks.

You can change the number of messages the plugin sends each time it sends queued
messages at the top of the plugin file by changing the number on this line:

$GLOBALS['OUTGOING_SMS_MAX_MESSAGES'] = '2';

SETTING THE "FROM" NAME OR ADDRESS
-------------------------------------------------------------------------------
Note that this varies between SMS Gateway vendors.  Some let you specify an
outgoing number in their website control panels and use that.  However, if your
provider lets you send a number or name in the message it will be sent.  Test
to know for sure.


-------------------------------------------------------------------------------
end of file.