Difference between revisions of "Send SMS"

From Boxis.net API Docs
Jump to: navigation, search
(Input params)
(Example URL with POST values)
 
(45 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
 
=SMS Function: sendSMS=
 
=SMS Function: sendSMS=
  
Line 4: Line 5:
  
  
----
+
== Input params ==
  
----
+
*'''version'''::String - ''API version (e.g. '1.0')''
=== Input params ===
+
{|
+
|-
+
| - '''version''' (string)
+
''API version (e.g. '1.0')''
+
|-
+
| - '''timestamp''' (String)
+
''Sequence of characters, denoting the date and time (e.g '1336553826')''
+
|-
+
| - '''username''' (String)
+
''User e-mail address (e.g 'mail1@example.com')''
+
|-
+
| - '''authcode''' (String)
+
'' md5 hash consisting of the concatenation of timestamp and user_key (e.g md5(1336553826BX3KwWU2SuqvoEWnjYmOibf'))''
+
|-
+
| - '''section''' (String)
+
''API module name. Use 'sms' value
+
|-
+
| - '''action''' (String)
+
''API module function. Use 'sendSMS' value
+
|-
+
| - '''content''' (String)
+
''The message text. Content of one message is normally 160 characters per single SMS or 70 in case of using at least one special character (polish characters are considered to be special characters). The maximal message is set to 459 normal characters or 201 if special chars are used and it is being sent as one block of 3 messages joined together and charged as three messages.''
+
|-
+
| - '''flash''' (Boolean) - optional
+
''Sending a message in flash mode can be activated by setting this parameter to 1''
+
|-
+
| - '''fast''' (Boolean)  - optional
+
''Setting this parameter to „1” will result in sending message with the highest priority which ensures the quickest possible time of delivery. This parameter may be used for both PRO and ECO messages. Fast messages costs 50% more than normal message.
+
'''Attention!''' Mass and marketing messages  mustn’t be sent with fast parameter''
+
|-
+
| - '''schedule''' (Boolean) - optional
+
''Adding a message to the schedule can be activated by setting this parameter to 1''
+
|-
+
| - '''timesend''' (String) - optional, use when schedule is 1
+
''Date in 'yyyy-mm-dd hh:mm' format when message will be sent. Setting a past date will result in sending message instantly''
+
|-
+
|}
+
  
=== Example URL with POST values ===
+
*'''timestamp'''::String - ''Sequence of characters, denoting the date and time (e.g '1336553826')''
{|
+
 
|-
+
*'''username'''::String - ''User e-mail address (e.g 'mail1@example.com')''
| <nowiki>https://boxis.net/xmlapi.php</nowiki>
+
 
|-
+
*'''authcode'''::String - '' md5 hash consisting of the concatenation of timestamp and user_key (e.g md5(1336553826BX3KwWU2SuqvoEWnjYmOibf'))''
| <nowiki>POST: returntype=xml&sender_name=boxis.net&recipients=a:1:{i:0;s:11:"48599131568";}&content=test1&version=1.0&username=your@mail.com&timestamp=1337844592&authcode=1234567890&json=sms&action=sendSMS</nowiki>
+
 
|-
+
*'''section'''::String - ''API module name. Use 'sms' value
|}
+
 
 +
* '''action'''::String - ''API module function. Use 'sendSMS' value
 +
 
 +
*'''recipients[1],recipients[2],..recipients[n]'''::Array of Strings - ''List of phobne numbers''
 +
 
 +
* '''content'''::String - ''The message text. Content of one message is normally 160 characters per single SMS or 70 in case of using at least one special character (polish characters are considered to be special characters). The maximal message is set to 459 normal characters or 201 if special chars are used and it is being sent as one block of 3 messages joined together and charged as three messages.''
 +
 
 +
* '''encoding'''::String - ''Possible values ('''case sensitive!'''): UTF-8, ISO-8859-2, Windows-1252
 +
 
 +
*'''flash'''::Boolean (optional) - ''Sending a message in flash mode can be activated by setting this parameter to 1''
 +
 
 +
* '''fast'''::Boolean (optional) - ''Setting this parameter to „1” will result in sending message with the highest priority which ensures the quickest possible time of delivery. This parameter may be used for both PRO and ECO messages. Fast messages costs 50% more than normal message. '''Attention!''' Mass and marketing messages  mustn’t be sent with fast parameter''
 +
 
 +
*'''schedule'''::Boolean (optional) - ''Adding a message to the schedule can be activated by setting this parameter to 1''
 +
 
 +
* '''timesend'''::String (optional, use when schedule is 1) - ''Date in 'yyyy-mm-dd hh:mm' format when message will be sent. Setting a past date will result in sending message instantly''
 +
 
 +
== Example URL with POST values ==
 +
 
 +
<pre>
 +
https://api.boxis.net/
 +
POST: returntype=xml&sender_name=boxis.net&recipients[1]=48599131568&content=test1&encoding=UTF-8&version=1.0&username=your@mail.com&timestamp=1337844592&authcode=1234567890&section=sms&action=sendSMS
 +
</pre>
  
=== Output params ===
+
== Output params ==
  
 
==== Example in XML (Success) ====
 
==== Example in XML (Success) ====
  
===== Single SMS (no scheduled) =====
+
* Send Single SMS (no scheduled)
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 72: Line 57:
 
</pre>
 
</pre>
  
===== Single Scheduled SMS =====
+
* Send Single Scheduled SMS
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 85: Line 70:
 
</pre>
 
</pre>
  
===== Bulk SMS (no scheduled) =====
+
* Send Bulk SMS (no scheduled)
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 110: Line 95:
 
</pre>
 
</pre>
  
===== Bulk Scheduled SMS =====
+
* Send Bulk Scheduled SMS
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 146: Line 131:
 
</pre>
 
</pre>
  
==== Example in Json (Success) ====
+
==== Example in JSON (Success) ====
  
===== Single SMS (no scheduled) =====
+
* Send Single SMS (no scheduled)
 
<pre>
 
<pre>
 
{"result":"1",
 
{"result":"1",
Line 157: Line 142:
 
</pre>
 
</pre>
  
===== Single Scheduled SMS =====
+
* Single Scheduled SMS
 
<pre>
 
<pre>
 
{"result":"1",
 
{"result":"1",
Line 166: Line 151:
 
</pre>
 
</pre>
  
===== Bulk SMS (no scheduled) =====
+
* Send Bulk SMS (no scheduled)
 
<pre>
 
<pre>
 
{"result":"1",
 
{"result":"1",
Line 181: Line 166:
 
</pre>
 
</pre>
  
===== Bulk Scheduled SMS =====
+
* Send Bulk Scheduled SMS
 
<pre>
 
<pre>
 
{"result":"1",
 
{"result":"1",
Line 196: Line 181:
 
</pre>
 
</pre>
  
==== Example in Json (Error) ====
+
==== Example in JSON (Error) ====
  
 
<pre>
 
<pre>
Line 204: Line 189:
 
</pre>
 
</pre>
  
==== Example using our PHP Class ====
 
  
 +
== Example using our PHP Class ==
 
<pre>
 
<pre>
 
/* API LOGIN DETAILS */
 
/* API LOGIN DETAILS */
Line 214: Line 199:
 
$apitype  = 'sms';
 
$apitype  = 'sms';
 
$command  = 'sendSMS';
 
$command  = 'sendSMS';
$params  = array(
 
 
$params  = array(
 
$params  = array(
 
     'returntype' => 'xml',
 
     'returntype' => 'xml',
 
     'sender_name' => 'boxis.net',
 
     'sender_name' => 'boxis.net',
     'recipients' => array('48599131568'),
+
     'recipients[1]' => '48599131568',
 
     'content' => 'test1',
 
     'content' => 'test1',
 
);
 
);
Line 224: Line 208:
 
/* PROCESS THE ACTION */
 
/* PROCESS THE ACTION */
 
$boxisAPI = new BoxisAPIConnection($email, $apikey);
 
$boxisAPI = new BoxisAPIConnection($email, $apikey);
$return = $boxisAPI->call($apitype, $command, $params);
+
$return = $boxisAPI->call($apitype, $command, $params, $timestamp);
 +
 
 +
/* TIMESTAMP SYNCHRONIZATION (JSON EXAMPLE)
 +
if($return['timestamperror']) {
 +
    $timestamp = $return['timestamp'];
 +
    $return = $boxisAPI->call($apitype, $command, $params, 'json', $timestamp);
 +
}
 +
*/
 +
 
 +
/* TIMESTAMP SYNCHRONIZATION (XML EXAMPLE)*/
 +
/*
 +
if($return->timestamperror) {
 +
    $timestamp = $return->timestamp;
 +
    $return = $boxisAPI->call($apitype, $command, $params, 'xml', $timestamp);
 +
}
 +
/*
 +
 
 
</pre>
 
</pre>

Latest revision as of 09:09, 27 June 2014

SMS Function: sendSMS

With this command, you are able to send SMS with boxis.net.


Input params

  • version::String - API version (e.g. '1.0')
  • timestamp::String - Sequence of characters, denoting the date and time (e.g '1336553826')
  • username::String - User e-mail address (e.g 'mail1@example.com')
  • authcode::String - md5 hash consisting of the concatenation of timestamp and user_key (e.g md5(1336553826BX3KwWU2SuqvoEWnjYmOibf'))
  • section::String - API module name. Use 'sms' value
  • action::String - API module function. Use 'sendSMS' value
  • recipients[1],recipients[2],..recipients[n]::Array of Strings - List of phobne numbers
  • content::String - The message text. Content of one message is normally 160 characters per single SMS or 70 in case of using at least one special character (polish characters are considered to be special characters). The maximal message is set to 459 normal characters or 201 if special chars are used and it is being sent as one block of 3 messages joined together and charged as three messages.
  • encoding::String - Possible values (case sensitive!): UTF-8, ISO-8859-2, Windows-1252
  • flash::Boolean (optional) - Sending a message in flash mode can be activated by setting this parameter to 1
  • fast::Boolean (optional) - Setting this parameter to „1” will result in sending message with the highest priority which ensures the quickest possible time of delivery. This parameter may be used for both PRO and ECO messages. Fast messages costs 50% more than normal message. Attention! Mass and marketing messages mustn’t be sent with fast parameter
  • schedule::Boolean (optional) - Adding a message to the schedule can be activated by setting this parameter to 1
  • timesend::String (optional, use when schedule is 1) - Date in 'yyyy-mm-dd hh:mm' format when message will be sent. Setting a past date will result in sending message instantly

Example URL with POST values

https://api.boxis.net/
POST: returntype=xml&sender_name=boxis.net&recipients[1]=48599131568&content=test1&encoding=UTF-8&version=1.0&username=your@mail.com&timestamp=1337844592&authcode=1234567890&section=sms&action=sendSMS

Output params

Example in XML (Success)

  • Send Single SMS (no scheduled)
<?xml version="1.0" encoding="UTF-8"?>
<return>
  <result>1</result>
  <resulttxt>success</resulttxt>
  <params>
    <sms_id>133655645431563000007320</sms_id>
  </params>
  <timestamp>1335767184</timestamp>
</return>
  • Send Single Scheduled SMS
<?xml version="1.0" encoding="UTF-8"?>
<return>
  <result>1</result>
  <resulttxt>success</resulttxt>
  <params>
    <sms_id>133655645431563000007320</sms_id>
  </params>
  <timestamp>1335767184</timestamp>
</return>
  • Send Bulk SMS (no scheduled)
<?xml version="1.0" encoding="UTF-8"?>
<return>
  <result>1</result>
  <resulttxt>success</resulttxt>
  <params>
    <sent>
      <sms1>
        <id>133654685431563000002080</id>
        <phone>48511141565</phone>
      </sms1>
      <sms2>
        <id>133654685409553000016930</id>
        <phone>48514645553</phone>
      </sms2>
    </sent>
    <not_sent>
       <phone>48714645553</phone>
    </not_sent>
  </params>
  <timestamp>1335767184</timestamp>
</return>
  • Send Bulk Scheduled SMS
<?xml version="1.0" encoding="UTF-8"?>
<return>
  <result>1</result>
  <resulttxt>success</resulttxt>
  <params>
    <scheduled>
      <sms1>
        <id>133654685431563000002080</id>
        <phone>48511141565</phone>
      </sms1>
      <sms2>
        <id>133654685409553000016930</id>
        <phone>48514645553</phone>
      </sms2>
    </scheduled>
    <not_scheduled>
       <phone>48714645553</phone>
    </not_scheduled>
  </params>
  <timestamp>1335767184</timestamp>
</return>

Example in XML (Error)

<?xml version="1.0" encoding="UTF-8"?>
<return>
  <result>0</result>
  <resulttxt>error: {error description}</resulttxt>
  <timestamp>1335767184</timestamp>
</return>

Example in JSON (Success)

  • Send Single SMS (no scheduled)
{"result":"1",
 "resulttxt":"success",
 "params":{
   "sms_id":"133655724631563000002130"}
 "timestamp":1335777400}
  • Single Scheduled SMS
{"result":"1",
 "resulttxt":"success",
 "params":{
   "sms_id":"133655724631563000002130"}
 "timestamp":1335777400}
  • Send Bulk SMS (no scheduled)
{"result":"1",
 "resulttxt":"success",
 "params":{
   "sent":{
     "sms1":{
       "id":"133655714331563000008070",
       "phone":"48511131564"}},
    "not_sent":{
      "sms1":"48717131563",
      "sms2":"48611171563"}},
 "timestamp":1335777400}
  • Send Bulk Scheduled SMS
{"result":"1",
 "resulttxt":"success",
 "params":{
   "scheduled":{
     "sms1":{
       "id":"133655714331563000008070",
       "phone":"48511131564"}},
    "not_scheduled":{
      "sms1":"48717131563",
      "sms2":"48611171563"}},
 "timestamp":1335777400}

Example in JSON (Error)

{"result":"0",
 "resulttxt":"Error: {error description}",
 "timestamp":1335777400}


Example using our PHP Class

/* API LOGIN DETAILS */
$email    = 'your@mail.com';    // your username
$apikey   = '1234567890';        // your apikey

/* API COMMAND DETAILS */
$apitype  = 'sms';
$command  = 'sendSMS';
$params   = array(
    'returntype' => 'xml',
    'sender_name' => 'boxis.net',
    'recipients[1]' => '48599131568',
    'content' => 'test1',
);

/* PROCESS THE ACTION */
$boxisAPI = new BoxisAPIConnection($email, $apikey);
$return = $boxisAPI->call($apitype, $command, $params, $timestamp);

/* TIMESTAMP SYNCHRONIZATION (JSON EXAMPLE)
if($return['timestamperror']) {
    $timestamp = $return['timestamp'];
    $return = $boxisAPI->call($apitype, $command, $params, 'json', $timestamp);
}
*/

/* TIMESTAMP SYNCHRONIZATION (XML EXAMPLE)*/
/*
if($return->timestamperror) {
    $timestamp = $return->timestamp;
    $return = $boxisAPI->call($apitype, $command, $params, 'xml', $timestamp);
}
/*