HTTPS API v2 / Sending SMS messages with the same content

Calling address

In order to send an SMS message using the Remote Service, you must send a specific application via HTTP or HTTPS using the POST method.

messages/send_sms

WARNING! To send an SMS FULL message fill in the sender field (alphanumeric name or number). If the sender parameter is omitted or its value is empty, an ECO + type SMS will be sent. Filling the parameter of the sender determines whether ECO + or FULL will be sent.

Available parameters

Parameter Type An example value or format Description
username String login Username used to dispatch the message
password String password Password to the account
phone String|Array +48500600700 Number or table phones numbers .
text String content Message content.
flash Boolean true, false or none

An optional parameter.
test Boolean true, false or none

The optional parameter, so you can check out the question of sending SMS messages. In response document is generated JSON / XML identical to the standard question, but the message will not be sent. Useful for testing applications (debug).
sender String

The alphanumeric name of the sender for example. "INFORMATION" own name, "2waySMS" or number 4 or 9-digit.

 The optional parameter allows you to change the sender field of SMS messages to almost any name or number. Each name of the sender must first be added to the Panel or API, and then approved by the administrator SerwerSMS.pl. Setting the name to "2waySMS" will replace the header with a random 9-digit number to which you can send a reply.
wap_push String Address URL or none An optional parameter.
utf Boolean true, false or none

An optional parameter allows you to send SMS FULL containing eg. Polish diacritics, Cyrillic, etc. Only available in SMS FULL. Using this option changes the maximum length of a single SMS from 160 to 70 characters.
details Boolean true, false or none The parameter displays in response to feedback details sent messages.
vcard Boolean true, false or none

An optional parameter, which allows sending messages VCARD.
speed Boolean 1, 0 or none

An optional parameter allows you to send an independent channel with the highest quality (extra charge). 
date DateTime ISO eg.
„2015-02-22 12:25:55”		 An optional parameter allows you to specify the date of dispatch messages
unique_id String|Array eg. 6asTD3fif98gj An optional parameter allows you to define your own ID sent message.

The identifier can be a minimum of 3 characters and a maximum of 50 alphanumeric characters (a-z, A-Z, 0-9). For group mailings, another unique_id must be unique and the number unique_id must be consistent with the amount of numbers.
group_id String|Array eg. 123456789

ID or group IDs in the Customer Panel. These identifiers can be downloaded using action groups / index or by copying them from the editing group in the Customer Panel.
contact_id String|Array eg. 123456789

 

ID or IDs of contacts in the Customer Panel. These identifiers can be downloaded using the stock contacts / index.
dlr_url String

http://www.twojadres.pl/skrypt.php?smsid=#SMSID#&stan=#STAN#&data=#DATA# 

This parameter allows the transmission method Push delivery reports on URL the Client. Setting this option to query the API overrides that in the settings in the Customer Panel. The address should be passed in encrypted form by the urlencode (). Address to forward reports applies to all messages submitted for execution within a single query.

Available parameters:

#SMSID# - message ID
#STAN# - condition of delivery
#DATA# - date of status change
#PRZYCZYNA# - the reason for non-delivery messages

The parameters marked in bold are mandatory. The others are optional.

If you wish to send a message as a vCard (parameter "vcard = true"), the structure of the message must be in a particular format. An example of the Vcard format can be found in the generally available documentation on the Internet or using the Customer Panel and SMS form. The next tags in the Vcard message should be separated by a newline character.

The FULL SMS message that contains Polish special characters should be properly encoded in UTF-8 before sending. To send a message with Polish characters, the "utf = true" parameter must be set, the subscriber must be authorized to send SMS messages FULL and the sender field must be filled in (this means that an SMS FULL will be sent).

Return response

Depending on the data sent, SerwerSMS.pl will generate a document in the JSON / XML format with information about the actions carried out. In the case of correctly sending an SMS message, the customer will receive, for example, the following information:

{
   "success":true,
   "queued":1,
   "unsent":0
}

If you specify an additional parameter details = true, the answer feedback will be supplemented with details of sent messages that can be writed in the database after the client software:{
   "success":true,
   "queued":1,
   "unsent":0,
   "items":[{
        "id":"1c142d81c7",
        "phone":"+48500600700",
        "status":"queued",
        "queued":"2014-10-16 16:49:05",
        "parts":1,
        "text":"Test SerwerSMS.pl"
   }]
}

The "success" contains information about the success of the operation.  The "queued" and "unset" attributes include the number of queued and unsent messages. Section "items" contains phone numbers and message ID passed to send (and the messages are queued for a reason).  The unique SMS tag can be used later to check the status of sending a specific SMS message remotely. The parameter "text" appears content sent SMS messages. The phone number is automatically corrected and displayed in full format required by SerwerSMS.pl or the country code (eg. 48) at the beginning.

 

In the case of providing, for example, a wrong phone number, an error message will be generated as well as a message ID (so that you can check later when and why it was not sent). For example, if two correct numbers and two wrong numbers are given, the system will generate the following JSON document:

{
   "success":true,
   "queued":2,
   "unsent":2,
   "items":[{
      "id":"32039da8e9",
      "phone":"+48500600700",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"Test platform SerwerSMS.pl"
   },
   {
      "id":"844c2b4af0",
      "phone":"+48500600500",
      "status":"queued",
      "queued":"2014-10-20 12:32:52",
      "parts":1,
      "text":"Test platformy SerwerSMS.pl"
   },
   {
      "id":"6e373d7856",
      "phone":"45616",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Incorrect number",      "text":"Test platform SerwerSMS.pl"
   },
   {
      "id":"bf069fe2c1",
      "phone":"7799123",
      "status":"unsent",
      "queued":"2014-10-20 12:32:52",
      "error_code":3103,
      "error_message":"Incorrect number",
      "text":"Test platform SerwerSMS.pl"
   }]
}

 

In addition, a general error can be generated where there is no delimitation to the queued. This can happen, for example, when the customer does not define the message content, does not provide phone numbers, his account is not active or there is another problem described in the error messages. If you do not enter the message, the following message will be generated:

{
   "error":{
      "code":3101,
      "type":"SendError",
      "message":"The message is empty"
   }
}

In the case of failure to provide telephone numbers:

{
   "error":{
      "code":3104,
      "type":"SendError",
      "message":"No specified phone numbers"
   }
}

Recommended settings

In the case of medium and large amounts of messages sent several thousand or more, it is recommended to transfer messages in "packages" after about 50-200 numbers in a single query. This will speed up considerably the process of transferring the data to SerwerSMS.pl and reduce the amount necessary to send queries.

If you try to send messages to two or more of the same phone numbers in a single query, the system will only send a message once to that number.

The recommended timeout value for a single query is 30-60 seconds.