NAV
shell

Introduction

This API describes the method calls for all Fonix Messaging.

All Fonix HTTP APIs are organized around REST.

Connection

Calls to Fonix must be made through HTTPS.

Calls from Fonix to your servers can be made either through HTTPS or HTTP. When using HTTPS, your server certificate must be signed by a trusted certificate authority. We recommend all information transported over the web to be encryped, hence we recommend to use HTTPS.

All calls to and from Fonix are made through POST.

Interface
YOU <–{MO - HTTPS:POST or HTTP:POST}— FONIX
YOU ———{MT - HTTPS:POST}———> FONIX
YOU <–{DR - HTTPS:POST or HTTP:POST}— FONIX

Authentication

Authentication is made by providing the API key as a header in your request. The header name is X-API-KEY. Our support team will provide you with the key for you to use.

You can have multiple API keys active at any one time for multiple services with us. Your API keys carry many privileges, so be sure to keep them secret!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

All HTTP request to and from Fonix should be encoded in the default content type: application/x-www-form-urlencoded.

FONIX API Endpoint

#https://sonar.fonix.io/v2/
#NOTE: The underlying destination IP address for sonar.fonix.io changes over time.
#      Don't use fixed destination IPs with this domain.

#Example API Keys

# Test Key: test_BYZNk5YUBMLfowSOQTUuqq3t
# Live Key: live_WrxOqXQYwEPWVJDGgdfirZrk

#Example Request including the API key
curl -i https://sonar.fonix.io/v2/chargesms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=447111222333 \
 -d BODY=Welcome%20Home

Message Referencing

We support client-provided references for requests to us. This allows you to pass us up to 80 character of data in a field (REQUESTID) which we will provide back to you in the corresponding delivery report. More detail can be found in the parameters section under REQUESTID.

Example including requestid

curl -i https://sonar.fonix.io/v2/chargesms \
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
  -d ORIGINATOR=84988 \
  -d NUMBERS=447111222333 \
  -d BODY=This+MT+SMS+is+tagged \
  -d REQUESTID=F21B992Ex9257x936Ex3D2Fx7CDEB38F217C

Success and Errors

An API call sent by you to us in this version (V2) is successful if and only if you receive a 200 OK HTTP response code in return.

Any other values in the HTTP response code indicate a failure and the request was rejected. Please do not retry the same request, as it would fail again if unchanged.

If the parameters in your request fail validation, you receive a 400 Bad Request error in response. Please check the result code in the JSON response for details of the failure.

If the key used in your request is incorrect or unauthorised, you receive a 401 Unauthorized error in response.

If your service has a maximum quota of bulk messages configured you receive a failcode: MAX_QUOTA_REACHED after that quota has been reached.

HTTP CODE Description
200 OK - Everything worked as expected.
400 BAD_REQUEST - Check the response body for details.
403 NOT_AUTHORORIZED - No valid API key provided.
500 INTERNAL_SERVER_ERROR - An unexpected error occured at the FONIX platform

For all 400 BAD_REQUEST the failure reasons are included in the JSON response:

failcode Description
OUT_OF_RANGE A request parameter value can’t be accepted
IS_EMPTY A mandatory request parameter is empty
TOO_MANY_NUMBERS Too many numbers. Max 100
INVALID_NUMBER Number is incorretly formatted
TOO_MANY_CHARACTERS A request parameter is too long
INVALID_CHARACTERS A request parameter has invalid chars
MAX_QUOTA_REACHED Contact us to reset your quota

CHARGE SMS

Request

This Method call sends premium billed SMS messages to one or many phone numbers, charging the mobile phone account.

Charge SMS requests can never be concatenated. If the message body is too long, we will reject your request with "failcode": "TOO_MANY_CHARACTERS".

#CHARGE SMS request

curl -i https://sonar.fonix.io/v2/chargesms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=447111222333,447111222444 \
 -d BODY=Welcome%20Home

Response

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found and which encoding we used (gsm/ucs2). We now also tell you the consumer price of the premium shortcode you originated the message from.

#CHARGE SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2",
        "encoding": "gsm",
        "price": 50
    }
}


#CHARGE SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "TOO_MANY_CHARACTERS"
    }
}

MO SMS

Request

Mobile originated (MO) messages are sent to your web server in an HTTPS POST request. If the user sent a long message arriving at our gateway in multiple MO SMS messages, by default we aggregate all of the messages and then send you the whole long message in a single request. This behaviour can be disabled on dedicated shortcodes upon request.

# MO SMS HTTPS POST example (to your application)
#
# POST /path/mosms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BODY=This%20is%20a%20mobile%20originated%20test%20message&RECEIVETIME=20130202102030
# &GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&PRICE=15

Response

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200, we will retry to deliver the MO message to your platform, which may cause you to interpret the retries as duplicates. We will retry to deliver the message to you for up to 24 hours.

Your HTTP response codes Description
200 You have accepted the MO message
4xx, 5xx You have not accepted the MO message. Fonix retries

MO BINARY

Request

For those cases where users manage to text in binary MO messages, we have created a dedicated MO BINARY request. The behaviour of it is similar to the MO SMS request, but to make your life easier we can direct MO BINARY requests to a separate listener on your side. There you can chose to decode and process them or just accept and ignore them.

Binary MO messages are often created unintentionally through grey-import handsets which don’t originate SMS messages in the standard way.

#MO BINARY HTTPS POST example (to your application)
#
# POST /path/mobinary HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&MONUMBER=447111222333&OPERATOR=o2-uk&DESTINATION=84988
# &BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
# F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
# &BINHEADER=050415810000&RECEIVETIME=20130202102030&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Response

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200 OK, we will retry to deliver the MO message to your platform, which may cause you to interpret the retries as duplicates. We will retry to deliver the message to you for up to 24 hours.

Your HTTP response codes Description
200 You have accepted the MO message
4xx, 5xx You have not accepted the MO message. Fonix retries

DR SMS

Request

Delivery reports for previously submitted MT messages are sent in an HTTPS POST request to your web server. DRs indicate either successful delivery or delivery failure. If the delivery failed, details about the failure reason are provided in the STATUSCODE and STATUSTEXT.

Delivery reports are useful to identify if the recipient of a CHARGE SMS message was successfully charged. Note: All delivered CHARGE SMS messages always mean the user was charged. However, in some cases undelivered messages are still charged.

We now also include the PRICE parameter which holds the consumer price of the premium shortcode you originated the MT message from.

When we forward your SMS request to the mobile operator, it can occasionally happen that we don’t receive an acknowledgement back from them. Our policy is not to retry the request in those cases, because the message may have been sent to the recepient handset correctly. Instead, we create a failure delivery report back to you with STATUSCODE=OPERATOR_TIMEOUT.

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=o2-uk&MONUMBER=447111222333&DESTINATION=84988
# &STATUSCODE=DELIVERED&STATUSTEXT=Delivered&STATUSTIME=20130202102030
# &PRICE=50&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

Response

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200, we will retry to deliver the DR to your platform for up to 24 hours.

Your HTTP response codes Description
200 You have accepted the MO message.
4xx, 5xx You have not accepted the MO message. Fonix retries.

Parameters

The following parameters are in use throughout the API:

The mobile operator code can be prefixed, i.e. NUMBERS=eeora-uk.447123456789

To send the same MT SMS to multiple numbers you can separate them with commas: NUMBERS=447111122222,447333344444 The maximum number of mobile numbers allowed in a batch is 100.

#A sample message sent from 447987654321:
 curl -i https://sonar.fonix.io/v2/sendsms \
  -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
  -d ORIGINATOR=447987654321 \
  -d ORIGINATOR_TYPE=msisdn  \
  -d NUMBERS=447111222333 \
  -d BODY=Welcome%20Home

If you send us a new request with a previously used REQUESTID within seven days we will not process it again, but reply with the same information we used in our previous response. If you send us a request with a previously used REQUESTID after seven days, the message may be sent again, hence we recommend you should not retry requests for longer then seven days.

The REQUESTID will also be passed back to you in the matching DR.

Incoming parameters (MO and DR)

The following information parameters appear in MO SMS, MO STOP and DR SMS only:

All DR contain a status code. The following values are defined for this:

DR status codes Description
DELIVERED (MT message successfully delivered)
INSUFFICIENT_FUNDS (User didn’t have enough money)
INVALID_MSISDN (Mobile number not accepted by operator)
INVALID_OPERATOR_SERVICE (Request type not accepted by operator)
INVALID_ORIGINATOR (Originator not accepted by operator)
MAX_SPEND_MSISDN (Daily user spend limit exceeded)
OPERATOR_REJECTED (Request not accepted by operator)
OPERATOR_TIMEOUT (Request not acknowledged by operator)
PERMANENT_OPERATOR_ERROR (Request permanently failed by operator)
PERMANENTLY_BARRED (User is permanently barred from request type)
SMSC_ERROR (Operator SMSC encountered a processing error)
TEMPORARY_BARRED (User is temprorarely barred from request type)
TEMPORARY_OPERATOR_ERROR (Request temprorarely failed by operator)
UNKNOWN_MSISDN (Mobile number not known to operator)
UNREACHABLE_MSISDN (User mobile is switched off or absent)
UNROUTABLE (We can’t process the request due to a missing route)
UNKNOWN_ERROR (Something went wrong, - the request failed)

Adult Services must not be provided to users where the parameter is set to AV=not_verified, as in those cases the mobile operator has informed us specifically that this user is barred to receive such services.

Mobile Operator Codes

The following list of mobile operator codes are used in this API version (V2) and all future versions:

Operator Code Operator
three-uk Three UK
eeora-uk EE (Orange) UK
eetmo-uk EE (T-Mobile) UK
voda-uk Vodafone UK
o2-uk O2 UK
virgin-uk Virgin Media UK
unknown Operator unknown

unknown appears in cases where the MO message was sent to us via another operator or a bulk message was delivered to a user whos network we couldn’t identify.

Character Types

The following data types are in use throughout the API:

Character Encoding
£ %C2%A3
%E2%82%AC
space %20
? %3F
+ %2B
& %26
/ %2F
\ %5C
= %3D
# Examples
#
# ORIGINATOR=84588
#
# BODY=Test+message
#
# BODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204
#      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B61
#
# NUMBERS=447111222333
#
# RECEIVETIME=20130202102030
#
# IFVERSION=201001
#
# GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209

ADULT VERIFY

Introduction

Fonix allows clients the ability to look up the age verification status of a MSISDN. This call is used in order to validate a client is eligable to access age restricted content.

Asynchronous Request

We ACK your request and then send the result in a separate AV REPORT to you.

curl -i  https://sonar.fonix.io/v2/adultverify \
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t \
-d NUMBERS=eetmo-uk.447932111222 \
-d NETWORKRETRY=NO

Asynchronous Response

With the response we either acknowledge (ACK) or reject (NACK) your Adult Verify request. The following parameters are returned:

Ack: + txguid: the GUID from the original request + numbers: the quantity of numbers sent through in the original request

Nack: + parameter: which parameter failed the validation + failcode: why the vaidation failed

# ACK:
# {
#   "success": {
#       "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
#       "numbers": "1"
#   }
# }

# NACK:
# {
#   "failure": {
#       "parameter": "parameter name",
#       "failcode": "FAILCODE"
#   }
# }

Synchronous Request

The response to your request will include the AV status. If after 30 seconds we don’t get a response from the operator, we send a pending response to your call. If you want to collect AV stauses in this cases, we can configure your service so that for each request we’ll send both a synchronous and an asynchronous response.

curl -i  https://avsolo.fonix.io/v2/avsolo \
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t \
-d NUMBERS=eetmo-uk.447932111222 \
-d NETWORKRETRY=NO

Synchronous Response

With the response we either acknowledge (ACK) or reject (NACK) your Adult Verify request. The following parameters are returned:

Ack (can be verified, not_verified, unknown or pending): + ifversion: API version + operator: mobile operator code of the operator from which we received the status information + guid: the GUID from the original request

Nack: + parameter: which parameter failed the validation + failcode: why the vaidation failed

# ACK:
# {"verified":{
#       "ifversion":"201001",
#       "operator":"o2-uk",
#       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
#   }
# }

# {"not_verified":{
#       "ifversion":"201001",
#       "operator":"o2-uk",
#       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
#   }
# }

# {"unknown":{
#       "ifversion":"201001",
#       "operator":"o2-uk",
#       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
#   }
# }

# {"pending":{
#       "ifversion":"201001",
#       "operator":"o2-uk",
#       "guid":"f2e84610-534a-4e02-bfad-9ccbaa14e09a"
#   }
# }

# NACK:
# {
#   "failure": {
#       "parameter": "parameter name",
#       "failcode": "FAILCODE"
#   }
# }

AV REPORT

Request

AV Reports for previously submitted Adult Verify requests are sent in an HTTPS POST request to your web server. They indicate whether the numbers you submitted were registered with the mobile operator as adult verified or not.


# AV REPORT HTTPS POST example (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# eetmo-uk.447932111222
#
# IFVERSION=201001&OPERATOR=eetmo-uk&MONUMBER=447932111222&GUID=7CDEB38F-4370-18FD-D7CE-329F21B99209&AV=VERIFIED

Response

Your HTTP response code back to us should be: 200 OK

If you don’t respond with a 200 OK, we will retry to deliver the Charge Report to your platform for up to 24 hours.

SENDSMS

Request

This Method call sends SMS messages to one or many phone numbers without charging the mobile phone account.

Typically you can fit 160 characters into the body of a single message. If your body is longer then we will spread and transport it across multiple SMS in a concatenated message.

Some special characters do take twice the space then others (see GSM for more information). If the body of your message contains non GSM characters, we will encode the entire message in UCS-2 before transmitting to the operator unless you force the encoding to use in the ENCODING parameter. If you want to check if your message body fits into a single SMS message, you could submit a DUMMY request first and look out for the response containing the smsparts parameter.

curl -i https://sonar.fonix.io/v2/sendsms \
 -H X-API-KEY:live_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=447111222333 \
 -d BODY=Welcome%20Home
 -d DUMMY=yes

Response

The response body is structured follwoing JSON.

If your request was successfully accepted by us, you’ll soon get a success response from us wich will contain our GUID reference "txguid" of your request, how many unique mobile phone "numbers" we found (Duplicate phone numbers in the same request are de-duped), how many "smsparts" your message was split over and which "encoding" we used (gsm/ucs2).

If your request failed due to an empty or incorrect parameter, we tell you which "parameter" had the issue and the "failcode" of the error. For more information about potential errors, please check the Errors section.

#SEND SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1"
        "smsparts": "1"
        "encoding": "gsm"
    }
}


#SEND SMS response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

SEND BINARY SMS

Request

To send a single or multi-part binary message to a handest the message has to be encoded in a particular way. We do this for you with this call. Depending on the length of the data, the binary message will be spread and transported across multiple SMS messages. Binary SMS messages don’t charge the mobile phone account.

#SEND BINARY SMS request

curl -i https://sonar.fonix.io/v2/sendbinsms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=447111222333,447111222444 \
 -d BINBODY=C024A3A5905E195B081180800991C6106DA620420620A22C4986166184289B526204 \
      F20620A28C26C49B6186289B0C3126205A04205A04D86D8608410A2D026C22C49B615905E1 \
      95B081180800991C6106DA62042028C26C49B6186289B0E195B0811808009928C26C4910A2 \
 -d BINHEADER=050415810000

Response

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found.

We also tell you how many SMS parts your message was split over.

#SEND BINARY SMS response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "2"
        "smsparts" "2"
    }
}


#SEND BINARY SMS response (failure)
{
    "failure": {
        "parameter": "originator",
        "failcode": "INVALID_CHARACTERS"
    }
}

SEND WAP PUSH

Request

To send a WAP push message to a handest the message has to be encoded in a particular way. We do this for you with this call. Depending on the length of the information in the link, the WAP push message will be spread and transported across multiple SMS messages. WAP push messages don’t charge the mobile phone account.

#SEND WAP PUSH request

curl -i https://sonar.fonix.io/v2/sendwappush \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=447111222333,447111222444 \
 -d PUSHTITLE=Welcome%20Home \
 -d PUSHLINK=http://www.google.com

Response

Duplicate phone numbers in the same request are de-duped and in the response we inform you how many unique mobile phone numbers we found.

We also tell you how many SMS parts your message was split over.

SEND WAP PUSH response (success)
{
    "success": {
        "txguid": "7CDEB38F-4370-18FD-D7CE-329F21B99209",
        "numbers": "1"
        "smsparts" "1"
    }
}


SEND WAP PUSH response (failure)
{
    "failure": {
        "parameter": "body",
        "failcode": "IS_EMPTY"
    }
}

Example Messages

MT billed example

A billed text message to two O2 numbers 447111222333 and 447111222444, with the body text of “Welcome Home” originating from 84988.


curl -i https://sonar.fonix.io/v2/chargesms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d NUMBERS=447111222333,447111222444 \
 -d BODY=Welcome%20Home \
 -d ORIGINATOR=84988

Binary MT example

A free text message to 447111222333 containing binary content and originating from HELLO.

curl -i https://sonar.fonix.io/v2/binarysms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d REQUESTTYPE=5 \
 -d NUMBERS=447111222333 \
 -d BINHEADER=050415810000 \
 -d BINBODY=024A3A5905E195[...]361B6182000 \
 -d ORIGINATOR=HELLO

Concatenated MT example

A free text message to 447111222333 with a poem of 242 characters and originating from POETRY. The message will be transmitted through two separate MT SMS messages and then re-assembled on the handset.

curl -i https://sonar.fonix.io/v2/sendsms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d REQUESTTYPE=19 \
 -d NUMBERS=447111222333 \
 -d BODY=Why+were+you+born+when+the+snow+was+falling%3F+ \
 You+should+have+come+to+the+cuckoo%27s+calling+Or+when+ \
 grapes+are+green+in+the+cluster%2C+Or%2C+at+least%2C+ \
 when+lithe+swallows+muster+For+their+far+off+flying+ \
 From+summer+dying.+%28Christina+Rossetti%2C+1865%29 \
 -d ORIGINATOR=POETRY

OPERATOR LOOKUP

Request

The HLR/Operator lookup call provides the network and country for a particular MSISND submitted. This call has international coverage and will take the MSISDN for all major mobile networks in all countries.

By submitting a MSISDN this function will return the associated country and operator for the specified MSISDN.

The method call is synchronous, i.e. we directly reply with the requested information to you in the HTTP response.


# Example API Request including the API key
  curl -i  http://sonar.fonix.io/v2/operator_lookup?NUMBER=447932111222 \
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

Response

The HTTP response provides the following information to the user:


#   {
#   "success":
#       {"mcc":"234",
#         "mnc":"15",
#         "operator":"voda-uk"}
#   }

Parameters

The following parameters are in use throughout the API:

# Example ENCRYPTEDMSISDN:
#   pcRBEbPss0xfscq6XLoWNA8ULssQL4UuM9eGdSkmGdcfUO%2Fu0koOav04GPDxb0yjAufzOyMuvi98JFCEMiHw3vkvIyFVmMpNciKWLLU9k1U%3D

SMPP API

Introduction

The Fonix SMPP API is closely aligned with the Short Message Peer to Peer Protocol Specification v3.4 (SMPP). We only made a few modifications to enrich the information we exchange with your platform.

Connection

In SMPP connections are made by your client to our server for both sending MT messages and picking up MO and DR messages.

SMPP is transported via TCP and Fonix uses the following ports to connect:

We support TRANSMITTER, RECEIVER and TRANSCEIVER binds. We can provide you with multiple sessions (binds) for your connection.

Authentication

Authentication in SMPP is made through custom credentials which we provide to you separately.

Versioning

We only support SMPP V3.4 (Document Version:- 12-Oct-1999 Issue 1.2)

Flow Control

The SMPP protocol is very efficient in data transport and also supports asynchronous transport where multiple requests can be issued without waiting. Requests are acknowledged in a skew order by the other end. The number of unacknowledged requests is called a window and the maximum size set by the sending party is called window size.

We support a receiving window size for MT messages of 100. Any unacknowledged requests above this level will be rejected with the RTHROTTLED error code.

Our default sending window size for MO and DR messages is 30, but can be configured to suit your needs.

Custom TLV parameters

To transport additional information not covered in the standard scope of SMPP we utilise custom defined Tag Length Value (TLV) parameters. Currently the following parameters are defined

TLV Tag Used in Description
0x1600 MO, MT and DR connection, the mobile operator code identifying the network of the mobile user
0x1620 MO sonar_guid, the unique identifier assigned by us for this message
0x1630 MO av, an optional identifier for adult verification
0x1640 MO and DR price, the consumer price in pence

NOTE: The message GUID assigned by Fonix is transported in different tags to you for different message types:

NOTE: The TLV paramters should be formated as c-var-octet strings and be null terminated. For example the TLV to tell us that your MT message should go to Vodafone would be 16000008766f64612d756b00.

NOTE: Please don’t send the sonar_guid, av or price tags to us in your MT request. We just ignore those values in message processing.


# Example c-var-octet strings for the operator TLV field:
#   1600000974687265652d756b00   = three-uk
#   160000096565746d6f2d756b00   = eetmo-uk
#   1600000965656f72612d756b00   = eeora-uk
#   16000008766f64612d756b00     = voda-uk 
#   160000066f322d756b00         = o2-uk 
#   1600000a76697267696e2d756b00 = virgin-uk

Sending Premium and Bulk SMS

Our API accepts both bulk and premium SMS through the same connection. MT Premium and MT Bulk are distinguished through the TON and NPI properties of the originator. Setting the right TON and NPI is very important to avoid unintentionally billing or not billing a user.

Here are the settings to use:

Type of Originator TON NPI
Shortcode (PSMS) 3 9
Alphanumeric (Bulk) 5 0
MSISDN (Bulk) 1 1

To send a premium message, the originator can only ever be a shortcode. To send a bulk message, the originator can be any string of alphanumeric characters or a fully formatted phone number.

# Extract for premium SMS:
#   {source_addr,"84988"}
#   {source_addr_ton,3},
#   {source_addr_npi,9},

# Extract for bulk SMS:
#   {source_addr,"Fonix"}
#   {source_addr_ton,5},
#   {source_addr_npi,0},

# Extract for bulk SMS from MSISDN:
#   {source_addr,"447987654321"}
#   {source_addr_ton,1},
#   {source_addr_npi,1},

Sending parameters (MT)

Here is some guidance on the specific use of SMPP parameters to compose your MT messages:


#SUBMIT_SM MT message example:
#  [{short_message,"hello world"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,1},
#  {validity_period,""},
#  {schedule_delivery_time,""},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"447111222333"},
#  {dest_addr_npi,1},
#  {dest_addr_ton,1},
#  {source_addr,"12345"},
#  {source_addr_npi,0},
#  {source_addr_ton,5},
#  {service_type,""}]

Incoming parameters (MO and DR)

The short_message parameter of MO messages is encoded in UTF-8 or (very rarely) in UTF-16 depending on how we receive the message from the handset. MO messages with Binary encoding are discarded.

Concatenated (long) MO messages can be assembled by Fonix and then transmitted as one long message using the message_payload parameter (you need to let us know to enable this). If the message_payload parameter is used, then the short_message parameter will be empty (sm_length=0).

Please also note the custom TLV parameters included in MO messages.

If you receive MO messages on adult shortcodes (69xxx, 79xxx or 89xxx) then we may tell you whether the user is allowed to receive adult services or not with these values: {av,"verified"} or {av,"not_verified"} or {av,"unknown"}.


#DELIVER_SM MO message example:
#  [{short_message,"Hello"},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"e9e26d88-029d-4464-a5fa-b221e71a7159"},
#  {connection,"o2-uk"}]

#DELIVER_SM Concatenated (long) MO message example (if enabled):
#  [{short_message,[]},
#  {sm_default_msg_id,0},
#  {data_coding,0},
#  {replace_if_present_flag,0},
#  {registered_delivery,0},
#  {validity_period,[]},
#  {schedule_delivery_time,[]},
#  {priority_flag,0},
#  {protocol_id,0},
#  {esm_class,0},
#  {destination_addr,"71234"},
#  {dest_addr_npi,9},
#  {dest_addr_ton,3},
#  {source_addr,"447111222333"},
#  {source_addr_npi,1},
#  {source_addr_ton,1},
#  {service_type,[]},
#  {sonar_guid,"0e1d4e59-7915-4ebf-852c-12d1b71db974"},
#  {connection,"o2-uk"},
#  {message_payload,"Why were you born when the snow was falling? 
#  You should have come to the cuckoo's calling, 
#  Or when grapes are green in the cluster, 
#  Or, at least, when lithe swallows muster 
#  For their far off flying From summer dying."}]

The short_message parameter of DR messages is always encoded in UTF-8 and contains the following structure:

id:GUID sub:001 dlvrd:001 submit date:YYMMDDhhmm done date:YYMMDDhhmm stat:STATUS err:ERR text:TEXT

The corresponding MT message is successfully delivered only if stat:DELIVRD


#DELIVER_SM DR message example:
#  [{short_message,"id:5822fcc6-6da6-4107-90da-33f00cefa12d sub:001
#  dlvrd:001 submit date: 1403181055 done date:1403181055 stat:DELIVRD
#  err:000 text:hello world"},
#  {data_coding,0},
#  {esm_class,4},
#  {source_addr_ton,1},
#  {source_addr_npi,1},
#  {source_addr,"447111222333"},
#  {destination_addr,"12345"},
#  {dest_addr_npi,0},
#  {dest_addr_ton,5},
#  {protocol_id,0},
#  {service_type,""},
#  {priority_flag,0},
#  {schedule_delivery_time,""},
#  {replace_if_present,0},
#  {sm_default_message_id,0},
#  {validity_period,""},
#  {receipted_message_id,"5822fcc6-6da6-4107-90da-33f00cefa12d"},
#  {connection,"o2-uk"}]

Increasingly consumers send MO messages longer then 160 chracters, which are then concatenated by the handset and sent in message parts to our gateway. At Fonix, we have developed a mechanism to aggregate all message parts and send them to you in one long MO message we originate

We concatenate a maximum of 20 message parts into one long MO message.

Mobile Operator Codes

The following list of values are used in the connection parameter:

Operator Code Operator
three-uk Three UK
eeora-uk EE (Orange) UK
eetmo-uk EE (T-Mobile) UK
voda-uk Vodafone UK
o2-uk O2 UK
virgin-uk Virgin Media UK
UNKNOWN Operator unknown

APPENDIX A

Every requests supports a DUMMY parameter that allows you to send test requests to our system. If you send requests with a TEST API Key (i.e. an API key starting with test_) then you can omit the DUMMY parameter but your requests will still be handled as DUMMY.

DUMMY requests are not forwarded to the Mobile Operators.

DUMMY requests allow you to test our interface. We advise to do full end to end tests before creating a new live service.

The response sent to a DUMMY request depends on the MSISDN you submit in the request. Below you can find more details for each type of request together with related examples.

In each type of request OPERATOR will be set basing on the first 4 digit of the MSISDN according to the following table:

Msisdn Prefix Operator Code
4400 o2-uk
4401 voda-uk
4402 eetmo-uk
4403 eeora-uk
4404 virgin-uk
4405 three-uk

For any other msisdn prefix it will be set basing on a number ranges lookup.

DUMMY SMS Requests & WAP PUSH

# SEND SMS request
curl -i https://sonar.fonix.io/v2/sendsms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=440200000001 \
 -d BODY=Welcome%20Home

# SEND SMS response
# {"success":{"txguid":"0ec3c023-21fb-4d2c-a942-18e1ab17815a",
#  "numbers":"1","smsparts":"1","encoding":"gsm"}}


# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000001
# &DESTINATION=84988&STATUSTIME=20160301114836&STATUSTEXT=OK
# &STATUSCODE=DELIVERED&CHARGESTATUS=false
# &GUID=0ec3c023-21fb-4d2c-a942-18e1ab17815a&PRICE=10&DURATION=0

# CHARGE SMS request
curl -i https://sonar.fonix.io/v2/chargesms \
 -H X-API-KEY:test_BYZNk5YUBMLfowSOQTUuqq3t \
 -d ORIGINATOR=84988 \
 -d NUMBERS=440200000004 \
 -d BODY=Welcome%20Home

# CHARGE SMS response
# {"success":{"txguid":"680f3176-cd7e-484d-aef9-7c46e95187ef",
#  "numbers":"1","smsparts":"1","encoding":"gsm","price":10}}

# DR SMS HTTPS POST example (to your application)
#
# POST /path/drsms HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=eetmo-uk&RETRYCOUNT=0&MONUMBER=440200000004
# &DESTINATION=84988&STATUSTIME=20160301110820
# &STATUSTEXT=Operator+System+Error&STATUSCODE=SMSC_ERROR
# &CHARGESTATUS=false&GUID=680f3176-cd7e-484d-aef9-7c46e95187ef
# &PRICE=10&DURATION=0

When submitting a valid DUMMY SMS or WAP request the system generates a response and a DR without submitting the request to network operators. You will get an error in the response if one ore more parameters are not valid.

We don’t perform duplicate checks on DUMMY requests and we try to deliver DRs only once.

You can force the OPERATOR, CHARGESTATUS (only for CHARGE SMS requests), STATUSCODE and STATUSTEXT of the DR that we’ll send back to you through the NUMBERS parameter that you pass in the request to us.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

CHARGESTATUS, STATUSCODE and STATUSTEXT can be controlled using the last 8 digit of the MSISDN:

Msisdn Suffix CHARGESTATUS STATUSCODE STATUSTEXT
00000001 true if premium DELIVERED OK
00000002 false INVALID_MSISDN Destination Address Error
00000003 false OPERATOR_REJECTED Invalid state or parameters
00000004 false SMSC_ERROR Operator System Error
00000005 false INSUFFICIENT_FUNDS Temporary Error
00000006 false UNKNOWN_MSISDN UnknownSubscriber
00000007 false TEMPORARY_OPERATOR_ERROR Temporary network/roaming issue
00000008 false UNREACHABLE_MSISDN Mobile not reachable or temporary busy
00000009 false INVALID_OPERATOR_SERVICE Service not supported from mobile or operator
00000010 false PERMANENT_OPERATOR_ERROR Permanent Error (network/parameters
00000011 false TEMPORARY_BARRED Temporary Barred
00000012 false PERMANENTLY_BARRED Permanently Barred
00000013 false UNKNOWN_ERROR Unknown Error
00000014 false MAX_SPEND_MSISDN Spend Limit Reached
00000015 false OPERATOR_TIMEOUT Operator has not acknowledged. Message might have been sent
00000016 false UNROUTABLE Unable to route the message

DUMMY ADULT VERIFY

# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo \
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t \
-d NUMBERS=eetmo-uk.440000000001 \
-d NETWORKRETRY=YES

# Sync Response
# {"verified":{"ifversion":"201001","operator":"o2-uk",
#  "guid":"5917d9ad-8c13-42a2-8a42-fd1d65cf2728"}}



# Sync Request
curl -i  https://avsolo.fonix.io/v2/avsolo \
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t \
-d NUMBERS=eetmo-uk.440000000001 \
-d NETWORKRETRY=NO

# Sync Response
# {"unknown":{"ifversion":"201001","operator":"eetmo-uk",
#  "guid":"938323a6-5147-43e7-b552-247ca9e62108"}}



# Async Request
curl -i  https://sonar.fonix.io/v2/adultverify \
-H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t \
-d NUMBERS=three-uk.440100000002 \
-d NETWORKRETRY=YES

# Async Response
# {"success":{"txguid":"3f8b527c-e27a-4a56-9cab-b3bb3ff7b885",
#  "numbers":"1"}}

# AV REPORT HTTPS POST (to your application)
#
# POST /path/chargereport HTTP/1.1
# Content‐Type: application/x-www-form‐urlencoded
# Connection: Keep-Alive
#
# IFVERSION=201001&OPERATOR=voda-uk&GUID=3f8b527c-e27a-4a56-9cab-b3bb3ff7b885&AV=NOT_VERIFIED

DUMMY requests can be sent to both synchronous and asynchronous APIs.

The synchronous response and the AV report depend on the MSISDN submitted.

OPERATOR will be set by the first 4 digit of the MSISDN according to the above table.

The AV status is fixed based on the last 8 digit of the MSISDN submitted according to the following table.

If NETWORKRETRY=NO and the operator submitted doesn’t match the one set by the first 4 digit of the submitted MSISDN then the AV status will always be unknown.

Msisdn Suffix AV STATUS
00000001 verified
00000002 not_verified
00000003 unknown
00000004 pending

DUMMY OPERATOR LOOKUP

# Request
  curl -i http://sonar.fonix.io/v2/operator_lookup?NUMBER=440500000002 \
  -H X-API-KEY:test_BYZNk5YUBMLfowS0QTUugg3t

# Response
#   {
#   "success":
#       {"mcc":"234",
#         "mnc":"20",
#         "operator":"three-uk"}
#   }

DUMMY requests receive responses depending on the MSISDN submitted. OPERATOR is set based on the first 4 digit of the MSISDN according to the above table.

Document Version

v2.9

Fonix