Sending gateway returns response or status value of every message that system attempts to send to the contacts in the list, these responses/statuses offer valuable information with regard to the delivery of the message. Every gateway handles responses in its own way using its own terms for providing a response of sending attempt or delivery status of the message.
SMSPlus is a Multiple Gateway supported application that you can configure with multiple gateway APIs. Running a platform with multiple gateways requires a spontaneous way of response processing with an ability to show stable metrics to the clients using the platform for sending. Plus, gateway responses can turn out to be difficult to understand sometimes for the clients, i.e. Rejected_DND a response from Infobip referring to the rejection of the message due to the intended number is on Do Not Disturb Network.
For this purpose, we have devised a way out for the administrator to map a gateway returned response with appropriate “System Response”. System responses are the collection of SMS+ internally setup responses that can interpret the majority of possible responses gateways can return. In this article, we'll discuss response processing as a whole which includes System Responses as well as the Gateway Responses.
Let's start from System Responses
Main Navigation -> Setup -> Gateways -> System Responses
System Responses
Recent updates have adopted a more effective way of processing message responses that the existing gateway returns after trying to send a message to a contact. It empowers the administrator of the application with better control over the response processing. There are two separate sections that collectively work for appropriate response processing. The first section is “System Responses” and the responses listed on this page are separate from the responses that gateways would return.
As every gateway treats messages differently and returns peculiar responses relevant for its own gateway, therefore, SMS+has collected a set of responses that can interpret the responses different gateways are returning. These responses that SMS+has collected as system responses are better understandable for the clients and will later be used to map the Gateway Returned Responses. Here on this page, you manage the status of every response to mark the status of specific responses as Failed, Delivered, Pending, and Undefined. Subsequent in this article are the details of these statuses.
The following area discusses the information that appears in the rows of each column of the “System Responses” table.
ID
The rows of the first column show an identification number separate for every record in the table.
Response (Add New Response)
Rows under this column contain currently available system responses that will later be used to map the gateway returned responses. We have carefully collected all possible responses that you can use to map with the responses of gateways, to translate the gateway return response in a simple and easy to understand manner for the clients.
For example, Clickatell returns a response for the particular message which says “Message Queued” and for the same status Twilio returns a response referring it to as just “Queued”, you can map both these responses with one System Response like “Message Queued” for both the cases and can mark its status according to your preferences between Failed, Delivered or Pending.
Furthermore, if you want to add a new response, you can use "Add System Response" a button at the top right area of the title bar.
Status
It is showing your preference for the system response status to appear as failed, delivered, pending or undefined. To set/update one of these statues with the specific response, you will need to click on the “Edit” under the “Actions” column.
Following you can find more details about what does every status conveys about the message delivery? and how the system treats messages marked as one of these statuses?
Delivered- Select when a message with a specific response needs to appear as successfully “Delivered. So you will make the status of certain system responses as “Delivered”, and map such gateway responses with this system response that represents successful delivery of the message.
Pending- Message that isn’t being delivered to recipient yet and also can’t be considered as failed can be categorized/marked as pending, i.e. scheduled for Late Delivery.
Undefined- Undefined status is actually specific for the “Undefined” response appearing in the list of current system responses. By default, all gateway responses are mapped with this “Undefined” system response having “Undefined” status value, until you go and update the mapping option for every gateway return response according to your preferences. Newly recognized gateway responses also fall in the same category, and are automatically mapped with “Undefined” message response having “Undefined” status. . But if you think it appropriate status for some other response, you can go ahead with it also.
Failed- Take this option for such System Response that you later will map with certain gateway responses that aren’t being delivered/sent to the intended number due to some error. Within MumaraSMS, failures are further categorized into two types, momentary failure (Soft Bounced) and permanent failure (Hard Bounced) that are later discussed in this article.
Bounced- If the status of a certain System Response is “Failed” this column will show if it is considered to be marked as Hard Bounced or Soft Bounced. For the statuses other than Failed, this column will remain empty.
Edit
Under the actions column, there is a function available for you to click and edit certain system responses. On the Edit page, you can change and update the Message Status to consider a message with a specific response as "Delivered", "Failed", or "Pending".
Delete
Delete specific responses from the list.
Failed Message Response
You will notice that when you click to select the status as “Failed” for a system response to later map it with certain gateway returned responses that denote to some delivery error, a dropdown option “Bounced” will appear underneath with two possible choices for you to select one of the appropriate.
In some of the cases, the gateway may give an uncertain response about the message status, or some momentary error occurs. System response with Failed and Soft Bounce status is required to map with these types of momentary delivery failures returned by sending gateway. For future campaigns, the system doesn’t exclude contact flagged as Soft Bounced and attempts sending to such contacts.
Some gateway returned responses can be categorized as a permanent error with obvious delivery failures. So to manage these gateway responses with obvious delivery failure, you would need the right mapping message with an appropriate status together as Failed and Hard Bounced.
Hard would be the right type of bounce to be set for the contacts with such responses. I.e. if the response reveals that the number string isn’t correct and the reason for failure is incorrect number format, numbers with such permanent failures will be categorized as hard bounced. Contacts flagged as hard bounce will not be attempted again during future campaigns. If the failure reason is corrected by editing the contact’s number, the flag will automatically turn as blank for such contacts.
If you have gone through the passage above, you might have understood the way responses are processed within SMSPlus. Now you know what are the system responses and how you can add them, it is time to learn how you map the gateway returned responses with the system responses?
Admin Main Navigation -> Setup -> Gateway -> Gateway Responses
Filter by Gateway
Before we go on to discuss the mapping thing and columns of the table that appear upon clicking Gateway Responses, let’s first look at the option available at top of the table to filter the records in the table. The dropdown option carries the name of available gateway APIs that the application is configured with; you can select your preferred gateway name to populate its responses in the table below. Without the filter applied, the table will populate records belonging to all existing gateways, so for ease to manage the responses one by one, use the filter.
ID
Identification number of every record appearing in the table
Response
This is the response that the gateways return after the sending attempt. Every gateway has its distinctive way of informing you on the status of your message, and all of the gateways provide knowledgebase resources to help you build a better understanding of their message responses and statuses. So you exactly know what has happened to your message. Before we move on to the next columns and eventually reach to the mapping, we would suggest you go through from these knowledgebase resources of different gateways you have configured your system with, to learn what response refers to which delivery status, and what will be the most appropriate system response and status would be to map specific gateway response with.
Error Reason
If the response in the previous row is erroneous, the row will provide you a short reason why the error occurred, otherwise, this row will remain empty.
Actions
With some gateways, actions are suggested to fix the delivery issue. This also helps you understand the specific responses, types of error,s and its resolution to better map it with appropriate system response.
Description
Some more details about the error response
Status
How does the gateway treat the specific response, is it treated as Failed, Delivered, Pending, etc.
Gateway
The rows of this column are showing the gateway name for each response/message status/error response entry that appears in the rows before.
Mapping Options
The dropdown carries all available System Responses for you to map a gateway returned response with an appropriate value of system response. It is eventually the System Response that your clients see in the Statistics and Logs of their messages, and not the gateway returned response. Therefore mapping the gateway response with an appropriate system response is important for the system to smoothly work.
Let’s take an example to further elaborate on how it works. E.g. the system is configured with Infobip API for sending, and you are on the Gateway Responses page where all possible responses from Infobip are listed under the Response column. Let’s say the first response you need to deal with is “PENDING_ENROUTE” and you are not sure what it exactly means and with which System Response you need to map it with.
As mentioned earlier, the best way to develop a better understanding of specific gateway responses is by reading through their knowledgebase resource, where they discuss the details of Responses, Statuses, and Error Messages. Here are the direct links for you to reach a right section of the knowledgebase and collect insight about the Message Responses, Error Responses, and Message Statues.
https://www.twilio.com/docs/api/messaging/message#message-status-values
https://dev.infobip.com/docs/response-codes#section-general-status-codes
https://archive.clickatell.com/developers/api-docs/message-status-codes/
On the above-mentioned link of Infobip, you will find out that “PENDING_ENROUT” falls under General Status Code, and it is referring that the message has been processed and is sent to the mobile operator, so its final delivery to the recipient’s handset is yet to be confirmed by the operator. Now you are sure that the message is successfully through the gateway but the delivery to the handset is yet to be confirmed. It is easy for you now to select an appropriate mapping option for this response.
You may find a couple of suitable options in System Responses that you can select with the desired status, i.e. “Delivered to Network” with possibly a Pending status (Depending on Your Preference). Status values of System Responses are under the control of the administrator and the admin can select/update a suitable status for specific system response.
When SMSPlus is installed on a webserver for the first time, you'll get all the gateway responses mapped with "Undefined" system response having an "Undefined" status value, as a default behavior of the system. Unless you separately set every gateway response/error message/status with a suitable system response, your clients will see the delivery status of every message as “Undefined” and “Undefined” in the detailed message log.
Therefore, before starting your application for commercial purposes and providing sending accounts to your clients, or offering Send Message API for transactional messages. It is necessary to first properly map the Gateway Responses with suitable System Responses. Let’s examine the effects of mapping by considering the above-mentioned example, where you have mapped Infobip PENDING_ENROUT response with “Delivered to Network” system response that is set with “Pending” status.
When a client account sends a campaign and Infobip returns PENDING_ENROUT as a response after trying sending a message to a contact in the list, SMSPlus immediately looks for the system response with which PENDING_ENROUT is mapped. After locating the mapped response, the system shows “Delivered to Network” as a response in the message logs and the Status value as “Pending”. If you have considered the status of “Delivered to Network” as “Delivered” instead of keeping it “Pending”, the system will also update the counter of the “Delivered” message in the statistics and count messages with Delivered to Network response as Delivered.
Moreover, the system keeps the Message ID as a reference, and for the responses that the gateway posts an update, SMSPlus updates it with the relevant system response and status. Accurate response processing lies in your ability to understand the gateway responses well enough to be able to map it with right system response with appropriate status.