Cequens SMSC · SMSC will handle message partitioning for you (used with Cequens managed services)...

Cequens SMSC

Interfaces Manual

Interfaces Manual

Template Version: 1.0 Document Version: 1.0 of 13

List of Contents

1. Overview .............................................................................................................................. 3

2. HTTP Interface Specifications ............................................................................................. 3

2.1. Basic Query ................................................................................................................. 3

2.2. Query Parameter Description ...................................................................................... 4

2.3. HTTP Interface Response ........................................................................................... 5

2.4. Send single SMS to one Recipient Query .................................................................... 6

2.5. Send single SMS to multiple recipients Query ............................................................. 6

2.6. Send POST Request ................................................................................................... 7

2.7. SMS Sending Errors .................................................................................................... 8

2.8. Receive DLR from HTTP Interface .............................................................................. 9

2.9. Credit Balance Query .................................................................................................. 9

2.10. Check Credit Balance Errors ..................................................................................... 9

3. XML Interface Specifications ............................................................................................. 10

4. SMPP Interface Specifications .......................................................................................... 11

Interfaces Manual


1. Overview

This document is for those clients who want to develop business applications to integrate with

Cequens SMSC and make use of its facilities in handling different types of sending SMS.

These Interfaces provide the client’s with the ability to integrate with Cequens SMSC to send

SMS. It was designed to help developers be more productive and to be able to add SMS

functionality to any project efficiently. Below are the main interfaces for this integration purposes:

HTTP interface: using GET and POST method over SSL.

XML interface: using HTTP POST method to pass an XML file over HTTP URL.

SMPP 3.4 (Using SMPP standards)

2. HTTP Interface Specifications

The HTTP Interface offers a number of messaging queries and SMS features, which can be

performed by forming the designated URL. HTTP Interface also support connection via Secure

Socket Layer (SSL).

2.1. Basic Query

Query is made up of three segments:

1. Authentication: username and password

2. The Basic Message components: message content and recipients and the

3. Additional message parameters

In the examples below, we will include the authentication and basic message components. The

additional message parameters will be included only where they are relevant.

Basic Query Structure:

http://ht.cequens.com/Send.aspx?UserName=xxx&Password=xxx&MessageType=xxxx

&Recipients=xxxx&SenderName=xxx&MessageText=xxx

For SSL connection just change http to https:

https://ht.cequens.com/Send.aspx?UserName=xxx&Password=xxx&MessageType=xxxx

&Recipients=xxxx&SenderName=xxx&MessageText=xxx

Interfaces Manual


2.2. Query Parameter Description

Parameter Type Short Description Restricted Values

UserName

(Required) String Your account username

Password

(Required) String Your account password

Recipients

(Required)

String

SMS Recipients valid mobile numbers. In case of multiple recipients, the numbers passed in a comma-separated format.

The number should be in required international number format.

Recipient no. consists of:

country code + network prefix

+ mobile number

e.g.: (966)(50)(1231234), (20)(10)(6587435)

MessageText

(Required) String Content of the message, Unicode/English

SenderName

(Required)

String

The message sender ID, which will be in the message.

The sender name can be mobile number or text (e.g. sender name)

A valid international format number between 1 and 16 characters long or an 11 character alphanumeric string; e.g. 0105478963,XYZ.

Note: The characters such as spaces, punctuation, Unicode and other special characters are not recommended. (0) don’t return

Acknowledgement

(Optional) Int

This will return a delivery acknowledgement for any message, upon delivery of the message to the mobile stations.

acknowledgement

(1) return acknowledgement

Delivery Time

(Optional)

Int

Delays delivery of SMS to mobile device, here the SMS was received by our SMSC. His ... should be greater than 10 minutes for best effect. Smaller time frames may

be delivered soon

The upper limit is 7 days, or

10080 minutes.

ClientMessagelD (Optional)

Long Client message ID defined by the client for internal message tracking in his/her business application.

Up to 32 Alphanumeric characters.

Interfaces Manual


Parameter Type Short Description Restricted Values

MessageType

(Required) String

Either Text or Unicode

Text: This is the default message type. To

send plain text messages.

Unicode: Send UTF-16BE messages.

In case of Unicode: You should convert message text to UTF-16BE before sending it through URL

ValidityPeriod

(Optional) Int

1440 This format.

Set value at X minutes to the period in minutes, minutes where the SMS was

(24 received by SMSC). The message will not be delivered if it is still queued in the SMSC after this period.

DlrUrl

(Optional) String

If you want ro recive DLR you have to setup you own http service on your own servers.

And send service url to Cequens HTTP interface in this parameter

2.3. HTTP Interface Response

Interface will return JSON response. Response will be in below format:

{

"requestStatus": {

"RequestID":<number>,

"ClientMessageID": <text>,

"ResponseText": <text>

},`

"invalidRecipients": <text>,

“notSentTryAgain”: <text>, "errors": [

[

<number>, <text>

]

]

}

Where:

Property Description

RequestID Random generated ID for each request

ClientMessageID Id that customer send in the request, interface return it as is.

ResponseText Request status.

invalidRecipients CSV of all invalid mobile numbers in the request

notSentTryAgain CSV of all numbers that didn’t sent and you can try to send them again.

Errors List of errors that occur while handle request

Interfaces Manual


2.4. Send single SMS to one Recipient Query

Request Format:

http://ht.cequens.com/Send.aspx?UserName=uuuu&Password=ppp&MessageType=text

&Recipients=1111111111111&SenderName=sss&MessaqeText

Response Format: JSON

{

"requestStatus": {

"RequestID": 854289307,

"ClientMessageID": 10,

"ResponseText": "Request Handled Successfully"

},`

"invalidRecipients": "",

“notSentTryAgain”: "",

"errors": []

}

2.5. Send single SMS to multiple recipients Query

Request Example:

http://ht.cequens.com/Send.aspx?UserName=uuu&Password=ppp&Message

Type=text&Recipients=1111111111111,2222222222222,201006&SenderName=ssss&MessageText=

mm mm

Response Example:

{

"requestStatus": {

"RequestID": 854289307,

"ClientMessageID": 10,

"ResponseText": "Request Handled Successfully"

},`

"invalidRecipients": "",

“notSentTryAgain”: "",

"errors": [

[-4, "Invalid Recipient Number: 201006"]

]

}

Interfaces Manual


2.6. Send POST Request

To send HTTP POST request, send parameters as post data.

Host or url = http://ht.cequens.com/send.aspx

Post data = “UserName=uuu&Password=ppp&MessageType=text&Recipients=1111111111

&SenderName=ssss&MessageText=example”

Example in C#:

var request = (HttpWebRequest)WebRequest.Create("http://ht.cequens.com/send.aspx");

var postData =

"UserName=uuu&Password=ppp&MessageType=text&Recipients=1111111111&SenderName=ssss&Me

ssageText=example";

var data = Encoding.ASCII.GetBytes(postData);

request.Method = "POST";

request.ContentType = "application/x-www-form-urlencoded";

request.ContentLength = data.Length;

using (var stream = request.GetRequestStream())

{

stream.Write(data, 0, data.Length);

}

var response = (HttpWebResponse)request.GetResponse();

var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();

Interfaces Manual


2.7. SMS Sending Errors

In the aforementioned queries, if invalid or empty parameters were passed in the HTTP request

a list of defined errors will be returned as explained below:

Error Code Error Text Comment

-1 Authentication Failed; User Name missing.

-1 Authentication Failed; Password missing.

-1 Authentication Failed; Account Not found.

-1 Authentication Failed; Password not match.

-1 Authentication Failed; Account Expired.

-1 Authentication Failed; No Permission to send from this interface.

-2 Invalid Validity Period

-3 No Recipients.

-4 Invalid Recipient Number: <number>

-5 Invalid Client message ID. If length more than 32 char

-6 Empty Message

-7 Invalid Message Type

-8 Invalid Delivery Time

-9 Invalid Sender Name

-10 Not sent for recipient: <number> try again later!

-12 Not Enough Credits.

-15 Flashing should be 0 or 1

-16 Invalid Unicode data! If message text is Unicode and invalid

-18 Acknowledgment should be 0 or 1

Interfaces Manual


2.8. Receive DLR from HTTP Interface

In order to recive DLR from HTTP interface you should do the following:

- On your premises, develop http service to parse the parameters of GET request, let say

it will be:

o www.account.com/dlr.aspx.

- Add the URL of this service in http request parameters:

o http://ht.cequens.com/Send.aspx?UserName=uuu&Password=ppp&MessageType=t

ext&dlrurl=www.account.com/dlr.aspx&Recipients=111111111&SenderName=sss

s&MessageText=xxxxxx

- Or, as alternative to previous step, predefine DLR URL in your account profile in portal

under "Delivery Address" field.

- When DLR is revieved from GSM network, HTTP interface will send it your service as

GET request in this format:

o www.account.com/dlr.aspx?msgid=guid&statusid=1&from=Sender&to=002010012

34567&statusmsg=NACK&accountid=user&SubmitDate=2015-03-12+09%3A07%3A37

- If you send ClientMessageID in HTTP request, you will recived it in DLR like this:

o www.account.com/dlr.aspx?ClientMessageID=123&msgid=guid&statusid=1&from

=Sender&to=00201001234567&statusmsg=NACK&accountid=user&SubmitDate=2015

-03-12+09%3A07%3A37

2.9. Credit Balance Query

Request Example:

http://ht.cequens.com/BalanceQuery.aspx?UserName=xxxx&Password=xxxx

Response Example:

Credit=xxxxxxxx

2.10. Check Credit Balance Errors

Error Parameter Error Number Returned Error Message

If passing invalid username and password -1 Authentication Failed.

If passing empty value in a required parameter -3 Invalid or Missing Parameter

If there is no credit -9 Nocreditlift

Interfaces Manual


3. XML Interface Specifications

In the XML interface the client can post XML file with certain schema to pass the required

parameters.

XML File Sample:

<?xml version=‘1.0’ ?>

<root>

<File_Description>

<File_Type>Classic</File_Type>

<MessagesCount>1</MessagesCount>

<UserName>1234</UserName>

<Password>1234</Password>

<DlrUrl></DlrUrl>

<DateStamp></DateStamp>

</File_Description>

<Messages>

<Message>

<MessageText>sample</MessageText>

<MessageContent></MessageContent>

<ClientMessageID>101</ClientMessageID>

<Flashing></Flashing>

<SenderName></SenderName>

<Acknowledgement>True</Acknowledgement>

<EnableCallback>2</EnableCallback>

<DeliveryTime>1440</DeliveryTime>

<MaximumCredits></MaximumCredits>

<MessageType>text</MessageType>

<ValidityPeriod>1440</ValidityPeriod>

<Recipients>

<Recipient>201006930543</Recipient>

</Recipients>

</Message>

</Messages>

</root>

Interfaces Manual


4. SMPP Interface Specifications

Cequens SMSC offers SMPP version 3.4 interface. Accordingly when using the SMPP interface

the connection between your application and Cequens SMSC will be through SMPP version 3.4.

The default data coding data_coding = 0 for GSM 03.38 data coding

data_coding = 8 for UCS-2 data coding

maximum number of characters per message for data_coding = 0 is 160 character

maximum number of characters per message for data_coding = 8 is 70 character

Send Long Messages

Client can use one of the following options

1. Client send message partitioning with UDH included for each part, UDHI should be set in

esm_class

2. Client send message partitioning with sar_msg_ref_num, sar_total_segments,

sar_segment_seqnum TLV parameters set for each part

Client send message without partitioning using message_payload TLV parameter and Cequens

SMSC will handle message partitioning for you (used with Cequens managed services)

Parameter Description

Username Provided for each client

Password Provided for each client

IP address SMSC SMPP interface IP (smpp.cequens.com)

Port A port from the set of available ports will be provided to the client

Session Type Transmitter, Receiver, or Transceiver

Number of Sessions:

Cequens provide each SMPP client account with a number or a maximum of sessions in which

the client could connect to simultaneously to ease the messages transmission process.

Session Binding Types:

Client could bind to Cequens SMSC interface through Transmitter, Receiver, or Transceiver. In

order to receive delivery reports you must bind Receiver or Transceiver.

PBUs Supported:

bind_transmitter, bind_reciever, bind_transciever, unbind, submit_sm, enquire_link

Interfaces Manual


Commend Response Description

ENQUIRE_LINK ENQUIRE_LINK_RESP To keep session alive

SUBMIT_SM SUBMIT_SM_RESP Submit response

BIND_TRANSCEIVER BIND_TRANSCEIVER_RESP Binding transceiver response

BIND_TRANSMITTER BIND_TRANSMITTER_RESP Binding transmitter response

BIND_RECEIVER BIND_RECEIVER_RESP Binding receiver response

UNBIND UNBIND_RESP Unbinding response

Submit Response:

As to confirm receiving, the messages from our clients our gateway sends submit response

confirmation message for the client application once message is received.

DLR Support:

Client will receive delivery report only if your route provider supports delivery reports. If provider

supports delivery report, reports will be sent to you equal the sent messages. In order to be able

to receive the reports you should set registered_delivery value to 1 for each SUBMET_SM PDU

and either bind with Receiver or Transceiver session.

DLR Format:

Cequens SMSC provide the delivery report to the client with the below format:

id:{message_id} sub:001 dlvrd:001 submit date:{date} done date:{date} stat:{stat}

err:{error_code} text:{msg}

DLR TLV parameters

Cequens SMSC provides the delivery report to the client with TLV parameters

receipted_message_id

message_state

Contact Information

Egypt

21 Mohamed Tawfiq Diab St,

Off Makram Ebeid St,

Nasr City, 11371,

Cairo, Egypt

Tel: +20 (2) 22734506

Fax: + 20 (2) 35365668

Saudi Arabia

Tawuniya Towers, King Fahd Rd.,

North Tower, 7th Floor,

P.O. Box 220933

Riyadh, Saudi Arabia

Tel: +966 (11) 2181515

Fax: +966 (11) 2181520

Website & Email

www.cequens.com

[email protected]

Cequens SMSC · SMSC will handle message partitioning for you (used with Cequens managed services)...

Documents

Transcript of Cequens SMSC · SMSC will handle message partitioning for you (used with Cequens managed services)...