HTTPS API v2 / Introduction
SerwerSMS.pl allows you to send messages using the Customer Panel and functions available there as well as using the so-called remote service. Thanks to the latter method, it is possible to send and check the correctness of sent messages as well as access to other functions without having to log in to the Customer Panel.
Communication with SerwerSMS.pl takes place by calling the URL with the POST method with the appropriate parameters. An SSL encrypted connection (https) is recommended. As a response, a document in JSON or XML format is returned indicating the result of the action being called.
The maximum size of a single notification for sending a message is 100,000 numbers. It is recommended to send smaller amounts of data, eg 50-200 numbers in one application. If more than 100,000 or more personalized messages (number and message, above 10,000) are sent in a single application, a generic error will be generated and no messages will be sent.
The service of remote service via HTTPS API also allows sending information about delivery reports and SMS replies directly to the Subscriber's URL address. In order for SerwerSMS.pl to automatically send information about delivery reports to the Subscriber, it is necessary to set the appropriate options in the Interface Settings tab (HTTPS XML API or settings in the appropriate section, eg ND / NDI) in the Customer Panel. More information on this subject can be found in the further part of the documentation.
It is recommended that communication via HTTPS API should be done with logins created specifically for connection via the API. The API user account can be created in the Client Panel → Interface settings → HTTPS XML API → Users.
It is also important to remember the format of the phone numbers provided. Each number should be in an international format, for example in the case of numbers of Polish cellular networks, it is +48500600700. Similarly, if the number is from another country's network, it should be preceded by the area code. Polish numbers that do not have the prefix number +48, if possible will be automatically adjusted to the required format, eg:
500 600 700 -> +48500600700
48500600700 -> +48500600700
0048.500600700 -> +48500600700
Foreign numbers must have a full international prefix preceded by the "+" sign (plus). In addition, pay attention to the length of the address sent by the GET method because if you send a larger amount of data, 255 characters may be exceeded. In this case, please send data by POST.
The address to which you should send requests to the HTTPS API is:
https://api2.serwersms.pl/
The default format for returned data is JSON. To call dispatch messages, use the structure:
https://api2.serwersms.pl/messages/send_sms
or:
https://api2.serwersms.pl/messages/send_sms.json
If you change the data format to XML, you must use the .xml extension in the URL:
https://api2.serwersms.pl/messages/send_sms.xml
Alternate address (HTTP or HTTPS):
https://s1api2.serwersms.pl/
In order to meet the expectations of our current and future customers, we provide the opportunity to check and test the service of remote service via HTTPS API for people who do not yet have accounts at SerwerSMS.pl. To use the test account you must log in to the following data:
Login: demo
Password: demo
Queries that in a normal account send messages, in this case only generate a return in the form of a document JSON / XML (the same as in the case of the parameter "test = 1"). Feedback is identical to the standard messaging . To accurately check delivery reports and read your feedback has been sent two text messages and one reply SMS. In return, the following documents JSON:
Sent SMS 1:
{
"success":true,
"queued":1,
"unsent":0,
"items":[{
"id":"c2451e1302",
"phone":"+48500600700",
"status":"queued",
"queued":"2014-10-16 16:49:05",
"parts":1,
"text":"This is a test message from SerwerSMS.pl"
}]
}
Sent SMS 2 (return in the form of an XML document):<result>
<success>1</success>
<queued>1</queued>
<unsent>0</unsent>
<items>
<item>
<id>c2451e1302</id>
<phone>+48783820099</phone>
<status>queued</status>
<queued>2014-10-17 16:00:15</queued>
<parts>1</parts>
<text>This is a test message from SerwerSMS.pl</text>
</item>
</items>
</result>
Reply to SMS ECO+ +:
{
"items":[{
"id":2469266,
"type":"eco",
"phone":"+48783820099",
"recived":"2014-10-16 16:52:03",
"message_id":"c2451e1302",
"blacklist":false,
"text":"Thank you for this information. Regards"
}]
}
On the basis of the above information, you can successfully test and implement remote service to your own software so that the integration process itself after using the SerwerSMS.pl offer will be shorter and more reliable.
We also offer ready libraries to be used implementing the HTTPS API in the following programming languages:
- Client PHP https://github.com/SerwerSMSpl/serwersms-php-api-v2
- Client Node https://github.com/SerwerSMSpl/serwersms-node-api
- Client C# https://github.com/SerwerSMSpl/serwersms-csharp-api
- Client Java https://github.com/SerwerSMSpl/serwersms-java-api
- Client Python https://github.com/SerwerSMSpl/serwersms-python-api
- Client Ruby https://github.com/SerwerSMSpl/serwersms-ruby-api
- Client Perl https://github.com/SerwerSMSpl/serwersms-perl-api
- Client Bash https://github.com/SerwerSMSpl/serwersms-bash-client
All actions described in the documentation can be tested using the API console available at: http://apiconsole.serwersms.pl​