Gateway HTTP XML

From txtNation Wiki
Jump to: navigation, search
txtNation Gateway logo

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.

IMPORTANT INFORMATION

Any country connection problems or interruptions to txtNation services will be announced in our Zendesk forum article 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.


Contents


Implementation

To make this process easier, you will need:

  1. Good programming knowledge to create a script that can respond to POST requests.
  2. The Gateway module enabled on your account.
  3. To restrict access to the script from only the txtNation server IP.
  4. To set up your Control Panel to POST to your script URL via Control Panel
  5. A simple to follow step by step guide.

Quick Reference


  • 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:

Inbound SMS

  • Gateway can be used to receive messages from your users without sending a reply. e.g. Long Codes, Global Long Codes, Virtual SIM's.

Non-Premium SMS

  • Gateway can send free individual messages to a users phone via pre-paid credits.

Bulk SMS

  • Gateway can be used to send Bulk SMS broadcasts to all of your clients.

WAP-Push Messages

  • Gateway can be used to send WAP-PUSH requests to your users phones.

Binary Messages

  • Gateway can be used to initiate binary requests to your users phones.

USSD Messages

  • 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:

Premium SMS

  • Gateway can be used to send and receive Premium SMS messages to users phones. e.g. Short Codes.

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
  • Payforit enables Direct Operator Billing in the UK.

Note: Payforit has it's own API. Please see our Payforit API.

WyWallet
  • WyWallet enables Direct Operator Billing in Sweden.


Getting Started

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 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:


Variable Contents
action mpush_ir_message
id The unique message ID
number The originating telephone number
network The originating network
message The contents of the message
shortcode The incoming short code of the message (if available)
country The 2 digit ISO country code (e.g. UK, US, ES)
billing The network billing type (if available)


Additional POST Variable Information

id

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.

network

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.

message

The contents of a user’s message is formatted and sent to you in the following way:


keyword message


For example: &message=buy+song+23432

country

For a full list of all countries please follow this link: ISO's focal point for country codes

billing

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.


Variable Contents
reply 1 or 0
id The unique message number
number The telephone number you are sending the message to.
network The originating network
message The contents of the message
cc Your brand/company code (Case sensitive)
currency The local currency you are billing in
value The cost of the message you are sending
ekey Your encrypted key (Case sensitive)
title The sender id/from field


Additional POST Variable Information

reply

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".

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.

network

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).

message

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.

cc

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)

currency

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.

value

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.

ekey

This is your encrypted key as found on the Gateway module in the control panel. (Case sensitive)

title

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.

wappush

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.

binary

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.

udh

If you are sending a binary message, you may need to include a UDH value which can be achieved with this parameter.

Delivery Reports

For each message you send through our gateway we will attempt to post you a delivery report (in supported countries). The report will consist of the following variables:


Variable Contents
action mp_report
id The unique message number
number The originating telephone number
report The delivery report text


Delivery Reports Explained

id

The id in the report will match the original id of the sent message.

report

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. ✔ ✔
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

Re-Billing

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.

Examples:
Here is an example post your server might use to reply to a users initial request for a service:

http://clients.txtnation.com/gateway.php?reply=1&id=123456&number=447777777777&network=ORANGEUK&value=1&currency=gbp&cc=your_company&ekey=your_ekey

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:

http://clients.txtnation.com/gateway.php?reply=0&id=R-123456&number=447777777777&network=ORANGEUK&value=1&currency=gbp&cc=your_company&ekey=your_ekey

As retry logic 'allowed attempts' varies per country, please contact your account manager for rules regarding retry logic.

Drop-Down Billing

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.

Example
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

"OK" Check

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.

Retry intervals
Attempt Interval
2 30 seconds
3 1800 seconds
4 3600 seconds
5 10800 seconds

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.

Reasons for retrying messages
Situation OK Check enabled OK Check disabled
HTTP Code > 200 Yes Yes
Network error 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.


67.23.27.65

72.32.41.114

72.32.41.115

74.54.223.228

74.54.223.230

174.143.237.218

174.143.239.166


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

Sample Script

You can download a sample script from here:


http://client.txtnation.com/client_scripts/mbill/responder.zip


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.

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.

Message Structure

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.

Retrieved from "http://wiki.txtnation.com/index.php?title=Gateway_HTTP_XML&oldid=1260"
Personal tools