Gateway HTTP XML
Our Gateway can be used to deploy any mobile billing or messaging related services, including SMS based campaigns into your new or existing RESTful platform. Our SMS Gateway enables businesses to facilitate SMS messaging (traffic) between themselves and their mobile subscribers.
The aim of this article is to guide you through the integration of our Gateway with your own platform. If you have developed RESTful services before, you should find this document relatively easy to follow. If you have any questions that are not covered by this API Wiki or in the FAQ's please contact our dedicated Client Support and Development site.
Any country connection problems or interruptions to txtNation services will be announced in our announcements forums found here: Please login to / create your Zendesk account and subscribe to these updates now, they will be very important for your services. If you are a temporary developer on a project, please advise your employer to do the same. Scheduled maintenance periods can also be subscribed to here.
To make this process easier, you will need:
- Good programming knowledge to create a script that can respond to POST requests.
- The Gateway module enabled on your account.
- To restrict access to the script from only the txtNation server IP.
- To set up your Control Panel to POST to your script URL via Control Panel
- Checklist for implementation.
- A simple to follow step by step guide.
- Useful URLs
- SSL URL to Post Messages at: https://client.txtnation.com/gateway.php
- URL to Post Messages at: http://client.txtnation.com/gateway.php
- Control Panel URL: http://cp.txtnation.com/
- Gateway Variables Post Tester: http://client.txtnation.com/client_scripts/mbill/tester/form.html
- Support and Development: http://sd.txtnation.com/
- Knowledge Base: http://sd.txtnation.com/clients/knowledge_base/
- Network XML feed: http://xml.txtnation.com/versions/2.0/networks.xml
- Handling Retries: http://clients.txtnation.com/entries/252390-uk-premium-sms-retry-and-failure-messages-with-sms-billing-in-the-uk-and-worldwide
- Handling STOP requests: http://clients.txtnation.com/entries/21277441-all-products-stop-request-stop-list
- PSMS Retry Fees: https://clients.txtnation.com/entries/252390-UK-Premium-SMS-Retry-and-Failure-messages-with-SMS-Billing-in-the-UK
- Other useful information:
- Encrypted Key (E-Key) Location: Within CP, under "Gateway > Two Way > SMS (HTTP)"
- Max length of SMS header (title/sender ID): 11 characters
- Payout Information: Please contact your account manager
- Billing Types: (Details here)
- MT : Mobile Terminating.
- MO : Mobile Originating.
- IO : One in, One out. Can be MO or MT billed, but requires both an inbound and outbound message for each transaction.
- NO : No outgoing.
- LC : Limited charging. One billed MT per transaction.
- DO : Double opt-in : Initial request cannot be billed until end user has agreed by SMS.
- DC : Double Charged : Billed on both the MO and MT message.
- Common Gateway Error Codes: (Extended list here)
- 101 : Duplicate post back for message ID.
- 102 : Binary transaction requested, but no UDH specified.
- 103 : An invalid E-Key / company code has been posted to us (These are case sensitive).
- 104 : Invalid details. Please check and try again, check the "id" you submitted matches the one posted to you for the request.
- 415 : Invalid company code sent. Please check the cc variable (Case sensitive).
- BARRED : MSISDN has sent a STOP request or is blacklisted.
- NO CREDITS : Please speak to your account manager to purchase credits.
Uses of Gateway - One Way
Gateway can be used in one direction to exclusively send or just to receive messages in the following ways:
- Gateway can be used to receive messages from your users without sending a reply. e.g. Long Codes, Global Long Codes, Virtual SIM's.
- Gateway can send free individual messages to a users phone via pre-paid credits.
- Gateway can be used to send Bulk SMS broadcasts to all of your clients.
- Gateway can be used to send WAP-PUSH requests to your users phones.
- Gateway can be used to initiate binary requests to your users phones.
- Gateway can be used to send USSD or flash messages to your users phones. See the USSD Notifications section if you want to use this feature.
Uses of Gateway - Two Way
Gateway can be used to send and receive SMS messages in an asynchronous fashion:
- Gateway can be used to send and receive Premium SMS messages to users phones. e.g. Short Codes.
MSISDN Forwarding (WAP Billing)
- Gateway can be used to capture mobile numbers (MSISDN Capture) where a user is on a mobile web (wap) site, available for selected operators only. Also may be referred to as Header Enrichment.
Uses of Gateway - Direct Billing (DOB)
Gateway can be set up to enable Direct Operator Billing:
Direct Operator Billing
- The Gateway API allows Direct Operator Billing in territories with this billing mechanism available.
Note: There is an approval process that you will need to complete in order to have this billing type enabled for your account. For more information please visit our DOB Approval Process FAQ and for activation, contact your account manager.
- Payforit enables Direct Operator Billing in the UK.
Note: Payforit has it's own API. Please see our Payforit API.
- WyWallet enables Direct Operator Billing in Sweden.
Firstly, you will need to log into our secure Two-way SMS (HTTP) section of the Control Panel. This page contains some important information regarding your account.
Location of your MO receiver
Enter the full URL (e.g. http://yourdomain.com/scripts/responder.php) of the file on your server which will process the POST requests from our server.
Your ekey (encrypted key)
Please make a note of your ekey. This will be used to authenticate you when you reply to our messages. It can be found in your CP (CONTROL PANEL) (( https://secure.txtnation.com/index.php?module=515&page=0 )) Step 4 - Your Encrypted Key
It is case sensitive
Location of your delivery report receiver
In supported countries you will receive delivery reports for all messages you send. If you do not specify a receiver, we will not send any delivery reports.
Our Network XML Feed
To find out the shortcodes and keywords you can promote in each country, try our Networks XML feed.
Details of the XML content is documented here Network XML Feed explained
POST Variables - txtNation to You [SMS (MO) Message]
Below are the POST variables we will send to you when we receive a text message:
|id||The unique message ID|
|number||The originating telephone number (MSISDN)
Full International form without leading zeros or + sign.
|network||The originating network|
|message||The contents of the message|
|shortcode||The incoming short code of the message (if available)|
|country||The 2 digit FIPS country code (e.g. UK, US, ES)|
|billing||The network billing type (if available)|
Additional POST Variable Information
txtNation will post to you a unique id for every request to your script. It is important to store this value as it is used later to reply to the incoming message.
All mobile networks are assigned a unique network identification string by txtNation. Each incoming message we post to you will contain this network id. As with the id, this value must be used in the reply to us when attempting to charge the end user.
The contents of a user’s message is formatted and sent to you in the following way:
For example: &message=buy+song+23432
Note: All inbound characters will be posted to you in lower case, if you require the casing intact please contact our support team.
For a full list of all countries please follow this link: ISO's focal point for country codes
Refer to Premium SMS - billing types.
POST Variables - You to txtNation [SMS(MT) Message]
Whether you are sending a direct reply to an incoming message, a scheduled subscription message or a free advertising message, the below variable set should be used.
|reply||1 or 0|
|id||The unique message number ( int 11 )|
|number||The telephone number (MSISDN) you are sending the message to.
Full Internatonal form without leading zeros or + sign. ( varchar 32 )
|network||The originating network ( varchar 34 )|
|message||The contents of the message|
|cc||Your brand/company code (Case sensitive) ( varchar 35 )|
|currency||The local currency you are billing in( varchar 3 )|
|value||The cost of the message you are sending ( decimal 9,2 )|
|ekey||Your encrypted key (Case sensitive)|
|title||The sender id/from field ( varchar 11 )|
** txtNation Server Response **
When your correctly formatted posts hit our server we will respond with “SUCCESS”. This simply means the gateway will attempt to deliver your message, it does not indicate a successful delivery. It is strongly recommended that you store all txtNation responses to help debug any errors, and to improve your ability to audit your traffic.
Additional POST Variable Information
If set to “1” you are telling txtNation the post is in reply to a specific message "id". This will pair the incoming message and your reply together in the txtNation control panel statistics, and in some countries a linked transaction is required to complete the billing. If your service involves only a single reply per request it is advised that you use this variable. Only one reply can be sent per unique message "id".
Used in conjunction with the reply variable you should set this as the "id" variable posted to you by txtNation for message you are replying to. If "reply" has not been set then you are free to assign the message id yourself. This same id will be posted back to you in the delivery report. Max length 11, characters (numeric).
The originating telephone number (MSISDN) Full International form without leading zeros or + sign. ** Note For some countries e.g. France, this may be an alias for the real MSISDN, and may have a preceding non numeric character e.g. #288166360171234 . You should reply to the alias including any non numeric prefix.
This must be the same "network" variable we posted to you for the number. If the message you are sending is non-billed you must use “international”. If this fails it could mean the territory you are trying to deliver to has special requirements and you should contact support (for example USA).
Your message body can be up to 160 characters and contained within the GSM character set. For best results please ensure your message is URL encoded UTF-8. For special character sending requirements please contact our support team. All inbound characters will be posted to you in lower case, if you require the casing intact please contact our support team.
Your company code must be passed across in each message you send. If you are unsure of what this is simply login to the control panel and look in the top right hand corner. Your company code is displayed next to your username. (Case sensitive)
The currency variable must be passed as the local currency of the country you are billing in, for example if you send "currency=usd&value=2.99" you will charge the user $2.99. You may only bill intervals of the tariffs we have available in each country, please refer to networks XML feed for a list of those tariffs (http://xml.txtnation.com/xml).
Please note if the currency you pass does not match that of the country you are attempting to send an SMS our system will bill the closest tariff available. It is recommended that you pay close attention to our supported tariffs if you are billing in multiple countries. This uses the ISO currency code list.
This is the amount you wish to charge the user and is used in conjunction with the currency variable to define a charge price for an SMS. This value must be equal to an available tariff in the country you are sending the SMS.
This is your encrypted key as found on the Gateway module in the control panel. (Case sensitive)
If the message is free you may set who the message will appear to have come from. This field can be up to 11 characters in length. Billed messages are by default from the billing short code, and can not be changed using this field.
Optional POST Variable Information
We also support a number of different types of message. Please see below for details.
To send out a WAP Push message, you’ll need to include a variable named "wappush", which will need to have a value of 1. The URL of the content needs to be included within the message variable.
To send a binary message to your users, there needs to be a "binary" variable, which must be set to 1. As well as this, it is imperative that the UDH (User Data Header - below) is set to the hexadecimal value of what you wish to post, no plain text is allowed in this instance. The message variable should also be binary data.
If you are sending a binary message, you may need to include a UDH value which can be achieved with this parameter.
For each message you send through our gateway we will attempt to post you a delivery report (for messages in countries which support delivery notifications). txtNation Gateway will attempt to deliver these notifications to the appropriate Delivery Report URL which you must define in the txtNation CP (Control Panel). either ( https://my.txtnation.com/api/gateway ) or ( https://oldcp.txtnation.com/index.php?module=515&page=0 )
The report will consist of the following variables:
|id||The unique message number|
|message_id||The unique message number|
|number||The originating telephone number|
|report||The delivery report text|
|reason_id||The unique message number|
Delivery Reports Explained
The key fields which you should be concerned with are id, number and report, these should bu used to update your own records concerning delivery status for each message.
Important point to note: Delivery notifications can arrive at your service in any order, so some logic should be built in to your service, to deal with the potential that a FINAL status report may be followed by an INTERIM status report.
The id in the report will match the original id of the sent message.
The destination telephone number to which the message was sent
This is text based and will contain the status of the sent message.
|Report||Description||Final status?||Retries possible?|
|DELIVERED||The transaction was completed successfully. If a billed message was sent then the end user was charged.||✔||✖|
|NO_CREDIT||Delivery of the message failed because the end user did not have sufficient credit to complete the transaction at this time.||✔||✔|
|FAILED||The transaction could not be completed.||✔||✔|
|VALIDITY_EXPIRED|| The message could not be delivered to the end user as the validity period expired.
An SMS message is stored temporarily in the SMS center / network operator if the recipient mobile phone is unavailable, e.g. off / out of reception / flight mode / any other reason that the phone can't be contacted.
Once deleted from the network's temporary store, the SMS message will no longer be available for dispatch to the recipient mobile phone (even if it becomes online).
Mobile networks only store text messages for a limited time as there is a limit to available space in which to store the messages.
|REJECTED||The transaction was rejected by the operator. You must not continue to send charges to the end user.||✔||✖|
|INVALID_MSISDN||The transaction could not be completed as the MSISDN was malformed or does not exist.||✔||✖|
|ACKNOWLEDGED||The transaction has been acknowledged for delivery by the operator. This is a transient state and may be succeeded by further reports. This status is categorised as "unconfirmed" in the Account Balance.||✖||✖|
|ACCEPTED||The transaction has been accepted by the operator and can be treated as DELIVERED. Although this is a transient state it may also be succeeded by further reports. This status is categorised as "confirmed" in the Account Balance.||✖||✖|
|UNKNOWN||The transaction could not be categorised as the operator or handset returned an undocumented status.||✖||✔|
|OPERATOR_ERROR||The transaction could not be completed as there was an error with the operator. Please contact our support team.||✔||✔|
The above status indicators are reflected in the (CP) Control Panel and can be viewed by navigating to http://cp.txtnation.com where you login to your account and then select `Statistics > Traffic Reports > Outgoing Responses` from the menu system.
This is explained in further detail in the Knowledgebase article : All Products / SMS Delivery Reports (CP) Control Panel
Retries (Retry Billing)
You can attempt to re-bill an MSISDN if the status of the delivery report is not billed. Some report status's must not be retried, they are marked as such in the descriptions above. Retries will only work for Premium SMS in MT available countries. Retry logic is always posted using the "reply=0" variable set. This means it doesn't matter if the original request was a "reply=1" to an inbound message, your retry will be counted as a new transaction. For reporting and separation purposes within your own system you may choose to append the ID with a character implying that this message is a retry, alternatively you could stick with the original ID for the message.
A great example of where this is useful would be the prepaid market. If you have a number of users that when billed returns a low credit error, your system can re-schedule the message for a later time when they may have topped up.
Here is an example post your server might use to reply to a users initial request for a service:
Now if the report for the above example returned "NO CREDIT", you might send a retry for it in a few days time which would look like this:
As retry logic 'allowed attempts' varies per country, please contact your account manager for rules regarding retry logic.
Please be aware that some networks charge a fee per retry when your failures rates cross a pre-defined threshold. Please see the following FAQ for more information:
You can attempt to re-bill an MSISDN at lower price points (where available) if the status of the delivery report is 'not billed' in the first instance. This will only work for Premium SMS in MT available countries and should stop when the mobile subscriber is billed at the desired lower tariff(s). The logic behind the message flow is exactly the same as Retry Billing, with the exception of the tariff that is used.
You are trying to bill a user in the UK £10 and in the first billing attempt receive "NO CREDIT". Your system now starts the Drop-Down billing process and retries in the following format:
Retry 1: £8 - Result: No Credit
Retry 2: £6 - Result: No Credit
Retry 3: £5 - Result: No Credit
Retry 4: £4 - Result: DELIVERED
You have now successfully billed a user that otherwise would have been a lost sale. If this reduction in billing amount can suit your service model, it's a highly recommended feature for your Gateway logic.
Please contact your account manager for rules regarding drop down billing or contact our Support Team for technical assistance.
Additional Setup Recommendations
You will notice when entering the URL for us to send your messages there is an option for our server to check you respond with "OK". With this set our server will mail you notifying of errors should we receive anything other than "OK" when a post is made. Whilst this option is only a recommendation, it proves useful if txtNation need to assist you setting up. With this in place we know if you are correctly receiving our messages.
Additional considerations (retries)
Our platform will try to the send you the message for up to 5 times, with increasing intervals between failed attempts.
The table below shows the decision making process for retrying the message. A Yes means the message will be retried, A No means it will not be retried.
|Situation||OK Check enabled||OK Check disabled|
|HTTP Code > 200||Yes||Yes|
|Server takes too long to reply||Yes||Yes|
|HTTP Code = 200, body != OK||Yes||No|
txtNation's Server IP Addresses
You can validate all posts you receive from our server by validating against the following IP list.
This is of course optional, but strongly recommended to prevent un-authorised requests. If you are unsure of what to do please contact our support team at http://sd.txtnation.com.
Implementation Examples & Testing
You can download a sample script from here.
Once downloaded please extract the file “responder.php”. You will need to edit the file to enter your account details and add any custom code (such as database inserts). Once done it will need to be uploaded to a server that supports .php. Its location can then be entered on the control panel and a test sent to it from a handset. If you require assistance with this please contact our support team at: http://sd.txtnation.com.
If you would like a sample bulk script you may download the following file:
Testing your service
Now your responder script is in place your probably going to want to send a few messages and tweak the replies. This can be done by sending the keyword you have requested upon setup to one of the shortcodes you have been assigned.
If you require testing from a country you have not purchased for your service, please first check http://xml.txtnation.com/xml to see if it is available and consult with the support team.
The text message you should send can consist of up to three sections.
PREFIX KEYWORD MESSAGE
If your targeted territory has a prefix it must be included before your assigned keyword, if not you may simply start your text message with the keyword. Prefixes can be found in the networks XML feed (http://xml.txtnation.com/xml). Please note prefixes will always be removed before the post is made to your server.
If you are unsure of the keyword you have been assigned please contact support at http://sd.txtnation.com, if you would like to add additional keywords please contact your account manager.
txtNation Server Response
When your correctly formatted posts hit our server we will respond with “SUCCESS”. This simply means the gateway will attempt to deliver your message, it does not indicate a successful delivery. It is recommended that you store all txtNation responses to help debug any errors.