HTTPS API v2 / Checking the SMS delivery reports

SerwerSMS.pl allows you to check the status of sent messages without having to log in to the Customer Panel. The control of the correctness of sending and the status of shipments can be checked in several available ways as well as combining them with one another in any way. In addition, in the Customer Panel you can set the option responsible for sending delivery reports directly to the URL indicated by the Subscriber. In this situation, there is no need to repeatedly query our system for the status of a single message. Instead, our system will notify the Subscriber that the message has been delivered (or for some reason has not been delivered).

Calling address

 

To check the status of messages using remote service, call the specified URL using POST method.

messages/reports

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	The number or telephone numbers sent in the table in the full format, ie. For example. +48500600700 (In the URL of a "+" is the code "% 2B").
date_from oraz date_to	DateTime	ISO eg. „2007-10-24 17:46:00”	The time interval to be displayed. This is the date and time of the Message Queuing to send messages or transfer data to the unsent in the event of an error.
id	String|Array	eg. Jdut76dn23 (litery oraz cyfry)	This parameter specifies the message ID that is assigned by the system during dispatch remote. You can also attach more ID SMS sending them through the array, then displays information about all selected messages. The maximum number of SMS ID in one query is 500.
status	String	delivered|undelivered|pending|sent|unsent|in_progress|saved	An optional parameter filters the messages displayed by the state of dispatch.
unique_id	String|Array	eg. abc123 (letters and numbers)	This parameter specifies the message ID that is assigned during dispatch by a remote client. You can also attach more unique_id sending them through the array, then displays information about all selected messages.
show_contact	Boolean	true, false or none	Display contact details if the number exists in the database of customers.

The parameters in bold are obligatory. Others are optional.

Return response

{
   "items":[{
      "id":"1c7a5432c9",
      "phone":"+48600700800",
      "status":"delivered",
      "queued":"2014-10-20 11:47:23",
      "sent":"2014-10-20 11:47:24",
      "delivered":"2014-10-20 11:47:57",
      "sender":"",
      "type":"eco",
      "text":"Test SerwerSMS.pl"
      "flash":false
      "utf":false
      "parts":1
      "cost":0.6
      "method":"PANEL"
      "mnc":26003
      "country":"Polska"
      "network":"Orange"
   },
   {
      "id":"8af63d4829",
      "phone":"+48600700800",
      "status":"sent",
      "queued":"2014-10-20 14:31:23",
      "sent":"2014-10-20 14:31:23",
      "delivered":"2014-10-20 14:32:01",
      "sender":"",
      "type":"eco",
      "text":"Test SerwerSMS.pl"
      "flash":false
      "utf":false
      "parts":1
      "cost":0.6
      "method":"PANEL"
      "mnc":26003
      "country":"Polska"
      "network":"Orange"
   },
   {
      "id":"d7cc8939e9",
      "phone":"+48500600700",
      "status":"undelivered",
      "queued":"2014-10-20 16:54:53",
      "sent":"2014-10-20 16:54:56",
      "sender":"INFORMACJA",
      "type":"full",
      "text":"Test SerwerSMS.pl",
      "reason":"message_expired"
      "flash":false
      "utf":false
      "parts":1
      "cost":0.12
      "method":"PANEL"
      "mnc":26003
      "country":"Polska"
      "network":"Orange"
   },
   {
      "id":"f3f5a0424e",
      "phone":"4888888888888",
      "status":"unsent",
      "queued":"2014-10-10 14:33:16",
      "type":"full",
      "reason":"wrong_number",
      "text":"Test SerwerSMS.pl"
   }]
}

 

In the above example, SerwerSMS.pl returned information about four messages from which one was delivered, one was sent and waits for delivery report, one was sent but not delivered and one failed to send due to the wrong recipient's number.

Explanation of the parameters feedback

Parameter	Description
id	It contains a unique number (ID).
phone	It contains the recipient's number in full format with the country code at the beginning.
status	It contains information on the status of dispatch the message. This field can take the following values: "delivered, undelivered, sent, unsent, in_progress, saved"
queued	Date and time of the adoption of SMS messages to the system (data call). In case of SMS delivery is scheduled for a specified term, appears here for the time when the SMS is sent.
sent	Date and time of sending SMS messages to the recipient.
delivered	Date and time of delivery to the recipient. This information is displayed when the message has a status of pending or has been delivered. If the message is not delivered, this information does not appear.
reason	It occurs only in case of failure of sending and tells why text message has not been sent. Possible values: message_expired, wrong_number, unsupported_number, message_rejected, operator_error, missed_call, limit_exhausted, lock_send, wrong_message, wrong_sender_name, number_is_blacklisted, sending_to_foreign_networks_is_locked, other_error.
text	It contains content of SMS message that will be sent.
flash	Information about the parameter flash.
utf	Information enabled to use Polish characters.
parts	The number of parts is made up of how many message.
cost	The cost of dispatch news accounts only type of post-paid.
method	Method dispatch messages.
mnc	Network code number.
country	Country Operator.
network	What network is a number.

 

Specify URL Subscriber on which to send delivery reports.

The appropriate options are available in the Customer Panel and require a one-time configuration. In order to send information about the subject to the Subscriber, go to the Settings menu → HTTPS XML API → Delivery reports → Send reports to the indicated URL, and enter your own URL addressing parameters such as # STAN #, # DATE #, # REASON # and # REPORT #.

Before sending information to the client, these parameters are exchanged with the data for a specific SMS message. The system checks if the customer page returns a "OK" response in response. If the system does not detect such a response, the report will be retried after 5, 15, 60 minutes and then after 24 hours. If the customer's website still does not return an answer saying "OK", SerwerSMS.pl will stop sending information regarding the delivery report. Information on delivery reports is sent using the GET method.

Transmitted parameters in the URL

Parameter	An example value or format	Description
#STAN#	Doreczono, Niedoreczono, Niewyslano, Oczekiwanie	This value determines whether forwarded to the dispatch message was sent, and if so, whether it was delivered.
#DATA#	Eg: 2009-10-21 14:23:28	Date of change of status messages, when it was delivered, the report came back undelivered, or when the message was sent to unsent.
#SMSID#	Eg. 8dfa7tvc44s	An alphanumeric string that uniquely identifies a single message.
#PRZYCZYNA#	Text description of the cause of the error, eg. „Błędny numer nadawcy”	The parameter that is passed more detailed information about the non-delivery or not send the message. It is filled only if the message has been Undelivered or unposted.

Recommended settings

 

It is recommended that delivery reports of sent messages be forwarded to the URL defined in the Client Panel. This contributes to a noticeable reduction in traffic and the handling of many unnecessary, repeatable queries.

If this is not possible, the best way to check reports is to query specific message IDs (id or unique_id). It is optimal to immediately ask many messages in one question, e.g. in packs of 50 - 200 identifiers. The maximum number of IDs to be checked during one query is 500. If more message IDs are sent, they will be omitted and will not be returned in the JSON / XML document.

Delivery reports available from the HTTPS API level reach about 14 days back. After this period, when querying for the selected message ID, an empty parameter "items" (JSON), an empty tag (XML) can be returned without information about the message. It is a signal that the message has already been archived (it is available from the Customer Panel level for about 12 months).

Delivery reports are also updated in the first 72 hours. If the delivery report is not updated by that time, it will not be updated (sometimes this happens when we do not receive a feedback report from the GSM Operator). In this case, please skip further checking the status of the message.

Too frequent inquiries about delivery reports may cause a response from the SMS.pl server administrators. In this situation, you are prompted for the recommended optimization. If there is no reaction from the client or asking the API is still not optimal, SerwerSMS.pl may temporarily block the ability to check reports for clarification.