This feature is dependent on Bug 14723. Since Bug 14723 introduces database a new column, 'delivery_note', we can now take better use of it if our SMS Gateway provider supports status reports. Our local SMS Gateway provider sends us a HTTP request containing information about the status of delivery. If the delivery was failed, they will let us know the reason for failure. We should use the 'delivery_note' column for this data. I propose taking REST API way to accept reports from provider and change the status of messages accordingly in the database.
A more detailed explanation for the reports and delivery notes. Our SMS Gateway provider has a two-step delivery success response. When sending the HTTP request from our SMS::Send driver, our SMS Gateway provider will immediately respond if the message is placed for delivery OR the following error messages: - unknown error - invalid recipient (phone# syntax is invalid) - duplicate recipient (same phone# is given multiple times) - unallowed recipient (non-mobile/foreign phone#) This is the first step to gather delivery notes from SMS Gateway provider. With Bug 14791 we are able to throw Exceptions from SMS::Send driver. I propose we throw an exception (e.g. Koha::Exception::SMSDeliveryFailure) with an accurate description of the error. The exception will be forwarded all the way to C4::Letters::_send_message_by_sms() where we can set the status of the message to 'failed' and add the delivery note accordingly. However, if the initial request was successful and the provider has accepted it for delivery, we will move to the second phase of the delivery. Second phase occurs after the delivery is complete on the provider's end. They will send us a request with appropriate information of the state of the delivery and an error message if the delivery was failed. For the second phase we should use REST API.
Created attachment 42674 [details] [review] Bug 14767: SMS delivery notes from SMS Gateway provider's report Two-phase method to receive delivery notes from SMS Gateway provider. This is an example how to receive Gateway reports and most likely does not apply for your local provider. However, it should give you a good starting point to start receiving SMS delivery notes with REST API with your own provider. Example driver is SMS::Send::Labyrintti::Driver Phase ONE (POST to provider) -------------------------------- In phase ONE, as normally, we make a HTTP POST to our SMS Gateway provider and give them the details of SMS. They will instantly respond if the message was placed for delivery. If not, there must have been some error and we will throw a Koha::Exception::SMSDeliveryFailure. This will be caught by C4::Letters via C4::SMS. Message in the queue will be set as "failed" and the reason for failure will be added to delivery_note accordingly. If the delivery was succesful, we set the message as "sent" like before and continue to phase TWO. Phase TWO (provider to REST API) -------------------------------- In phase TWO, the message has been placed for delivery at our SMS Gateway provider. When the message has been processed and sent at their end, they will send us a POST request. We have added this into our Swagger definitions. If you want to limit the REST endpoint only to your provider, please see koha-httpd.conf where we will allow this endpoint to only certain IPs and block the rest. If the report says the message delivery was successful, we don't change anything. However, if the report says that the message delivery was failed, we will change the message status from "sent" to "failed" and add the reason of failure into delivery_note. Includes REST tests. Endpoints introduced in this patch: POST /api/v1/messages/{messagenumber}/report/labyrintti (for receiving the report)
Created attachment 42695 [details] [review] Bug 14767: SMS delivery notes from SMS Gateway provider's report
Created attachment 42805 [details] [review] Bug 14767: (follow-up) Use Unicode-parameter only when needed This patch makes Labyrintti driver use Unicode parameter only when required. In most cases in our local library we are fine with GSM 03.38. We will check if data is lost when comparing the decoded gsm0338 encoded message to the original message. Add it as optional feature in koha-conf - smsProviders - labyrintti - Unicode. To turn it on, set the value to "yes". For statistics, store the result in "metadata" field of message_queue if the message was sent as UTF-16. We also make a small fix to the response protocol since it is not in sync with what Labyrintti expects. Their delivery report wants a 200 OK response, not 201 or 204.
Blocked by Bug 14723.