1. OVERVIEW

This document describes the API for the Phanerus E1 messaging platform. Providing access for developers to the messaging interface with a powerful set of tools to help facilitate deployment of messaging based applications. The platform can be accessed by the following ways:

  
-	HTTP submitted using GET or POST. 
- SMPP which enables message transfer via a 7bit PDU.
- SMTP which enables email applications to send email that gets delivered as SMS.

Only the HTTP access method is covered in this documentation. However, all the access methods implement the same properties as will be described in detail within this document.


2. AUTHENTICATION

In order to begin delivering messages, Phanerus will need to authenticate to ensure it is coming from a valid customer. The following parameters are used by us to authenticate third parties:

  http://sms.phanerus.com/API-E1/http/authenticate/?username=yourlogin&password=yourpassword  
The username and password has to be part of each message submission request. Also, an authentication check can be performed by sending a POST or GET using request type authenticate, for which the following string will have to be used.
Parameter Description
Server name sms.phanerus.com
API version API-E1
Access method http
Request type authenticate
Authentication Customer/s username and password

Example:

  http://sms.phanerus.com/API-E1/http/authenticate/?username=yourlogin&password=yourpassword  
ParameterReturn Values
Valid username & password True
Invalid username & password False

 

3. SMS CREDITS

The SMS credits balance for an account can be retrieved using the following parameters

 The SMS credits balance for an account can be retrieved using the following parameters  
ParameterDescription
Server name sms.phanerus.com
API version API-E1
Access method http
Request type smscredits
Authentication Customer/s username and password

Example:

  http://sms.phanerus.com/API-E1/http/smscredits/?username=yourlogin&password=yourpassword  

 

4. MESSAGING

Phanerus Technologies uses various SMSC connections which are set automatically at message send time based on message routing requirements. About seven different types of messages are supported text message, multiple recipient text messaging, two way message, concatenated message, WAP message, silent message, binary message, unicode message and schedule message.

4.1 TEXT MESSAGE

 Phanerus Technologies uses various SMSC connections which are set automatically at message send time based on message routing requirements. About seven different types of messages are supported text message, multiple recipient text messaging, two way message, concatenated message, WAP message, silent message, binary message, unicode message and schedule message.  
ParameterDescription
Request type Textmessage
Authentication Customer/s username and password
Message The text content of the message
Mobile The recipient address
Sender The originating name or address
Countrycode Destination

Example:

  http://sms.phanerus.com/API-E1/http/textmessage/?username=yourlogin&password=yourpassword&message=This+is+a+test+message&mobile=27830000001&sender=phanerus&countrycode=27  

 

4.2 MULTIPLE RECIPIENT TEXT MESSAGE

 
ParameterDescription
Request type Textmessage
Authentication Customer/s username and password
Message A comma separated recipient address list
Mobile The originating name or address
Sender Destination
Countrycode Country code

Example:

  http://sms.phanerus.com/API-E1/http/textmessage/?username=yourlogin&password=yourpassword&message=This+is+a+multiple+recipient+message&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27  

 

4.3 TWO WAY MESSAGE

Two way messaging delivers the SMS to the destination handset with a reply to virtual mobile number message appended to the message text. An allowance of 26 characters should be created for this additional content. If the subscriber replies to this message (i.e to the virtual mobile number) the Phanerus E1 platform would forward the MO reply to the reply path - email address – provided.

The MO reply forwarded to the reply path will contain a session identifier e.g. sessionid=6048y2384y63596494u6, which will be used to track the conversation and associate the MO reply with the MT message originally submitted to the Phanerus E1 platform. This session tracked 2 way messaging is enabled by the presence of the sessionid parameter.

The MO reply forwarded to the reply path will contain a session identifier e.g. sessionid=6048y2384y63596494u6, which will be used to track the conversation and associate the MO reply with the MT message originally submitted to the Phanerus E1 platform. This session tracked 2 way messaging is enabled by the presence of the sessionid parameter.
Parameter Description
Request type twowaymessage
Authentication Customer/s username and password
Message The text content of the message
Mobile The recipient address(s)
Sender The originating name or address
Countrycode Destination Country code
Reply path Your email address
Session id Stored session identifier

Example :

  http://sms.phanerus.com/API-E1/http/twowaymessage /?username=yourlogin&password=yourpassword &message=This+is+a+two+way+message&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27& sessionid=6048y2384y63596494u694&replypath=yourname@email.com  

 

4.4 SCHEDULE MESSAGE

Set the time-zone you wish the "timezone" parameter. The time-zone must be specified in the TZ format, e.g. "Africa/Johannesburg". You can view a list of time zone formats here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
Parameter Description
Request type Schedulemessage
Authentication Customer/s username and password
Message The text content of the message
Mobile The recipient address(s)
Sender The originating name or address
Countrycode Destination Country code
Delivery time Time in YYYY-MM-DD HH:MM:SS format
Timezone Timezone for message delivery e.g. Africa/Lagos

Example:

  -	YYYY is the year 
- MM is the month
- DD is the day of the month
- HH is the hour of the day
- MM is the minute of the hour
- SS is the seconds

 

4.5 CONCATENATED MESSAGE

Messages that exceed 160 characters will automatically be sent as two or three page messages, with 140 characters as the additional page length size.

 

4.6 WAP MESSAGE

The WAP Push message requires the URL parameter, this is used by the WAP Service Indicator to begin download of software, JPEG, MP3 or any other form of media which you intend to transfer.

 http://sms.phanerus.com/API-E1/http/textmessage/?username=yourlogin&password=yourpassword &message=This+is+a+wap+message&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27&url=wap.yourwebsite.com/datafiles/32412315132.jpg
The presence of the url parameter informs the system that you are sending a wappush message.
ParameterDescription
Request type Description
Authentication wapmessage
Message Customer/s username and password
Mobile The text content of the message
CountrycodeA comma separated recipient address list
url The originating name or address

Example:

  http://sms.phanerus.com/API-E1/http/textmessage/?username=yourlogin&password=yourpassword &message=This+is+a+wap+message&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27&url=wap.yourwebsite.com/datafiles/32412315132.jpg  

 

4.7 SILENT MESSAGE

The silent message requires the silentmessage request type.

The presence of the url parameter informs the system that you are sending a wappush message.

Parameter Description
Request type Silentmessage
Authentication Customer/s username and password
Message The text content of the message
Mobile A comma separated recipient address list
Sender The originating name or address
Countrycode Destination Country code

Example :

  http://sms.phanerus.com/API-E1/http/silentmessage/?username=yourlogin&password=yourpassword &message=This+is+a+silent+message&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27  

 

4.8 UNICODE MESSAGE

The unicode message requires the unicodemessage request type, some writings done in unicode format are Arabic, Armenian, Bengali, Bopomofo, Cyrillic, Devanagari, Georgian, Greek and Coptic, Gujarati, Gurmukhi, Hangul, Hebrew, Hiragana, Kannada, Katakana, Lao, Latin, Malayalam, Oriya, Tamil, Telugu, Thai, and Tibetan.
ParameterDescription
Request type Unicodemessage
Authentication Customer/s username and password
Message The message in unicode format e.g. Arabic or Hebrew
Mobile A comma separated recipient address list
Sender The originating name or address
Countrycode Destination Country code

Example:

  http://sms.phanerus.com/API-E1/http/unicodemessage/?username=yourlogin&password=yourpassword&message=%D8%AC%D9%87%D8%A7%D8%AF%20%D8%AF%D9%8A%D8%A8&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27  

 

4.9 BINARY MESSAGE

The binary message requires the binarymessage request type.
Parameter Description
Request type Binarymessage
Authentication Customer/s username and password
Message The message encoded in binary format
Mobile A comma separated recipient address list
Sender The originating name or address
Countrycode Destination Country code

Example:

  http://sms.phanerus.com/API-E1/http/unicodemessage/?username=yourlogin&password=yourpassword&message=546869732069732074686520646174612C20696E2074686520636C6561722E&mobile=27830000001, 27830000002&sender=phanerus&countrycode=27  

 

5. RESPONSES

The response values indicate the status of network interaction between the Phanerus E1 platform and the customer/s application.

Note: For safe delivery using the HTTP protocol we advise that contact numbers are offloaded in batches of 100. Developer could create a script to loop through the contact base until all message is offloaded to all contacts.
Following is the list of values return by the server on submission of sms via HTTP.
Return Code Description
1200 Request Timeout
1201|Batch_number|Date time Message Sent Successfully
1202 Invalid IP
1203 Incorrect Username or Password
1204 Insufficient Credits
1205 Invalid url Submission
1206 Invalid Mobile
1207 Invalid Sender Id
1208 Invalid Message length
1209 Message Empty
  Note: For safe delivery using the HTTP protocol we advise that contact numbers are offloaded in batches of 100. Developer could create a script to loop through the contact base until all message is offloaded to all contacts.  

 

6. MESSAGE PARAMETERS IN DETAIL

Domain Name (domain name)

User/s account details on PHANERUS.COM

Username (Username)

The username parameter value is passed for validation purposes. The username is The same as that which is supplied by the client while registering on PHANERUS.COM. The username (username) parameter is the email address with which you signed up on PHANERUS.COM, with no spaces.

Password Parameter (password)

The password parameter value is also passed in combination with the username for validation purposes. The password is created by the client along with the username when he registers with PHANERUS.COM for sending SMS messages through the Gateway.

Mobile Number Parameter (mobile)

The mobile number parameter refers to the destination mobile number to which the message is to be sent. However, the mobile number is required to be in a specific format. Any error in this parameter value would lead to non-delivery of the message. The mobile number should contain only numbers. It must also include the country code at the start beginning. It should not contain any symbols (+) or zero (0) etc. and it must be a valid mobile Number

Message Parameter (message)

The message parameter refers to the actual message that is to be sent to the destination mobile (mobile). The message parameter may consist of up to 160 characters belonging to the following set:
- A to Z a to z 0 to 9
- Blank space
- The meta characters \ (line feed)
Due to restrictions in the HTTP protocol format, the following special characters must be encoded in order not to collide with reserved HTTP characters: Character must be encoded as:

For simple text messages, the message can contain numbers, alphabets, spaces and certain special characters.

Message Parameter (message)

The sender parameter refers to the message dispatcher or the From clause (THE SENDER), from whom the message is sent. The sender can an eleven character alphanumeric string. The sender Id is an optional clause. In case the sender Id is not specified, PHANERUS.COM is sent as the sender to the destination mobile.

Sender Id (sender)

Character Hexa-decimal Encoded String
Dollar ("$") %24
Ampersand ("&") %26
Plus ("+") %2B
Comma (",") %2C
Forward slash/Virgule ("/") %2F
Colon (":") %3°
Semi-colon (";") %3B
Equals ("=") %3D
Question mark ("?") %3F
/At/ symbol ("@") %40
Space %20
Quotation marks %22
/Less Than/ symbol ("<") %3C
/Greater Than/ symbol (">") %3E
/Pound/ character ("#") %23
Percent character ("%") %25
Left Curly Brace ("{") %7B
Right Curly Brace ("}") %7D
Vertical Bar/Pipe ("|") %7C
Backslash ("\") %5C
Caret ("^") %5E
Tilde ("~") %7E
Left Square Bracket ("[") %5B
Right Square Bracket ("]") %5D
Grave Accent ("`") %60

 

7. DELIVERY REPORTS

Deliver reports are gathered using the "Batch Number" along with the "Date time" when the SMS was received by the Phanerus E1 platform. This info (Batch Number and Date time) was received as a response along with the "1201 response code" after data payload was sent successfully.

Delivery reports are retrievable only for 48hours after message is received by the Phanerus E1 platform, after 48hours DLR must be downloaded directly from the Phanerus SMS web interface.

Parameter Description
Request type delivery report
Authentication Customer/s username and password
marker The Batch Number
datetime Date time when message was received by the Phanerus E1 platform

Delivery reports are retrievable only for 48hours after message is received by the Phanerus E1 platform, after 48hours DLR must be downloaded directly from the Phanerus SMS web interface.

Example:

  http://sms.phanerus.com/API-E1/http/dlr/?username=yourlogin&password=yourpassword &marker=3SEAPRA4OII1D18ZR2S5&datetime=2014-06-27%2008:06:10