Call us now on 01772217772

Getting started with the JSON API



Tagged with json, api, jsonapi
by Jonny Carter
in Uncat

24-Sep-2015 17:03



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

We have sample code for PHP

All transactions are made by sending a HTTP POST request with a JSON body to the TextGoto system, which will return an JSON 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/jsonapi.aspx

All inputs are configured in the following format:

{ "campaign":{ "header":{ "-uid":"[USERID]", "-pwd":"[PASSWORD]", "-action":"[FUNCTION]" }, "body":{ [REQUEST BODY PARAMETERS HERE] } } }

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:

{ "output":{ "msg":[An array of key values will be out put depending on the called function] } } If there is an error the output JSON will be formatted as follows { "output":{"error":[error description if an error has occurred]} }

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 "body" array of the input JSON. The output is always placed within the "{output:{"msg"}} part of the JSON output stream.

SEND_MSISDN

Sends an SMS message to one or more of MSISDNs.

INPUT

{ "campaign":{ "header":{ "-uid":"[USERID]", "-pwd":"[PASSWORD]", "-action":"SEND_MSISDN" }, "body": { "msisdn": [ "447771112222", "447123456789" ], "msg": "[MESSAGE]", "orig": "[ORIGINATOR]", "time": "[TIMESTAMP]" } } }

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

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.

OUTPUT

{"output":{"msg":[{"@msisdn":"447771112222","@response":"OK"}]}}

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

{ "campaign":{ "header":{ "-uid":"[USERID]", "-pwd":"[PASSWORD]", "-action":"VERIFICATION" }, "body": { "msisdn": [ "447771112222" ], "msg": "[MESSAGE]", "orig": "[ORIGINATOR]", "delay": "[SECONDS]" } } }

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

{"output":{"msg":{"@msisdn":"447771112222","@response":"OK","@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

{ "campaign":{ "header":{ "-uid":"[USERID]", "-pwd":"[PASSWORD]", "-action":"STOP_MSISDNS" }, "body": { "msisdn": [ "447771112222", "447123456789" ] } } }

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

GET_BALANCE

INPUT

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

{ "campaign":{ "header":{ "-uid":"[USERID]", "-pwd":"[PASSWORD]", "-action":"CHECK_BALANCE" } } }

OUPUT

The balance will be output as an attributes of the output node as shown below.

{"output":{"@balance":"21.461","@available":"31.461"}}

HLR

INPUT

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

{ "campaign": { "header": { "-uid": "[UID]", "-pwd": "[PASSWORD]", "-action": "HLR" }, "body": { "number": [ "447123456789" ] } } }

OUPUT

The output will be formatted as shown in the example below

{ "output": { "hlr": { "number": "447123456789", "country": "United Kingdom", "orig_network": "T-Mobile UK (Everything Everywhere Limited)", "ported_network": "T-Mobile UK (Everything Everywhere Limited)", "roaming_country": "United Kingdom", "roaming_network": "T-Mobile UK (Everything Everywhere Limited)", "ported": "false", "roaming": "false", "error_code": "DELIVRD", "is_perm_err": "0" } } }

APPEND_LIST

INPUT

Adds a number to a list that you specify, if the list doesn't exist it will be created

{ "campaign": { "header": { "-uid": "[UID]", "-pwd": "[PASSWORD]", "-action": "APPEND_LIST" }, "body": { "list": "[LISTNAME]", "phone": "[PHONE]" ] } } }

OUPUT

The output will be formatted as shown in the example below

{ "output":"NUMBER_ADDED" }