Call us now on 01772 217800

Getting started with the XML API



Tagged with api, xml, xmlapi
by Jonny Carter
in Uncat

18-May-2015 11:13



The XML API allows you to access various functions of the system remotely for use in your own applications.

We have sample code for PHP, VB.NET and Java for Android

All transactions are made by sending a HTTP POST request with an XML body to the TextGoto system, which will return an XML string with the response data in, which you can then interpret as necessary.

The address for the HTTP POST request is: http://textgoto.com/api/xmlapi.aspx

All inputs are configured in the following format:

<campaign> <header uid="[userid]" pwd="[password]" action="[function]"/> <body> [request body XML] </body> </campaign>

The user ID and password are those of the user account will perform the action, or the account from which data will be extracted. The function describes the action that will be performed. The formatting of the output will depend on the called function, but will always be returned within the following framework:

<?xml version="1.0" encoding="utf-8"?> <output> [output data xml] <error> [error description if an error has occurred] </error> </output>

The functions available are as follows. Permissions to access each function are defined by a permission matrix, and if a call is made to a function you are not permitted to access you will receive a NOT_PERMITTED error. The input defined in each function should be placed within the <body> section of the input XML. The output is always placed within the <output> tags of the output stream.

SEND_MSISDN

Sends an SMS message to one or more of MSISDNs.

Silver, Gold and Platinum Tariffs only can add a timestamp with the <time> parameter to set a message to be released at a future date/time. This timestamp should be in the format yyyy-MM-dd HH:mm:ss

Accounts with permission to set originator/sender ID can set the originator on the messages with the <orig> parameter.

INPUT

<msg>[message body]</msg> <orig>[originator]</orig> <msisdn>[msisdn]</msisdn> <msisdn>[msisdn]</msisdn> <time>[yyyy-MM-dd hh:mm:ss]</time> <links>[comma separated link IDs]</links>

Note that all MSISDNs must be in international format (in UK, 447771111222).

The TIME and LINKS tags are both optional. If you set the timestamp, the message will be sent as soon as possible after that timestamp.

The LINKS tag allows you to generate and include your tracking links in the message. To do this, place a [LINK] tag in square brackets in each location you want to generate a link. The IDs of those links should then be placed in sequence inside the LINKS tag in the XML (comma separated) to match to each [LINK] merge tag in the message body. Be aware that the length of the links when generated may result in long messages! When using the LINKS tag, you can only send to one number per API call.

OUTPUT

<msg msisdn="[msisdn]" response="[response]" />

There are a number of possible general error outputs from this function:

  • MESSAGE_TOO_LONG
  • NO_MESSAGE
  • INSUFFICIENT_CREDITS
  • INVALID_MESSAGE
  • SITE_UNAVAILABLE

The possible responses per MSISDN are:

  • INVALID_MSISDN
  • MSISDN_FAILURE
  • SEND_FAILURE
  • UNKNOWN_ERROR
  • MSISDN_BLOCKED
  • OK

You will only be charged for an "OK" response.

VERIFICATION

Sends a Verification SMS message with a unique 6 digit code that you can use to verify the identity/mobile number of the recipient

The message body MUST include the [CODE] place holder in the position of the message that you wish the 6 digit code to be inserted, for example "Here is your verification code [CODE]" would be delivered to the recipient like so "Here is your verification code 012837". If no code place holder is present within your message body, you'll receive the following error "NO_CODE_PLACEHOLDER_PRESENT"

You can submit to only 1 recipient per request when using this function, if you submit more that 1 MSISDN you'll receive the following error "MSISDN_LIMIT(1)_EXCEEDED"

Verification messages are queued for delivery immediately, however if you require additional time for processing, you can specify a delay (in seconds) s shown in the example below.

INPUT

<msg>[message body]</msg> <orig>[originator]</orig> <msisdn>[msisdn]</msisdn> <delay>[seconds]</delay>

Note that all MSISDNs must be in international format (in UK, 447771111222).

OUTPUT

A successful output will be in the following format, providing you with the verification code for validation

<msg msisdn="[msisdn]" response="[response]" code="[code]"/>

There are a number of possible general error outputs from this function:

  • NO_CODE_PLACEHOLDER_PRESENT
  • MESSAGE_TOO_LONG
  • NO_MESSAGE
  • INSUFFICIENT_CREDITS
  • INVALID_MESSAGE
  • SITE_UNAVAILABLE

The possible responses are:

  • INVALID_MSISDN
  • MSISDN_FAILURE
  • SEND_FAILURE
  • UNKNOWN_ERROR
  • MSISDN_BLOCKED
  • OK

You will only be charged for an "OK" response.

STOP_MSISDNS

Flags supplied MSISDNs as Stopped, so they will not be sent any more SMS messages.

INPUT

<msisdn>[msisdn]</msisdn> <msisdn>[msisdn]</msisdn> <msisdn>[msisdn]</msisdn>

There is a limit of 100 MSISDNs per API call, if you exceed this you'll receive an error response of "TOO_MANY_MSISDNS".

EXTRACT_STOPS

Extracts a report of opt-outs received in the last x days, in either an XML or flat CSV format.

INPUT

<DAYS>0|1|2 ... 7</DAYS> <FORMAT>XML|TEXT</FORMAT>

The days refer to calendar days, so if you enter a value of 0 (which is the default) you will receive a report of stop requests since midnight. The maximum is 7 days.

GET_BALANCE

INPUT

Returns your balance in the response XML body, this function requires no body in the request so the complete XML string you need to post should look like this:

<campaign> <header uid='[USERNAME]' pwd='[PASSWORD]' action='CHECK_BALANCE'/> <body></body> </campaign>

OUPUT

The balance will be output as an attribute of the <output> tag as shown below.

<?xml version='1.0' encoding='utf-8'?> <output balance='19.996'></output>

HLR

INPUT

Returns HLR information of the specified number in the response XML body.

<campaign> <header uid='[USERNAME]' pwd='[PASSWORD]' action='HLR'/> <body> <number>07123456789</number> </body> </campaign>

OUPUT

The output will be formatted as shown in the example below

<?xml version="1.0" encoding="utf-8"?> <output> <hlr> <number>447123456789</number> <country>United Kingdom</country> <orig_network>T-Mobile UK (Everything Everywhere Limited)</orig_network> <ported_network>T-Mobile UK (Everything Everywhere Limited)</ported_network> <roaming_country>United Kingdom</roaming_country> <roaming_network>T-Mobile UK (Everything Everywhere Limited)</roaming_network> <ported>false</ported> <roaming>false</roaming> <error_code>DELIVRD</error_code> <is_perm_err>0</is_perm_err> </hlr> </output>

APPEND_LIST

INPUT

Adds a number to a named list. If the list doesn't exist, it will be created. Do not use to bulk add numbers to lists!

<campaign> <header uid='[USERNAME]' pwd='[PASSWORD]' action='APPEND_LIST'/> <body> <list>[LIST NAME]</list> <phone>[PHONE NUMBER]</phone> </body> </campaign>

OUPUT

A successful add will return the response NUMBER_ADDED, otherwise an error message will be returned.