|
|
|
|
|
|
This API will allow the sending and receiving of messages, as well as basic account
inquiries. The API is provided in the form of a PHP library to be included with the
rest of your application's PHP source.
Table of Contents
|
|
|
|
|
|
|
|
The API was developed and tested on PHP 4.3.3, with OpenSSL support compiled and configured in order to communicate with the directSMS’ gateway over SSL for greater security. Without SSL support configured, you will not be able to use the more secure form of connection.
Note, however, that releases of PHP prior to 4.3 will not support encrypted communications with the directSMS gateway via SSL. It is recommended that you upgrade to the 4.3 release of PHP to take full advantage of this API.
The main class to be used in application development is sms_connection, which is used to connect to the gateway, query the customer’s balance, send branded and 2-way messages as well as retrieving any replies received for 2-way messages.
In the event of any errors encountered while interacting with the SMS gateway, the error message describing the error condition can be retrieved by calling the get_error() method.
Table of Contents
|
|
|
|
|
|
|
|
The API is distributed as PHP source code (sms_connection.php), it can be installed anywhere that your PHP interpreter has read access. For convenience, we suggest that you install it in the same directory as the PHP application that will be using it.
Table of Contents
|
|
|
|
|
|
|
|
The following section will explain how to best use the API in building SMS enabled applications through the use of examples. The sample script (included as Appendix A) details the various operations available through the API.
Table of Contents
|
|
|
|
|
|
|
|
In order to connect and authenticate to the server, call the connect() method passing a directSMS username and password. If the credentials passed are genuine, the method will return true. If the gateway is down, the username and password are invalid in any way, or any one of a number of errors, the method will return false.
If the user account used is not set up for API access, an error will be returned.
In order to use the API, you can either contact the directSMS Support team to enable this feature on your account. This will activate your 60 day API trial. Please note; this is a single seat licence, for use on one customer account only.
The second option is to purchase an enterprise licence which will require you to pass the licence key along with the login credentials for authentication when opening a new connection. This is the approach to take if you are developing an application that will be distributed to multiple customers.
<html>
<title>directSMS PHP Code Sample</title>
<body>
<h2>directSMS PHP Code Sample</h2>
<pre>
<?php
// load the directsms sms_connection library
require_once("sms_connection.php");
// create a new connection, using the
// secure connection
$conn = new sms_connection(true);
// check if there are any problems. at this stage
// the only problem at this stage might be that
// the sms gateway is unreachable
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
// login and start a session using a licence key
if($conn->connect("s3UsEr",
"pAs5wOrD",
"71904d3a-d4c5ab00-46dbf93a-1f36312e"))
{
// go about your business
}
Table of Contents
|
|
|
|
|
|
|
|
Once authenticated and connected, the client can send a branded message or a
2-way message using the send_branded_sms and send_two_way_sms
methods.
// create a new sms message
$message = "this is a test message from the directsms sms gateway";
// create an array of the mobile numbers to send this message to
$mobiles = array("0401001001", "0402002002");
// send a branded sms message with the sender id "directSMS",
// remember the sender id can not exceed 11 characters in length
// and it must not contain any characters outside of:
// a-z, A-Z, . or 0-9
// the sender id can be set to a valid mobile number which means
// recipients can reply back to the number set, the replies
// however can not be tracked by directSMS' gateway
$id = $conn->send_branded_sms($message, $mobiles, "directSMS");
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("branded message id = " . $id . "\n");
}
// send a 2-way sms message with the message id "my-id". we can
// use that to search for replies to this message later, or at
// least to correlate reply messages to this 2-way message later
// on
$id = $conn->send_two_way_sms($message, $mobiles, "my-id");
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("2-way message id = " . $id . "\n");
}
The send_branded_sms and send_two_way_sms methods return the unique directSMS
message identifiers, which uniquely identify the submitted SMS messages. Should any error
conditions arise while communicating with the gateway, null will be returned instead, and the
methods is_error() and get_error() on the sms_connection used can be used
to check the error.
Table of Contents
|
|
|
|
|
|
|
|
The get_balance() method can be used to retrieve the number of SMS credits left on the your directSMS account.
// get the current balance
$credits = $conn->get_balance();
// use the is_error() method to check for
// any problems
if($conn->is_error())
{
// show the error encountered
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
// show the balance
print("current credit balance = " . $credits . " credit(s)\n");
}
Table of Contents
|
|
|
|
|
|
|
|
Once authenticated and connected, the client can schduled the sending of branded or
2-way messages at a later date/time using the schedule_branded_sms and schedule_two_way_sms
methods.
// create a new sms message
$message = "This is a test message going out at 11AM, January 1, 2006 (EST)";
// get the number of seconds after the unix epoch for 1/1/2006 11:00:00
$timestamp = mktime(11, 0, 0, 1, 1, 2006);
// create an array of the mobile numbers to send this message to
$mobiles = array("0401001001", "0402002002");
// schedule the branded sms message with the sender id "directSMS",
// remember the sender id can not exceed 11 characters in length
// and it must not contain any characters outside of:
// a-z, A-Z, . or 0-9
// the sender id can be set to a valid mobile number which means
// recipients can reply back to the number set, the replies
// however can not be tracked by directSMS' gateway
$id = $conn->schedule_branded_sms($message,
$mobiles,
"directSMS",
$timestamp);
// check if there were any problems
// encoutered while scheduling the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("scheduled message id = " . $id . "\n");
}
// schedule a 2-way sms message with the message id "my-id". we can
// use that to search for replies to this message later, or at
// least to correlate reply messages to this 2-way message later
// on. send the message on 1/1/2006 11:00:00
$id = $conn->schedule_two_way_sms($message, $mobiles, "my-id", $timestamp);
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("scheduled message id = " . $id . "\n");
}
The scheduled_branded_sms and scheduled_two_way_sms methods return the unique directSMS
message identifiers, which uniquely identify the submitted SMS messages. Should any error
conditions arise while communicating with the gateway, null will be returned instead, and the
methods is_error() and get_error() on the sms_connection used can be used
to check the error.
Table of Contents
|
|
|
|
|
|
|
|
The get_balance() method can be used to retrieve the number of SMS credits left on the your directSMS account.
// get the current balance
$credits = $conn->get_balance();
// use the is_error() method to check for
// any problems
if($conn->is_error())
{
// show the error encountered
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
// show the balance
print("current credit balance = " . $credits . " credit(s)\n");
}
Table of Contents
|
|
|
|
|
|
|
|
The get_sms_replies() method allows client applications to retrieve "unread" replies to ALL 2-way SMS messages or to a single 2-way message. The get_sms_replies() method takes an optional messageid parameter. If a message id is specified, only "unread" replies to the referenced 2-way message will be retrieved.
// lets retrieve any replies to the 2-way sms
// submitted a little earlier
$replies = $conn->get_sms_replies(null, "my-id");
print(count($replies) . " replies retrieved\n");
// display the replies
for($i = 0; $i < count($replies); $i++)
{
// print each reply on a separate line.
print($replies[$i]->to_string() . "\n");
}
The above code sample will result in the retrieval of all "unread" replies to the 2-way SMS message with the id "my-id" submitted earlier.
The get_sms_replies() method also takes a boolean parameter to mark any retrieved replies as "read". In essence this stops the server from retrieving these messages again in future calls to the get_sms_replies() function.
Table of Contents
|
|
|
|
|
|
|
|
The get_inbound_sms() method allows client applications to retrieve "unread" inbound SMS messages. The get_inbound_sms() method takes an optional inbound_number parameter. If an inbound number is specified, only "unread" messages received on the specified number will be retrieved. Otherwise, all unread messages irrespective of which number they were received on are retrieved.
// lets retrieve any new inbound sms messages
// received on any of our inbound numbers
$messages = $conn->get_inbound_sms();
print(count($messages) . " inbound messages retrieved\n");
// display the messages
for($i = 0; $i < count($messages); $i++)
{
// print each message on a separate line.
print($messages[$i]->to_string() . "\n");
}
The above code sample will result in the retrieval of all "unread" inbound SMS messages on all inbound numbers.
The get_inbound_sms() method also takes a boolean parameter to mark any retrieved messages as "read". In essence this stops the server from retrieving these messages again in future calls to this method.
Table of Contents
|
|
|
|
|
|
|
|
Once the client is finished sending and receiving all messages, they disconnect from the server using the disconnect() method.
// done, now disconnect
$conn->disconnect();
Table of Contents
|
|
|
|
|
|
|
|
The following section outlines the various classes making up the PHP API library.
|
|
|
|
|
|
|
|
This is the main class providing connectivity with the directSMS gateway. The following public methods are detailed below:
sms_connection()
This constructor takes a boolean argument secure which indicates whether or not to use SSL to communicate with the SMS gateway. Please note; In order to use SSL encryption, PHP 4.3 or higher is required.
connect()
This method will return a boolean after connecting and authenticating the user’s login credentials against the directSMS gateway.
If the user account used is not set up for API access, a false is returned, along with an error message. In order to use the API, you either need to contact the directSMS Support team to enable this feature on your account. This will activate your 60 day API trial. Please note; this is a single seat licence, for use on one customer account.
The second option is to purchase an enterprise licence which will require you to pass the licence key along with the login credentials for authentication when opening a new connection. This is the approach to take if you are developing an application that will be distributed to multiple customers.
is_error()
This method will return a boolean reflecting whether or not the last operation carried out using this sms_connection encountered an error condition.
get_error()
This method will return the error message associated with the error encountered during the last operation. If in fact an error condition is encountered. If the operation completed successfully, null is returned instead.
send_branded_sms()
This method will send the message passed in with the sender id specified through the directSMS gateway.
Please remember that the sender id must exceed 11 characters in length and it must not contain characters
outside of a-z, A-Z, . or 0-9. The sender id can be set to a valid mobile number which means recipients
can reply back to the number set. The replies however can not be tracked by directSMS' gateway. Upon
success, this method returns the 32 byte Message ID used by the directSMS gateway to uniquely identify
the submitted SMS message. In the case of failure, null is returned instead.
send_two_way_sms()
This method will send the message passed in through the directSMS gateway, associating it with the messageid specified (This messageid can be used in later calls to get_sms_replies() to retrieve replies to this message and this message only). Upon success, this method returns the 32 byte Message ID used by the directSMS gateway to uniquely identify the submitted SMS message. If the operation fails, null is returned instead.
schedule_branded_sms()
This method will send the message passed in with the sender id specified through the directSMS gateway at the specified time (specified in seconds after the UNIX Epoch).
Please remember that the sender id must exceed 11 characters in length and it must not contain characters
outside of a-z, A-Z, . or 0-9. The sender id can be set to a valid mobile number which means recipients
can reply back to the number set. The replies however can not be tracked by directSMS' gateway. Upon
success, this method returns the 32 byte Message ID used by the directSMS gateway to uniquely identify
the submitted SMS message. In the case of failure, null is returned instead.
schedule_two_way_sms()
This method will send the message passed in through the directSMS gatewayat the specified time (specified in seconds after the UNIX Epoch). The gateway will associate the message with the messageid specified (This messageid can be used in later calls to get_sms_replies() to retrieve replies to this message and this message only). Upon success, this method returns the 32 byte Message ID used by the directSMS gateway to uniquely identify the submitted SMS message. If the operation fails, null is returned instead.
get_sms_replies()
The method will return an array of sms_reply objects that represent the unread replies to 2-way SMS messages.
This method accepts 2 optional parameters:
messageid: This instructs the SMS gateway to retrieve all unread replies to the 2-Way SMS message identified by messageid (the parameter passed with the SMS when it was submitted using send_two_way_sms()). If this parameter is not present, unread replies to ALL 2-way messages are returned.
mark_as_read: This parameter instructs the gateway to mark all reply messages returned as "read". This stops the gateway from returning them again in the future. If this parameter is not present or is set to false the returned messages are left as is and are in fact returned again in future calls to this method.
get_inbound_sms()
The method will return an array of inbound_sms objects that represent the unread inbound SMS messages.
This method accepts 2 optional parameters:
inbound_number: This instructs the SMS gateway to retrieve all unread SMS message received on the specified inbound number only.
mark_as_read: This parameter instructs the gateway to mark all messages returned as "read". This stops the gateway from returning them again in the future. If this parameter is not present or is set to false the returned messages are left as is and are in fact returned again in future calls to this method.
disconnect()
This method will disconnect the client from the gateway and close the connection.
Table of Contents
|
|
|
|
|
|
|
|
This is the class of object returned by the directSMS gateway server in response to a request for "unread" 2-way message replies.
The attributes of this class are listed below:
message: This is the SMS message text sent as a reply to the original 2-way message.
messageid: The identifier that uniquely identifies this 2-Way message (in your system) that this reply belongs to. This is sent back to allow clients group replies to the different messages together. This is the messageid specified in your call to the get_sms_replies() method to submit the 2-way message.
mobile: The mobile phone number of the person responding to this message. The number is returned in international format with a + at the front e.g. +61412345678.
when: The number of seconds since this reply message was received by the gateway.
The following public methods are detailed below:
to_string()
This method returns a string representation of this reply object suitable for debugging.
Table of Contents
|
|
|
|
|
|
|
|
This is the class of object returned by the directSMS gateway in response to a request for "unread" inbound SMS messages.
The attributes of this class are listed below:
message: This is the SMS message text.
inbound number: The number the message was received on. The number is returned in international format with a + at the front e.g. +61412345678.
mobile: The mobile phone number of the person sending this message. The number is returned in international format with a + at the front e.g. +61412345678.
when: The number of seconds since this message was received by the gateway.
The following public methods are detailed below:
to_string()
This method returns a string representation of this reply object suitable for debugging.
Table of Contents
|
|
|
|
|
|
|
|
The following is a code sample outlining the use of the various methods in the sms_connection class.
<html>
<title>directSMS PHP Code Sample</title>
<body>
<h2>directSMS PHP Code Sample</h2>
<pre>
<?php
/************************************************************************/
/* */
/* desc: sample to show the operations available through the */
/* directsms http api */
/* */
/* version: 1.0 */
/* author: ramez zaki */
/* copyright: copyright (c) 2001-2004. all rights reserved */
/* date: 17/08/2004 */
/* */
/************************************************************************/
// load the directsms sms_connection library
require_once("sms_connection.php");
// create a new connection
$conn = new sms_connection();
// check if there are any problems. at this stage
// the only problem at this stage might be that
// the sms gateway is unreachable
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
// login and start a session using a licence key
if($conn->connect("s3UsEr",
"pAs5wOrD",
"71904d3a-d4c5ab00-46dbf93a-1f36312e"))
{
// get the current balance
$credits = $conn->get_balance();
// use the is_error() method to check for
// any problems
if($conn->is_error())
{
// show the error encountered
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
// show the balance
print("current credit balance = " . $credits . " credit(s)\n");
}
// create a new sms message
$message = "this is a test message from the directsms sms gateway";
// create an array of the mobile numbers to send this message to
$mobiles = array("0401001001", "0402002002");
// send a branded sms message with the sender id "directSMS",
// remember the sender id can not exceed 11 characters in length
// and it must not contain any characters outside of:
// a-z, A-Z, . or 0-9
// the sender id can be set to a valid mobile number which means
// recipients can reply back to the number set, the replies
// however can not be tracked by directSMS' gateway
$id = $conn->send_branded_sms($message, $mobiles, "directSMS");
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("branded message id = " . $id . "\n");
}
// send a 2-way sms message with the message id "my-id". we can
// use that to search for replies to this message later, or at
// least to correlate reply messages to this 2-way message later
// on
$id = $conn->send_two_way_sms($message, $mobiles, "my-id");
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("2-way message id = " . $id . "\n");
}
// lets retrieve any replies to the 2-way sms submitted just
// now
$replies = $conn->get_sms_replies(null, "my-id");
print(count($replies) . " replies retrieved\n");
// display the replies
for($i = 0; $i < count($replies); $i++)
{
// print each reply on a separate line
print($replies[$i]->to_string() . "\n");
}
// lets retrieve any inbound messages
$messages = $conn->get_inbound_sms();
print(count($messages) . " inbound messages retrieved\n");
// display the messages
for($i = 0; $i < count($messages); $i++)
{
// print each message on a separate line
print($messages[$i]->to_string() . "\n");
}
// create a new sms message
$message = "This is a test message going out at " .
"11AM, January 1, 2006 (EST)";
// get the number of seconds after the
// unix epoch for 1/1/2006 11:00:00
$timestamp = mktime(11, 0, 0, 1, 1, 2006);
// create an array of the mobile numbers to send this message to
$mobiles = array("0401001001", "0402002002");
// schedule the branded sms message with the sender id "directSMS",
// remember the sender id can not exceed 11 characters in length
// and it must not contain any characters outside of:
// a-z, A-Z, . or 0-9
// the sender id can be set to a valid mobile number which means
// recipients can reply back to the number set, the replies
// however can not be tracked by directSMS' gateway
$id = $conn->schedule_branded_sms($message,
$mobiles, "directSMS", $timestamp);
// check if there were any problems
// encoutered while scheduling the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("scheduled message id = " . $id . "\n");
}
// schedule a 2-way sms message with the message id "my-id". we can
// use that to search for replies to this message later, or at
// least to correlate reply messages to this 2-way message later
// on. send the message on 1/1/2006 11:00:00
$id = $conn->schedule_two_way_sms($message,
$mobiles, "my-id", $timestamp);
// check if there were any problems
// encoutered while sending the sms
if($conn->is_error())
{
print("ERROR: " . $conn->get_error() . "\n");
}
else
{
print("scheduled message id = " . $id . "\n");
}
// lets look at our credits again, they should have gone down
print("current credit balance = " . $conn->get_balance() .
" credit(s)\n");
// done, now disconnect
$conn->disconnect();
}
else
{
// show the error and stop
print("ERROR: " . $conn->get_error() . "\n");
}
}
?>
</pre>
</body>
</html>
Table of Contents
|
|
|
|
