This wrapper lets you interact with Clockwork without the hassle of having to create any XML or make HTTP calls.
Clockwork is Mediaburst's SMS API.
- A Clockwork account
Require the Clockwork library:
require 'class-Clockwork.php';
$clockwork = new Clockwork( $API_KEY );
$message = array( 'to' => '441234567891', 'message' => 'This is a test!' );
$result = $clockwork->send( $message );
We recommend you use batch sizes of 500 messages or fewer. By limiting the batch size it prevents any timeouts when sending.
$clockwork = new Clockwork( $API_KEY );
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );
The responses come back as arrays, these contain the unique Clockwork message ID, whether the message worked (success), and the original SMS so you can update your database.
Array
(
[id] => VE_164732148
[success] => 1
[sms] => Array
(
[to] => 441234567891
[message] => This is a test!
)
)
If you send multiple SMS messages in a single send, you'll get back an array of results, one per SMS.
The result will look something like this:
Array
(
[0] => Array
(
[id] => VI_143228951
[success] => 1
[sms] => Array
(
[to] => 441234567891
[message] => This is a test!
)
)
[1] => Array
(
[id] => VI_143228952
[success] => 1
[sms] => Array
(
[to] => 441234567892
[message] => This is a test 2!
)
)
)
If a message fails, the reason for failure will be set in error_code and error_message.
For example, if you send to invalid phone number "abc":
Array
(
[error_code] => 10
[error_message] => Invalid 'To' Parameter
[success] => 0
[sms] => Array
(
[to] => abc
[message] => This is a test!
)
)
Check your available SMS balance:
$clockwork = new Clockwork( $API_KEY );
$clockwork->checkBalance();
This will return:
Array
(
[symbol] => £
[balance] => 351.91
[code] => GBP
)
The Clockwork wrapper will throw a ClockworkException if the entire call failed.
try
{
$clockwork = new Clockwork( 'invalid_key' );
$message = array( 'to' => 'abc', 'message' => 'This is a test!' );
$result = $clockwork->send( $message );
}
catch( ClockworkException $e )
{
print $e->getMessage();
// Invalid API Key
}
This class has a few additional features that some users may find useful, if these are not set your account defaults will be used.
-
$from [string]
The from address displayed on a phone when they receive a message
-
$long [boolean]
Enable long SMS. A standard text can contain 160 characters, a long SMS supports up to 459.
-
$truncate [nullable boolean]
Truncate the message payload if it is too long, if this is set to false, the message will fail if it is too long.
-
$invalid_char_action [string]
What to do if the message contains an invalid character. Possible values are
- error - Fail the message
- remove - Remove the invalid characters then send
- replace - Replace some common invalid characters such as replacing curved quotes with straight quotes
Options set on the API object will apply to all SMS messages unless specifically overridden.
In this example both messages will be sent from Clockwork:
$options = array( 'from' => 'Clockwork' );
$clockwork = new Clockwork( $API_KEY, $options );
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!' )
);
$results = $clockwork->send( $messages );
Set option values individually on each message.
In this example, one message will be from Clockwork and the other from 84433:
$clockwork = new Clockwork( $API_KEY, $options );
$messages = array(
array( 'to' => '441234567891', 'message' => 'This is a test!', 'from' => 'Clockwork' ),
array( 'to' => '441234567892', 'message' => 'This is a test 2!', 'from' => '84433' )
);
$results = $clockwork->send( $messages );
This project is licensed under the ISC open-source license.
A copy of this license can be found in license.txt.
If you have any feedback on this wrapper drop us an email to [email protected].
The project is hosted on GitHub at https://github.com/mediaburst/clockwork-php. If you would like to contribute a bug fix or improvement please fork the project and submit a pull request.