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).
To check the status of messages using remote service, call the specified URL using POST method.
|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.|
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.
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
It contains a unique number (ID).
|phone||It contains the recipient's number in full format with the country code at the beginning.|
It contains information on the status of dispatch the message. This field can take the following values: "delivered, undelivered, sent, unsent, in_progress, saved"
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.|
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.|
The number of parts is made up of how many message.
The cost of dispatch news accounts only type of post-paid.
|method||Method dispatch messages.|
Network code number.
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.|
An alphanumeric string that uniquely identifies a single message.
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.
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.