« SMS API (v. 2.0)

Usage_examples

Overview

Activate API usage in the “Settings” of Atomic SMS Sender Control Panel (http://www.atompark.com/members/sms/profile.php) to turn on the sms gateway. Choose “Yes” in “XML interface enabled” and choose “Real Mode” or “Test Mode” in “XML interface mode”.

If “Real Mode” is chosen the text messages will be sent immediately after incoming gateway request. If the “Test Mode” is chosen, the text messages won’t be sent at all. But tasks with “Not ready” statuses will be created. It means the connection to the gateway and the data transmission was successful.

The API Usage Basics

To use API methods means to send an HTTP-request to the URL like:
http://atompark.com/api/sms/3.0/METHOD?key=public_key&sum=CONTROL_SUM&arg1=ARG_1&argN=ARG_N

where

*All the required parameter will be marked with *

The parameters can be transmitted by GET and POST methods, all the parameters must be in UTF-8 encoding. It’s recommended to transmit all the parameters by POST method to avoid saving them in the proxy server logs.
To calculate the control sum you need:

1. To sort all the incoming keys
2. To make a value concatenation over those keys
3. To make the received value concatenation with the private key
4. Take MD5 from the received result

The response comes in the JSON format object.

You can specify the public and private keys on the settings page of the server.

The example of sum calculation for addAddressbook method in PHP language.

$params ['version'] ="3.0";
$params ['action'] = "addAddressbook";
$params [‘key’] = $openKey; //you open key
$params [‘name’] = “Test addressbook”;
$params [‘description] = “Test description”;
ksort ($params);
$sum='';
foreach ($params as $k=>$v) 
$sum.=$v;
$sum .= $privateKey; //your private key
$control_sum =  md5($sum);

The successful method call results

If the method call succeed, the object will contain “result” field, its content depends on the called method, and will not contain “error” field. But even in the case of successful method running the field “warnings” may appear, it contains a package of warning objects with one- line field “warning”.

Successful method call response example:

{
   "result":{
      "id":18628,
      "name":"TEST NAME ADRESSBOOK",
      "phones":0,
      "exceptions":0,
      "creationdate":"2012-04-01 18:44:36",
   }
} 

The error response example

The criterion of error after running a method is the existence of the “error” field with HTML error message in the response object. Besides, there will be a “code” field with the code of the error in the response object if there is any error. And the “result” field must be ignored in case of error.

{
   "error":"Wrong public key.",
   "code":"-1",
   "result":"false"
} 
 

The Methods

Address Book Operations

The Address Book is the object consisting of
[id] — The identifier
[name] => Name
[phones] => The quantity of telephone numbers
[exceptions] => The number of excepted telephones
[creationdate] => The date of creation
[description] => The description

To create the Address Book

The addAddressbook() method is used.

The arguments

The request example: URL:http://atompark.com/api/sms/3.0/addAddressbook?key=public_key&sum=control_sum&name=BOOK_NAME&description=BOOK_DESCRIPTION

The response:

{
   "result":{
      "addressbook_id":21620
   }
} 
 

The unique identifier of a new Address Book addressbook_id will be returned in the response.

To delete the Address Book

The delAddressbook()method is used.

The arguments

The request example:
URL:http://atompark.com/api/sms/3.0/delAddressbook?key=public_key&sum=control_sum&idAddressBook=21619

The response:
If the transaction is successfully completed the “result” object will contain “successful”: true.

{
   "result":{
      "successful":true
   }
} 
  

If the transaction failed:
In case you are trying to delete an Address Book  that doesn’t exist the server will return

{
   "error":"No addressbook",
   "code":"202",
   "result":"false"
} 

  

To edit the Address Book

The editAddressbook()method is used.
The arguments

The request example:
URL:http://atompark.com/api/sms/3.0/editAddressbook?key=public_key&sum=control_sum&idAddressBook=21619&newName=name&newDescr=descr

The response:

{
   "result":{
      "successful":true
   }
} 
  

To get the Address Book

The getAddressbook( ) method is used.

The arguments

The Address Book return is possible:

• With the specified  identifier

  The request example:
URL:http://atompark.com/api/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161
The response:

{
   "result":{
      "id":2161,
      "name":"super book",
      "phones":25,
      "exceptions":0,
      "creationdate":"2012-04-01 18:44:36",
      "description":null
   }
} 

• without specified identifier all the Address Books will be returned.

The request example:
URL:http://atompark.com/api/sms/3.0/getAddressbook?key=public_key&sum=control_sum

• without specified identifier, but with specified offset, all the Address Book that corresponds to the offset will be returned

The request example:
URL:http://atompark.com/api/sms/3.0/getAddressbook?key=public_key&sum=control_sum&from=3&offset=3
The response:

{
   "result":{
      "count":55,
      "fields":[
         "id",
         "name",
         "phone",
         "date",
         "description"
      ],
      "data":[
         [
            "21597",
            "new book",
            "250",
            "2012-01-17 14:57:37",
            ""
         ],
         [
            "18684",
            "testNAME",
            "0",
            "2012-02-06 15:08:16",
            ""
         ],
         [
            "18661",
            "testNAME2",
            "4",
            "2012-03-27 22:45:47",
            ""
         ]
      ]
   }
} 
  

The Address Book search
The searchAddressBook() method is used.

The arguments

		{
		   "name":{
			  "operation":"like",
			  "value":"test%"
		   }
		}	  

The request example:
URL:http://atompark.com/api/sms/3.0/searchAddressBook?key=public_key&sum=control_sum&from=10&offset=3&searchFields={ "name" : { "operation" : "like" , "value" : "test%" } }

 The response:

{
   "result":{
      "count":50,
      "fields":[
         "id",
         "name",
         "phone",
         "date",
         "description"
      ],
      "data":[
         [
            "18629",
            "test2",
            "0",
            "2012-01-05 16:34:15",
            "tstdescr"
         ],
         [
            "18684",
            "testNAME",
            "0",
            "2012-02-06 15:08:16",
            ""
         ],
         [
            "18661",
            "testNAME",
            "4",
            "2012-01-27 10:45:47",
            ""
         ]
      ]
   }
} 
  

The phone numbers operations

The phone number is the object composed of:
[id]=> The phone identifier
 [addressbook]=> The Address Book identifier
 [phone]=> The phone number
 [normalphone]=>The phone number according the international standard *
 [variables]=> The variables to personalize, separated by «;» **
 [status]=> The telephone number status

* international standard
** for example: Test1;Test2;Test3

Adding  the phone number to the Address Book

The addPhoneToAddressBook()method is used.
The arguments

The request example:

The request example:
URL:http://atompark.com/api/sms/3.0/addPhoneToAddressBook?key=public_key&sum=control_sum&idAddressBook=2432&phone=380638962555&variables=test

The response:

{
   "result":{
      "phone_id":24552302
   }
} 
 

The unique phone number identifier phone_id will be returned.

Getting the Address Book

The getPhoneFromAddressBook()method is used.

The arguments

All the arguments are optional.

The request example:
URL: http://atompark.com/api/sms/3.0/getAddressbook?key=public_key&sum=control_sum&idAddressBook=2161

The response:

{
   "result":{
      "count":2,
      "fields":[
         "id",
         "phone",
         "normalPhone",
         "variables",
         "status",
         "code"
      ],
      "data":[
         [
            "24552301",
            "380632587852",
            "380632587852",
            "test variables",
            "0",
            ""
         ],
         [
            "24552302",
            "380632587853",
            "380632587853",
            "test variables",
            "0",
            ""
         ]
      ]
   }
}

  

The request example:
URL:http://atompark.com/api/sms/3.0/getPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301

The response:

{
   "result":{
      "id":24552301,
      "addressbook":18628,
      "phone":"380632587852",
      "normalphone":"380632587852",
      "variables":"test variables",
      "status":0
   }
} 
  

Deleting phone numbers from the Address Book.

The delPhoneFromAddressBook()method is used.

The Arguments:

In order to delete all the phone numbers it is necessary to specify the Address Book identifier, but to delete a single phone you need to specify the phone number identifier.

The request example:
URL:http://atompark.com/api/sms/3.0/delPhoneFromAddressBook?key=public_key&sum=control_sum&idPhone=24552301

The response:

{
   "result":{
      "successful":true
   }
} 
  

Editing phone numbers in the Address Book

The editPhone() method is used..
The arguments

It is necessary to input the new phone number (according to the international standard) and the new line of variables.

The request example:
URL:http://atompark.com/api/sms/3.0/editPhone?key=public_key&sum=control_sum&idPhone=24552301&phone=380657412569&variables=test

The response:

{
   "result":{
      "successful":true
   }
} 
 

Looking up phone numbers in the Address Book

The searchPhones() method is used..
The arguments

{
   "phone":{
      "operation":"like",
      "value":"38063%"
   }
}	  

The request example:
URL:{ "variables" : { "operation" : "like" , "value" : "иван%" } }">http://atompark.com/api/sms/3.0/searchPhones?key=public_key&sum=control_sum&searchFields={ "variables" : { "operation" : "like" , "value" : "иван%" } }

The response:

{
   "result":{
      "count":1,
      "fields":[
         "id",
         "idAddressBook",
         "phone",
         "normalPhone",
         "variables",
         "status",
         "code",
         "maid"
      ],
      "data":[
         [
            "24552295",
            "21597",
            "9999999999",
            "9999999999",
            "Иван Васильевич",
            "0",
            "",
            "0"
         ]
      ]
   }
} 
  
  

The exceptions operations.

The exception is the object composed of:
[id] => The identifier
[phone] =>The phone number
[added] => The adding date
[comment] => The description

To add the telephone number to the exceptions

The addPhoneToExceptions() method is used.
The arguments

To add the phone to the exceptions it is necessary to relay the phone identifier or the phone number.
The request example:
URL: http://atompark.com/api/sms/3.0/addPhoneToExceptions?key=public_key&sum=control_sum&idPhone=24552291&reason=test_add

The response:

{
   "result":{
      "exseption_id":24552302
   }
} 
 

The unique exception identifier exception_id will be returned in the response.

Deleting phone numbers from the exceptions

The delPhoneFromExceptions() method is used.
The arguments

To delete the telephone number it is necessary to relay one of these parameters.

The request example:
URL:http://atompark.com/api/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

The response:

{
   "result":{
      "successful":true
   }
} 

 

Editing phone numbers in the exceptions

The editExceptions() method is used.
The arguments

The request example:
URL: http://atompark.com/api/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

The response:

{
   "result":{
      "successful":true
   }
} 
  

Getting the exception object

The getException() method is used.
The arguments

The request example:
URL: http://atompark.com/api/sms/3.0/delPhoneFromExceptions?key=public_key&sum=control_sum&idPhone=24552291

The response:

{
   "result":{
      "id":181042,
      "phone":"380692587852",
      "added":"2012-04-04 10:55:08",
      "comment":"testREASON_PHONE"
   }
} 
  
  

The request example:
URL:http://atompark.com/api/sms/3.0/getException?key=public_key&sum=control_sum&from=1&offset=2

The response:

{
   "result":{
      "count":6,
      "fields":[
         "id",
         "phone",
         "added",
         "comment"
      ],
      "data":[
         [
            "181038",
            "99999999999",
            "2012-03-12 10:44:31",
            "testREAS!!!"
         ],
         [
            "181042",
            "88888888888",
            "2012-04-04 10:55:08",
            "testREASON_PHONE"
         ]
      ]
   }
} 
  

Searching through exceptions

The searchPhonesInExceptions() method is used..
The arguments

{
   "descr":{
      "operation":"like",
      "value":"testR%"
   }
} 
	  

The request example:
URL:{ "variables" : { "operation" : "like" , "value" : "иван%" } }"> http://atompark.com/api/sms/3.0/searchPhones?key=public_key&sum=control_sum&searchFields={ "variables" : { "operation" : "like" , "value" : "иван%" } }

The response:

{
   "result":{
      "count":6,
      "fields":[
         "id",
         "phone",
         "added",
         "comment"
      ],
      "data":[
         [
            "181041",
            "91234561",
            "2012-04-04 10:11:40",
            "testREASON_PHONE"
         ],
         [
            "181038",
            "74999404711",
            "2012-03-12 10:44:31",
            "testREASasdON!!!"
         ]
      ]
   }
} 
  
  

Checking the balance

The request example:
URL:http://atompark.com/api/sms/3.0/getUserBalance?key=public_key&sum=control_sum¤cy=USD

The response:

{
   "result":{
      "currency":"USD",
      "balance_currency":2.5
   }
} 

  

The sender name registration

The registerSender() method is used.
The arguments

The request example:
URL: http://atompark.com/api/sms/3.0/registerSender?key=public_key&sum=control_sum&name=qwerty&country=UA

The response:

{
   "name_id":748,
   "status":0
} 

The status in the “status” field will be returned in the response:
0 – pending approval
1 — approved
2 — denied

Getting the sender status

The getSenderStatus() method is used.
The arguments

To get the sender status it is necessary to transmit the sender name identifier or to transmit the sender name and the country. To get all the objects specify the offset.

The request example:
URL:http://atompark.com/api/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&idName=747

или

URL: http://atompark.com/api/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&name=qwerty&country=ua

The response:

{
   "result":{
      "id":747,
      "name":"qwerty",
      "status":"0",
      "country":"UA"
   }
}   
  

URL: http://atompark.com/api/sms/3.0/getSenderStatus?key=public_key&sum=control_sum&from=10&offset=2

The response:

{
   "result":{
      "count":661,
      "fields":[
         "id",
         "country",
         "name",
         "status",
         "description"
      ],
      "data":[
         [
            "11",
            "UA",
            "test",
            "1",
            ""
         ],
         [
            "12",
            "UA",
            "test1",
            "1",
            ""
         ]
      ]
   }
}   
  

Bulk sms operations

Creating a campaign

The createCampaign() method is used.
The arguments:

The “datetime” parameter is used if the campaign must be sent not immediately, but be scheduled. For the immediately delivery this parameter needs to be empty.

The example of date format during the parameter transmission – 2012-05-01 00:20:00

The “batch” and “batchinterval” parameters are used if the delivery needs to be sent by parts. If the delivery is planned by an iteration, the parameters must be transmitted with the 0 value.

The optional parameter “control_phone” is specified if the delivery quality control on the input phone is necessary. The phone number must be in the international standard format.

The request example:
URL: http://atompark.com/api/sms/3.0/createCampaign?key=public_key&sum=control_sum&sender=Info&text=Testing%20SMS&list_id=1234&datetime=&batch=0&batchinterval=0&sms_lifetime=0&controlnumber=

The response:

{
"result":{
"id":1853173,
"price":403.44
}
}
  

Where id is the created campaign identifier, price is the value of the delivery in the currency, specified in the user settings. –

Sending a single the text message to a particular phone number

The sendSMS() method is used.
The arguments:

The “datetime” parameter is used if it is necessary not to send the delivery immediately but to schedule it. For the immediately delivery just transmit the empty parameter. The example of date format during the parameter transmission – 2012-05-01 00:20:00

The request example:
URL: http://atompark.com/api/sms/3.0/sendSMS?key=public_key&sum=control_sum&sender=Info&text=Testing%20SMS&phone=380972920383&datetime=&sms_lifetime=0

The response:

{
"result":{
"id":1853174,
"price":0.13
}
}
 

Getting information over the campaign results

The getCampaignInfo() method is used.
The arguments:

{
"result":{
"sent":1,
"delivered":1,
"not_delivered":0,
"price":0.13,
"status":3
}
}
 

 
{
"result":{
"phone":[
"380972920383"
],
"sentdate":[
"0000-00-00 00:00:00"
],
"donedate":[
"0000-00-00 00:00:00"
],
"status":[
"0"
]
}
}  

{
"result":{
"successful":1
}
}

{
"result":{
"successful":1
}
}
  

{
"result":{
"price":1210.32
}
}

    

{
"result":{
	"id": [
			"10012",
			"10013"
			],
"from": [
"Sender1",
"Sender2"
],
 "body": [
"Text of SMS1",
"Text of SMS2"
],
 "status" : [
3,
3
]
}
}