Documentation
Welcome to the Sequel API Developer Documentation. On this page you can get all the information to connect your software to our Communication Platform.
Communication protocols overview
Short Message Peer-to-Peer (SMPP)
Short Message Peer-to-Peer (SMPP) in the telecommunications industry is an open, industry standard protocol designed to provide a flexible data communication interface for the transfer of short message data between External Short Messaging Entities (ESMEs), Routing Entities (REs) and SMSC.
SMPP is often used to allow third parties (e.g. value-added service providers like news organizations) to submit messages, often in bulk, but it may be used for SMS peering as well. SMPP is able to carry short messages including EMS, voicemail notifications, Cell Broadcasts, WAP messages including WAP Push messages (used to deliver MMS notifications), USSD messages and others. Because of its versatility and support for non-GSM SMS protocols, like UMTS, IS-95 (CDMA), CDMA2000, ANSI-136 (TDMA) and iDEN, SMPP is the most commonly used protocol for short message exchange outside SS7 networks.
The Hypertext Transfer Protocol (HTTP)
The Hypertext Transfer Protocol (HTTP) is an application layer protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web, where hypertext documents include hyperlinks to other resources that the user can easily access.
Development of HTTP was initiated by Tim Berners-Lee at CERN in 1989. Development of early HTTP Requests for Comments (RFCs) was a coordinated effort by the Internet Engineering Task Force (IETF) and the World Wide Web Consortium (W3C), with work later moving to the IETF.
HTTP functions as a request-response protocol in the client-server computing model. A web browser, for example, may be the client and an application running on a computer hosting a website may be the server. The client submits an HTTP request message to the server. The server, which provides resources such as HTML files and other content, or performs other functions on behalf of the client, returns a response message to the client. The response contains completion status information about the request and may also contain requested content in its message body.
Hypertext Transfer Protocol Secure (HTTPS) is an extension of the Hypertext Transfer Protocol (HTTP). It is used for secure communication over a computer network, and is widely used on the Internet. In HTTPS, the communication protocol is encrypted using Transport Layer Security (TLS) or, formerly, Secure Sockets Layer (SSL). The protocol is therefore also referred to as HTTP over TLS, or HTTP over SSL.
SMPP 3.4
We providing access to our SMPP platform for more efficient message delivery. This allows an applications to communicate with our Short Message Service Centres to perform messaging between the application and SMS capable mobile devices. Suitable for use with all standard SMPP applications as based on v3.4 protocol.
SMPP Activation
SMPP is not activated by default on your accounts. To activate it you must send request to helpdesk@sequel-tele.com. SMPP is primarily aimed at high throughput bulk SMS uses. If you will send or receiving low volumes you may want to consider using our HTTP API. SMPP activation normally takes no longer than 24 hours excluding weekends.
Protocol Specification
The Short Message Peer to Peer (SMPP) protocol is an open, industry standard protocol designed to provide a flexible data communications interface for transfer of short message data between a Message Center, such as a Short Message Service Centre (SMSC), GSM Unstructured Supplementary Services Data (USSD) Server or other type of Message Center and a SMS application system, such as a WAP Proxy Server, EMail Gateway or other Messaging Gateway.
Protocol version
The provided SMPP support is SMPP version 3.4, the full SMPP specification can be downloaded from the https://smpp.org web site. Version SMPP 5.0 is currently unsupported. The SMPP Version must always be set to 0x34 (hex 34) for version 3.4. If this is not set, your connection attempts will be rejected.
Connection settings
| Primary Host | Backup Host | |
|---|---|---|
messaging.sequel-tele.com |
backup.sequel-tele.com |
|
Port : TX |
5000 (5001 SSL) | 5000 (5001 SSL) |
Port : RX |
5000 (5001 SSL) | 5000 (5001 SSL) |
Port : TRX |
5000 (5001 SSL) | 5000 (5001 SSL) |
To start using SMPP API you need to whitelist your IP address in User panel Interface. Otherwise, the connection attempt will be rejected.
Submit Throughput
Submit throughput is limited to 20 SMS/sec. If you require higher throughput please contact the Support Team to discuss your needs.
Optional Parameters
Optional parameters (v3.4) are not supported.
SMPP Commands
The following list contains all commands supported by our SMSC
bind_transmitter
bind_transmitter_resp
bind_receiver
bind_receiver_resp
bind_transceiver
bind_transceiver_resp
unbind
unbind_resp
submit_sm
submit_sm_resp
deliver_sm
deliver_sm_resp
enquire_link
enquire_link_resp
generic_nack
Bind Operation
Use the bind request to initiate an SMPP session for transmitting messages. During the bind operation, you will pass your account ID and password in an encoded format. Your information is authenticated, and once authenticated a connection is established. With the connection established, you can then send messages.
Bind request is composed of a header indicating the type of request and PDU parameters. Sequel platform returns a bind response along with a Bind response status codes. A bind request can be sent by any PDU of the following:
bind_transmitter: you will be able to send messages. To receive delivery reports you should open bind_receiver session at same time.
bind_receiver: you will be able to receive delivery reports. To send messages you should open bind_transmitter or bind_transceiver session at same time.
bind_transceiver: you will be able to send messages and receive delivery reports in same session.
Bind response
In case of successful submitting of bind request you will get bind response. Main purpose of the response is tell you that your credentials is proper and connection was successful made.
Sice you submited bind PDU with proper login and password you will get response containing Command Status value 0x00 wich means The request completed successfully. List of Command Statuses for bind operation listed below.
| Code | Message | Comments |
|---|---|---|
0x00 |
No error | The request completed successfully. |
0x02 |
Command length is invalid | This is not supported in the API. If the command length is invalid, the bind is dropped. |
0x05 |
ESME Already in Bound State | A bind request was submitted, but the allowed number of binds for the account are already connected. |
0x08 |
System Error | Internal SMPPGW system error. For example, this might be when server can't be reached to authenticate a user. |
0x0D |
Bind Failed | The bind failed authentication or if the customer account is not provisioned for SMS SMPP in the SMS provisioning tables. |
0x0E |
Invalid Password | Password is either outside of the defined length range or is NULL. |
0x0F |
Invalid System ID | The System ID is either outside of the defined length range or is NULL. |
Bind Drops
In the event of receiving an unbind request from the server, you should acknowledge the request with unbind_resp and disconnect. If no response is received within 60 seconds connection will be forceably closed. Once conncetion was closed your application should automatically rebind to the server, the frequency of rebinds should not be more than once every 30 seconds.
Enquire link
The enquire_link operation checks the communication link between your software and Sequel's SMS Center. enquire_link can be initiated by either you or by Sequel. As soon as you received enquire_link PDU you need to send enquire_link_resp PDU to our SMSC to acknowledge connection.
Our SMSC sends enquire_link once per 30 seconds. If we don't receive enquire_link_resp for next 60 seconds session will be droped.
Submit SM
The submit_sm operation allows you to submit a short message to Sequel's SMSC for transmission to a user's handset. Our SMSC supports submit_sm PDU request and submit_sm_resp PDU response. The PDU request is composed of mandatory parameters. submit_sm_resp PDU echoes back the header information and submit command status code indicating acknowledge of the request.
submit_sm PDU is composed of header and body that contains mandatory parameters, described in table below.
submit_sm PDU header
| Parameter | Description |
|---|---|
| Command Length |
Length of the PDU in octets.
Size (octets): 4 Type: Integer
|
| Command ID |
Identifies the type of message the SMPP PDU represents.
Size (octets): 4 Type: Integer Value: 0x04
|
| Command Status |
This field is not used. Set to 0x00 (NULL).
Size (octets): 4 Type: Integer Value: 0x00
|
| Sequence Number |
A unique customer-set sequence number. The associated submit_sm_resp PDU echoes this sequence number back in the response.
Size (octets): 4 Type: Integer Value: Customer-supplied
|
submit_sm PDU mandatory parameters
| Parameter | Description | |||
|---|---|---|---|---|
| Service Type |
Not used by our SMSC. Can be empty string.
Size (octets): Maximum is 6 Type: C-Octet String |
|||
| Source Address TON |
Source address type of number.
Size (octets): 1 Type: Integer Value: The value of the MT Source Address TON. Only the following are supported:
|
|||
| Source Address NPI |
Source address numbering plan indicator.
Size (octets): 1 Type: Integer Value: 0x00 or 0x01 The rules for filling out these fields are described in the section Type of Number and Number Plan Indicator Settings. |
|||
| Source Address |
Address of the originating short messaging entity (SME).
When submitting the source address, you must not use the leading plus (+) sign.
Size (octets): Minimum - 1, maximum - 21 Type: C-Octet String Value: Sender address. |
|||
| Destination Address TON |
Type of number (TON) for the destination.
Size (octets): 1 Type: Integer Value: 0x01 The rules for filling out these fields are described in the section Type of Number and Number Plan Indicator Settings. |
|||
| Destination Address NPI |
The destination address numbering plan indicator.
Size (octets): 1 Type: Integer Value: 0x01
The rules for filling out these fields are described in the section Type of Number and Number Plan Indicator Settings. |
|||
| Destination Address |
Address of message recipient. If the value is NULL or not within the defined length limits, the message will be rejected with error status ESME_RINVDSTADR.
Size (octets): Variable, but a maximum of 21 Type: C-Octet String Value: The message destination address. This must be a phone number that includes the country code. Do not include the leading plus (+) character. |
|||
| ESM Class |
The message mode and type, indicating any special message attributes associated with the SMS.
Size (octets): 1 Type: Integer Value:
|
|||
| Protocol ID |
The network protocol identifier.
Size (octets): 1 Type: Integer Value: Network-specific value. If non-NULL, the value is passed through to the mobile operator. |
|||
| Priority Flag |
Not used. Set to 0x00 (NULL). If a non-null value is supplied, it will be ignored.
Size (octets): 1 Type: Integer Value: 0x00
|
|||
| Schedule delivery time |
Not used. Set to 0x00 (NULL). If the value of this parameter is anything other than NULL, the MT is rejected with status code 0x61.
Size (octets): 1 Type: C-Octet String Value: 0x00
|
|||
| Validity Period |
If the default mobile operator validity period is requested, set to 0x0 (NULL). Otherwise, see section 7.1, "Time Definitions", in the SMPP v3.4 specification for instructions on setting a non-zero validity period in either absolute or relative time format.
Size (octets): 1 or 17 Type: C-Octet String Value: No default value is selected. If no value is supplied, the mobile operator's default value is used.
|
|||
| Registered Delivery |
Used to request an SMSC delivery receipt and/or SME-originated acknowledgment. If the value is not one of the supported values, the MT is rejected with status code 0x7.
Size (octets): 1 Type: Integer Value: Use one of the following:
|
|||
| Replace if Present Flag |
Not used. Set to 0x00 (NULL).
If the value of this parameter is anything other than NULL, message will be rejected with status code 0x54.
Size (octets): 1 Type: Integer Value: 0x00
|
|||
| Data Coding |
Defines the encoding scheme of the short message user data. If the value is not one of the supported values, message will be rejected with status 0x406.
Size (octets): 1 Type: Integer Value: Use one of the following:
See Data Coding Scheme Article for more information. |
|||
| Short Message Default Message ID |
Not used. Set to 0x00 (NULL). If the value of this field is anything other than NULL, message will be rejected with status 0x63.
Size (octets): 1 Type: Integer Value: 0x00
|
|||
| Short Message Length |
The length of the short message in the delivery receipt. If the Short Message content is greater than that of the specified Short Message Length, the message is truncated to the length specified by this parameter.
Size (octets): 1 Type: Integer Value: 0 to 160
|
|||
| Short Message |
Message text
Size (octets): 0 - 160
Type: Octet String Value: The message content. If the Short Message is greater than the Short Message Length, it is truncated to the value set by the Short Message Length.
|
|||
Submit response
submit_sm_resp is response for a submit_sm request. Response will include a status code indicating the result of the operation and message-id for tracking delivery receipt.
| Parameter | Description |
|---|---|
| Command Length |
Length of the PDU in octets.
Size (octets): 4 Type: Integer Value: Customer-supplied
|
| Command ID |
Identifies the type of message the SMPP PDU represents.
Size (octets): 4 Type: Integer Value: 0x04
|
| Command Status |
Identifies the outcome of the submit_sm request.
Size (octets): 4 Type: Integer Value: general response status code
All codes description you can find in Command Status codes description article. |
| Sequence Number |
The sequence number passed in the submit_sm request.
Size (octets): 4 Type: Integer Value: Customer-supplied
|
| Message ID |
Message-ID, used for tracking delivery receipts.
Size (octets): Variable, with a maximum of 65 Type: C-Octet String Value: Message ID
|
Delivery Receipts
Once a messages reaches its final status a delivery receipt will be returned with the corresponding message ID, indicating its delivery state and any error status. Delivery receipt data relating to the original SMS will be included in the short_message field of deliver_sm PDU.
Detailed description of short_message field you can find below
| Field | Size (octets) | Type | Description |
|---|---|---|---|
id |
10 | C-Octet String (Decimal) | The message ID allocated to the message by our SMSC when originally submitted. |
sub |
3 | C-Octet String (Decimal) | Unused feature, will always be 1. |
dlvrd |
3 | CC-Octet Fixed Length String (Decimal) | Unused feature, will always be 1. |
submit date |
10 | C-Octet Fixed Length String |
The time and date at which the short message was submitted. In the case of a message which has been replaced, this is the date that the original message was replaced.The format is as follows:
YYMMDDhhmm where: YY last two digits of the year (00-99) MM = month (01-12) DD day (01-31) hh hour (00-23) mm minute (00-59) |
done date |
10 | C-Octet Fixed Length String | The time and date at which the short message reached its final state. The format is the same as for the submit date. |
stat |
7 | C-Octet Fixed Length String | The final status of the message. See Message States and Error Codes below. |
err |
3 | C-Octet Fixed Length String | Any error code of the message. See Message States and Error Codes below. |
text |
20 | Octet String | Unused feature, result will be -. |
Type of Number and Number Plan Indicator Settings
Type of Number (TON)
The Type of Number (TON) setting is used to tell both your EMSE the format of the addressing (bind addressing) that will be processed for inbound messages as well as tell the Sequel network (source and destination addressing) how it should be processed for submits. There are three separate pairs of TON and NPI values; receiving addressing, source addressing, and destination addressing. These definitions are derived from the ETSI GSM 03.40 specification, which defines the SMS protocol. The SMPP specification defines the following TON values:
0: Unknown
1: International
2: National
3: Network Specific
4: Subscriber Number
5: Alphanumeric
6: Abbreviated
Numbering Plan Identification (NPI)
The Numbering Plan Identification setting is used to tell both your EMSE the numbering plan associated with your messaging. The SMPP specification defines the following TON values:
0: Unknown
1: ISDN/telephone numbering plan (E163/E164)
3: Data numbering plan (X.121)
4: Telex numbering plan (F.69)
6: Land Mobile (E.212)
8: National numbering plan
9: Private numbering plan
10: ERMES numbering plan (ETSI DE/PS 3 01-3)
13: Internet (IP)
18: WAP Client Id (to be defined by WAP Forum)
Short Code - 3 digits to 8 digits in length
If the source code/address is a Short Code
TON = 3
NPI = 0
Long Code - 10 digits to 15 digits in length, excludes the plus sign
If the source code/address is a Long Code the recommended settings and default settings will be used are:
TON = 1
NPI = 1
Alphanumeric
If the source code/address is Alphanumeric (contains both letters and numbers or only letters)
TON = 5
NPI = 0
Data Coding Scheme
In SMPP, the data coding scheme (DCS) indicates information that includes (but isn't restricted to) the character set that the message text is in.
Default character set
When your account is first provisioned, we set a default character encoding on your account for both sending and receiving messages. When sending messages, use DCS 0 to indicate that the message text uses your default character encoding. You can choose either of these two character sets as the default for your account:
DCS 0 - GSM 7-bit, default alphabet and extension table of 3GPP TS 23.038 / GSM 03.38.
Other DCS options
DCS 3 - Latin 1 (ISO-8859-1).
DCS 4 - Binary message
DCS 8 - UTF-16 big-endian encoding. See the Wikipedia article: http://en.wikipedia.org/wiki/UTF-16.
DCS 240 - Flash (class 0) message. The message text must use the default character set configured for your account.
DCS 24 - Flash (class 0) message, where the message text uses UCS-2.
DCS 246 - SIM-specific binary message. This is only used in special cases where you are communicating with a custom application on the mobile device. No message reaches the phone's SMS inbox.
Command Status codes description
| ID | Error | Description |
|---|---|---|
| 0 | ESME_ROK |
Ok - Message Acceptable |
| 1 | ESME_RINVMSGLEN |
Invalid Message Length |
| 2 | ESME_RINVCMDLEN |
Invalid Command Length |
| 3 | ESME_RINVCMDID |
Invalid Command ID |
| 4 | ESME_RINVBNDSTS |
Invalid bind status |
| 5 | ESME_RALYBND |
Bind attempted when already bound |
| 6 | ESME_RINVPRTFLG |
Invalid priority flag |
| 7 | ESME_RINVREGDLVFLG |
Invalid registered-delivery flag |
| 8 | ESME_RSYSERR |
SMSC system error |
| 10 | ESME_RINVSRCADR |
Invalid source address |
| 11 | ESME_RINVDSTADR |
Invalid destination address |
| 12 | ESME_RINVMSGID |
Invalid message-id |
| 13 | ESME_RBINDFAIL |
Generic bind failure |
| 14 | ESME_RINVPASWD |
Invalid password |
| 15 | ESME_RINVSYSID |
Invalid System-ID |
| 17 | ESME_RCANCELFAIL |
Cancel failure |
| 19 | ESME_RREPLACEFAIL |
Replace failure |
| 21 | ESME_RMSGQFUL |
Too many messages in queue, at present |
| 22 | ESME_RINVSERTYP |
Invalid services type |
| 51 | ESME_RINVNUMDESTS |
Invalid number of destination addresses |
| 52 | ESME_RINVDLNAME |
Invalid name |
| 64 | ESME_RINVDESTFLAG |
Invalid Destination Flag Option |
| 66 | ESME_RINVSUBREP |
Invalid value for submit with replace option |
| 67 | ESME_RINVESMCLASS |
Invalid value for esm_class field |
| 68 | ESME_RCNTSUBDL |
Cannot submit to a distribution list |
| 69 | ESME_RSUBMITFAIL |
Generic submission failure |
| 72 | ESME_RINVSRCTON |
Invalid type of number for source |
| 73 | ESME_RINVSRCNPI |
Invalid numbering plan indicator for source |
| 74 | ESME_RINVDSTTON |
Invalid type of number for destination |
| 75 | ESME_RINVDSTNPI |
Invalid numbering plan indicator for destination |
| 77 | ESME_RINVSYSTYP |
Invalid esm type |
| 78 | ESME_RINVREPFLAG |
Invalid submit with replace flag option |
| 85 | ESME_RINVNUMMSGS |
Invalid number of messages specified for query_last_msgs primitive |
| 88 | ESME_RTHROTTLED |
SMSC is throttling inbound messages |
| 97 | ESME_RINVSCHED |
Invalid Schedule Date |
| 98 | ESME_RINVEXPIRY |
Invalid Validity Date |
| 99 | ESME_RINVDFTMSGID |
Invalid sm_default_msg_id Parameter |
| 100 | ESME_RX_T_APPN |
ESME Receiver Temporary App Error Code |
| 101 | ESME_RX_P_APPN |
ESME Receiver Permanent App Error Code |
| 102 | ESME_RX_R_APPN |
ESME Receiver Reject Message Error Code |
| 103 | ESME_RQUERYFAIL |
Query failure |
| 192 | ESME_RINVOPTPARSTREAM |
Error in the optional TLV parameter encoding |
| 179 | ESME_FAILCREDIT |
Account has no available pre-pay credit |
| 180 | ESME_ACCDISABLED |
Account Disabled |
| 193 | ESME_ROPTPARNOTALLWD |
An optional TLV parameter was specified which is not allowed |
| 194 | ESME_RINVPARLEN |
Invalid optional parameter length |
| 195 | ESME_RMISSINGOPTPARAM |
Missing optional parameter |
| 196 | ESME_RINVOPTPARAMVAL |
Invalid optional parameter value |
| 254 | ESME_RDELIVERYFAILURE |
Generic delivery failure |
| 255 | ESME_RUNKNOWNERR |
Unknown Error |
Delivery report status description
| Status | Explanation |
|---|---|
ENROUTE |
The message is enroute. |
DELIVRD |
The message was successfully delivered. |
EXPIRED |
The SMSC was unable to deliver the message in a specified amount of time.For instance when the phone was turned off. |
DELETED |
The message was deleted. |
UNDELIV |
The SMS was unable to deliver the message.For instance, when the number does not exist. |
ACCEPTD |
The SMS was accepted and will be send. |
UNKNOWN |
Unknown error occured. |
REJECTD |
The message was rejected.The provider could have blocked phonenumbers in this range. |
HTTP(s) API
The HTTPs API implemented by Sequel Communication Platform provides a great, easy to use interface, that allows software developers to send and receive SMS messages. The following pages give you information on how to use this technology.
HTTP(s) API Activation
HTTPs API is activated by default on your account after you complete registration.
Connection settings
| Primary Host | Backup Host | |
|---|---|---|
api.sequel-tele.com |
api-backup.sequel-tele.com |
|
Port : HTTP |
1701 | 1701 |
Port : HTTPs |
1702 | 1702 |
To start using HTTP(s) API you need to whitelist your IP address in User panel Interface. Otherwise, the connection attempt will be rejected.
API Usage
In order to deliver messages, Data is transferred using HTTP GET/POST requests. Sequel SMSC gateway accepts requests at the following URL:
https://api.sequel-tele.com:1702/send for HTTPS connections
and
http://api.sequel-tele.com:1701/send for HTTP connections
Parameters
To send a message you need to send GET or POST request to the above URL with filled parameters from table below.
| Parameter | Value | Description / Notes |
|---|---|---|
| to | recipient |
Recipient's phone number |
| from | sender |
Sender id that will be displayed on the recipient's phone |
| coding | data_coding |
Data Coding Scheme bits. Default is 0. Accepts values all allowed values in SMPP protocol DSC |
| username | username |
API account username. |
| password | password |
API account password. |
| dlr | yes / no |
Tells our gateway whether to send a delivery report. If value is yes parameters dlr-url, dlr-level and dlr-method is mandatory. |
| dlr-url | HTTP(s) URL |
URL to which the delivery report will be sent if the dlr parameter is set to yes. |
| dlr-level | 1, 2 or 3 |
1: SMS-C level, 2: Terminal level, 3: Both |
| dlr-method | GET / POST |
Request method for delivery report link |
| content | text |
Message text |
Response
If all parameters are filled correctly, then you will receive response as in the example below.
Success "43a3fb54-7a02-11eb-9439-0242ac130002"
where 43a3fb54-7a02-11eb-9439-0242ac130002 is id of sent message for future tracking.
Delivery report
After your message was delivered you will get delivery report on URL set in dlr-url parameter. Request will contain parameters listed below.
| Parameter | Description / Notes |
|---|---|
id |
message-id which was sent in response to submit. |
message_status |
Message delivery status. All possible statuses listed in delivery statuses table of SMPP 3.4 documentation. |
subdate |
Time and date at which message was submitted. |
donedate |
Time and date at which the short message reached itâs final state |
sub |
Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list.The value is padded with leading zeros if necessary |
dlvrd |
Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list.The value is padded with leading zeros if necessary |
err |
Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message |
text |
- |