SMS Gateway
HTTP Interface
Receiving unsubscription notifications via HTTP
Overview
When an end-user makes a request to unsubscribe themselves from a service we can inform partners of this using HTTP. This page details the format of the HTTP requests which are sent to allow the processing of unsubscription by external software systems.
Contents
- Sources of unsubscription notifications
- Enabling HTTP notifications for unsubscriptions
- Message format
- Response to the server
- Security considerations
Sources of unsubscription notifications
Unsubscription 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-shortcode 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 unsubscriptions
Normally, notifications of unsubscriptions 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.
Message format
Unsubscription notifications will take the form of an HTTP GET request to your server, using the parameters included in the table below:
| Parameter | Description |
| msisdn | The MSISDN being removed |
| shortcode | The short code(s) to remove this MSISDN from. There will be one parameter per short code |
| 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) |
When sending HTTP GETs 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).
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?Response to the server
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.
Security considerations
To ensure the authenticity of the HTTP requests you should only accept requests from the following MX Telecom IP addresses:
- 83.166.68.0/23 (ie 68.0 -> 69.255)
The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.
