Receiving unsubscribe notifications via HTTP
This page details the format of unsubscribe notifications sent by the SMS Gateway to your platform. These notifications identify when an end user should no longer be considered subscribed to your service. You can receive a unsubscribe notification via either email or an HTTP GET request sent by the SMS Gateway.
- Sources of unsubscription notifications
- Enabling HTTP notifications for unsubscriptions
- Message format
- Response to the SMS Gateway
- Security considerations
Sources of unsubscribe notifications
Unsubscribe notifications can be sent out whenever an end-user is removed from a partner's reverse-billing whitelist. End-users may be removed from whitelists for any of the following reasons:
- Number no longer active: if we receive confirmation that a user's number is no longer active on a particular network, it will be removed from all partners' whitelists.
- Sending "STOP" to a Shared Short Code. Because we are unable to determine which partner's service the STOP was intended for, we will remove the user's number from the shared Short Code whitelists of all partners who have MT accounts on the Shared Short Code.
- Call to our automated or staffed customer-care lines (particularly in the case of Shared Short Codes where the PhonePayPlus customer-care line is provided by MX Telecom).
Enabling HTTP notifications for unsubscribes
Normally, notifications of unsubscribes are sent via email; however, in order to facilitate automated processing of these notifications, they can also be sent via HTTP using the interface described below. To have this enabled, please contact us.
Unsubscribe notifications will take the form of an HTTP GET request to your server, using the parameters included in the table below:
|msisdn||The MSISDN being removed|
|shortcode||The short code to remove this MSISDN from.|
|date||Date and time of request in yyyy-MM-dd HH:mm:ss format|
|source||The source of the request (max length of 50 characters):|
IVR (call to automated removal service), STOP (MO STOP SMS sent in), UnknownSubscriber (user is no longer a valid subscriber on this network), UNKNOWN (other)
For example, a request to remove 447884436692 from 81111 and 82222 at 2005-08-29 19:12:45 triggered by a call to our IVR automated removal service:http://something.customer.com/test?
We will retry a request which fails after a timeout (currently 60 seconds). It is the partner's responsibility to filter duplicate requests—these might occur if for some reason we did not receive the HTTP response from a previous attempt within 60 secs (perhaps because the reply took longer than that or there was a network outage etc).
Response to the SMS Gateway
The system expects to receive a non-empty HTTP 200 response to the request. If a 200 response is not given within a timeout (currently 60 seconds) then the request will be retried.
To ensure the authenticity of the HTTP requests you should only accept requests from the following IP addresses:
- 22.214.171.124 - 126.96.36.199 (188.8.131.52/23)
- 184.108.40.206 - 220.127.116.11 (18.104.22.168/24)
- 22.214.171.124 - 126.96.36.199 (188.8.131.52/22)
The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.