SMPP API Introduction

Access to our Mobile Messaging Routing Platform using the Short Message Peer to Peer (SMPP) protocol is available, this allows an applications to communicate with Short Message Service Centres (SMSC's) and Virtual Mobile platforms to perform one-way and two-way messaging between the application and SMS capable mobile devices.

Suitable for use with all standard SMPP applications as based on SMPP v3.3 / v3.4 protocols.

Setup SMPP To Send SMS on Your Account

SMPP is not enabled by default on accounts, you must contact us to request SMPP access.

SMPP is primarily aimed at high volume, high throughput bulk SMS uses. If you will send or receiving low to medium volumes, with low to medium throughput you may want to consider using our HTTP REST API.

SMPP is not available to trial accounts, after you have made your first purchase of SMS credits please contact us to have SMPP enabled.

SMPP activation normally takes no longer than 24 hours excluding weekends.

SMPP Interface

The SMPP protocol allows a client’s applications to access World-Text’s Mobile Message Routing Platform (MMRP) to send and/or receive SMS.

The application should implement the SMPP protocol (version 3.3 or 3.4) to communicate with World-Text’s systems.

SMPP Interface Specifications

SMSC SMPP Simulator

We have an SMSC simulator running on our servers, this provides full FREE access to our SMPP interface for testing and integration. If you would like to verify your application against our simulator simply contact us and we will send you the connection details required.

Please note, the simulator is NOT a protocol verifier, neither does it deliver messages. It simply responds appropriately to the SMPP commands that our service supports.

For a protocol verifier we suggest WireShark.

SMPP Interface API

SMPP Interface Specification

SMPP interface specification technical manual. Provision of services is dependent upon compliance with the specifications set forth herein. The information in this document is subject to change without notice. Although World Text has taken reasonable steps to ensure the accuracy and completeness of this document, it shall not be liable for any losses whatsoever, whether direct or indirect, including without limitation and loss of profit, loss of use, or loss of data, as a result of any errors or omissions contained herein . The information or statements in this document concerning the specification or performance of World Text software or hardware systems shall not constitute any binding promise or warranty.

Connection Settings

Host and Port Information:

Host/Portname Primary Host * Backup Host
Hostname smpp1.world-text.com smpp2.world-text.com
TRX Port 2775 2775
TRX SSL Port 2776 2776

Please check back regularly with the World-Text web site for updates to this information as we add additional SMPP resilience to our network.

* Backup Host connections are only available to invoiced clients, pre-pay clients may only connect to the primary host.

Simulator Host and Port Information

Hostname smpp1.world-text.com
TRX Port 12775

Enquire link

Enquire Links to our server should be sent no more than once in every 60 second period.

Multi-binds

If you require multi-binds, by default this is not enabled. Please contact the Support Team to discuss your needs.

SMS Throughput

Accounts should not submit any faster than 10 SMS/sec, if you require higher throughput please contact the Support Team to discuss your needs.

Character Set Support

Character set support is restricted to GSM and Unicode as this is the common subset supported by carriers and networks that we connect to.

To send characters in GSM simply leave the Data Coding field of the Submit SM packets as unset (0). For Unicode the Data Coding needs to be set to 8 and the Short Message encoded in UCS-2.

Custom Status Values

In addition to the standard SMPP status values returned in SMPP Message Header, the following are also valid vendor-specific values.

Value Meaning
0x400 Insufficient credit remaining on pre-pay account or credit limit has been reached (invoiced accounts).

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. The delivery receipt data relating to the original SMS will be included in the short_message field of the deliver_sm.

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 C-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 it’s 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 page.
err 3 C-Octet Fixed Length String Any error code of the message. See Message States and Error Codes page.
text 20 Octet String Unused feature, result will be blank.
id:123A456B sub:1 dlvrd:1 submit date:1702281424 done date:1702281424 stat:DELIVRD err:0 text:
Optional Parameter Description
0x1511 Within the optional parameters return in the SMPP delivery receipt, hex value 0x511, a numeric value of 5 or 6 digits with indicates which network the destination number belongs to. This is what's known as the E.212 code or MCC/MNC (Mobile Country Code / Mobile Network Code, for reference you can see these values on our coverage page. This information will only be returned when the message reaches it's final state.

Please note, this functionality is not available for all destinations / networks, in the event the information is not available the content returned for MCC/MNC will be '000000'.

The e212 optional parameter functionality for delivery receipts must be requested to be enabled on your account, please contact us to request this.

.

Our servers dispatch Enquire Link PDUs every 90 seconds, if a correctly sequenced Enquire Link Response PDU is not received, the link will be disconnected without an Unbind request and the socket closed.

Enquire Links to our server should be sent no more than once in every 60 second period.

Optional Parameters

Optional parameters (v3.4) are not supported, this is due to the lack of support by operators that we connect to.

Server Rebinds

In the event of receiving an Unbind Request from the server, you should acknowledge the request with and Unbind Response and Disconnect. If they do not disconnect, the connections are forceably closed, once disconnected your application should automatically rebind to the server, the frequency of rebinds should not be more than once every 30 seconds.

SMPP Commands

The Following List Contains All of the Commands Supported By Our API

  • Bind Transmitter
  • Bind Transmitter Response
  • Bind Receiver
  • Bind Receiver Response
  • Bind Transceiver
  • Bind Transceiver Response
  • Unbind
  • Unbind Response
  • Submit SM
  • Submit SM Response
  • Deliver SM
  • Deliver SM Response
  • Enquire Link
  • Enquire Link Response
  • Generic Nack

- Additional commands may be supported if requested.

SMPP Server Restarts

From time to time the SMPP server is restarted to allow for upgrades and configuration changes, although we try to keep these to a minimum, they are required.

During a restart, clients are disconnected and all Submit SM PDUs that have been successfully responded to with a Submit SM Response, but have not yet been dispatched, are cached to disk. On start-up these data files are reloaded so that no submitted data is lost.

SMPP Version

The provided SMPP support is SMPP version 3.3 and a cut down version 3.4, the full SMPP specification can be downloaded from the World-Text web site at www.world-text.com/docs and www.smpp.orgfor the 3.4 specification. Version 5.0 SMPP support is currently unplanned. More information on SMPP and additional documentation can be obtained by searching the internet.

The SMPP Version must always be set to either 0x33 (hex 33) for version 3.3 or 0x34 (hex 34) for version 3.4. If this is not set, your bind will be rejected.

Source Addresses

When the SMPP account is activated it is created only to allow transit of messages with the alphanumeric source address SMSAlert. If you require to use a different source address then please see the information on our web site to request additional source addresses.

System ID and Password

The System ID is made up of the two characters sm and your account ID (unless otherwise specified to you upon SMPP being enabled on your account), this account ID can be found on the account administration page which can be accessed by logging into your account at www.world-text.com

Account ID: 1000

System ID: sm1000

The password is not the same as your web portal login, if you need to change the password it can be done so via the 'Configuration' tab of your account's dashboard here.

Currently SMPP accounts need to be activated by World-Text support who you should contact at support@world-text.com.

System Type

The System Type should always be set to: SMPP

TON and NPI Settings

When creating your SMPP packets for alphanumeric source addresses you should use a Type of Number setting of 5 and a Numbering Plan Indicator of 6.

For your destination address the TON and NPI should both be set to 1

SMPP Command ID Values

ID Value Description
0x80000000 ESME_NACK Negative Acknowledgement
0x00000001 ESME_BNDRCV Bind to SMSC Kernel as a receiver
0x80000001 ESME_BNDRCV_RESP Response to bind_receiver
0x00000002 ESME_BNDTRN Bind to SMSC Kernel as transmitter
0x80000002 ESME_BNDTRN_RESP Response to bind_transmitter
0x00000003 ESME_QUERY_SM Query status of a short-message
0x80000003 ESME_QUERY_SM_RESP Response to query_sm
0x00000004 ESME_SUB_SM Submit a short-message
0x80000004 ESME_SUB_SM_RESP Response to submit_sm
0x00000005 SMSC_DELIVER_SM Submit a short-message to ESME
0x80000005 SMSC_DELIVER_SM_RESP Response to deliver_sm
0x00000006 ESME_UBD Unbind from SMSC Kernel
0x80000006 ESME_UBD_RESP Response to unbind
0x00000007 ESME_REPLACE_SM Replace a short message
0x80000007 ESME_REPLACE_SM_RESP Response to replace_sm
0x00000008 ESME_CANCEL_SM Cancel a short message(s)
0x80000008 ESME_CANCEL_SM_RESP Response to cancel_sm
0x00000009 ESME_BIND_TRANSCEIVER Bind to SMSC Kernel as transmitter
0x80000009 ESME_BIND_TRANSCEIVER_RESP Response to bind_transmitter
0x0000000B SMSC_OUTBIND An outbind request to remote server
0x00000015 ESME_QRYLINK Link confidence check
0x80000015 ESME_QRYLINK_RESP Response to enquire_link
0x00000021 ESME_SUB_MULTI Submit a short message to
an SME Address
a Distribution list
Multiple Recipients
0x80000021 ESME_SUB_MULTI_RESP Respose to submit_multi.
0x00000102 SMSC_ALERT_NOTIFICATION Notifcation that a device is read to receive messages
0x00000103 ESME_DATA_SM Submit a short data message
0x80000103 ESME_DATA_SM_RESP Response to data_sm

Add text messaging and two-way text messaging into your business.

Over 1100+ networks worldwide.

Market leading coverage and specialist support, HTTP, SMPP and SMTP (Email) interfaces.

Easy Use APIs
HTTP, SMPP & SMTP

Premium Support
20+ Years Experience

Free Cloud SMS Software
Communicator Pro

Auto Responder
Auto SMS Processing

Create FREE account  

SMPP Error Codes

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