SMPP API
Introduction
IMIconnect supports SMPP (Short Messaging Peer to Peer) apart from HTTP protocol. SMPP (Short Messaging Peer to Peer) protocol is an open, industry-standard protocol designed to provide a flexible data communication interface for the transfer of short message data between External Short Message Entities (ESME) (enterprises), Routing Entities (RE) (IMIconnect), and Short Message Service Center (SMSE) (telecom operators).
With an SMPP connection, the client is continuously connected to the imiconnect gateway. The SMPP protocol allows you to send large volumes of SMS messages in a short period of time as it provides a direct connection to IMIconnect messaging gateway.
Prerequisites
Following are the prerequisites to use SMPP protocol:
| Component | Description |
|---|---|
| IMIconnect account | An active account on IMIconnect platform. |
| SMPP account | An SMPP account must be created for a client on IMIconnect platform. |
| SMPP Protocol version 3.3 and 3.4 | A thorough understanding of the SMPP protocol is required. |
| SMPP client | You must have SMPP client installed. |
| A number in IMIconnect (optional) | A number must be purchased and configured in IMIconnect to receive MOs. |
Get an SMPP account
You should contact the support team and request for an SMPP account. You may be asked to provide your account details. After successful creation of the SMPP account, you will be provided with a domain name, username, and password.
Send SMS using SMPP
To send an SMS using SMPP protocol, you must use the account details created for SMPP account.
The following PDUs (Protocol Data Units) are supported by the IMIconnect SMPP server:
| PDUs | Description and Functionality |
|---|---|
| BIND_TRANSMITTER | Used to send only SMS (binary, unicode, and text format) messages. |
| BIND_TRANSMITTER_RESP | Used to provide an SMSC response to a BIND_TRANSMITTER request. |
| BIND_RECEIVER | Used to receive SMS messages. The delivery status of the SMS is also received using this account. |
| BIND_RECEIVER_RESP | Used to provide an SMSC response to a BIND_RECEIVER request. |
| BIND_TRANSCEIVER | Used to send and receive SMS messages. |
| BIND_TRANSCEIVER_RESP | Used to provide an SMSC response to a BIND_TRANSCEIVER request. |
| SUBMIT_SM | Used to submit a single message from the enterprise to the SMSC. This PDU contains the sender and recipient address and the message body. |
| SUBMIT_SM_RESP | Used to submit message response. |
| DELIVER_SM | Used to deliver messages to the client. It contains information about the sender of the message and the message body. This PDU is also used to send delivery reports to the ESME. |
| DELIVER_SM_RESP | Used to deliver the short message response. |
| ENQUIRE_LINK | Used to check if the connection is still alive once in every x minutes. If not, the connection is terminated. This PDU is also used to keep dial-up connections alive. |
| ENQUIRE_LINK_RESP | Used to enquire link response. |
Concatenated Messages
In this method a long message is sent in parts as multiple short messages are then joined together on the mobile if the mobile supports long messages. Else each message part will be displayed as a separate message. In this method the client sends the UDH (User Data Header) as part of the short_message field.
On SMPP:submit_sm the UDHI (User Data Header Indicator) in the esm_class parameter must be set:
esm_class = 0x40
The concatenation UDH values are inserted at the start of the message body.
Example:
Message 1 (UDH+UD should not exceed 160 bytes):
esm_class=0x40
short_message = 0x05 0x00 0x03 0x05 0x02 0x01 LG also announced its latest TVs would support four HDR formats - including Hybrid Log-Gamma jointly developed by the BBC and the Japanese broadcaster
Message 2 (UDH+rest of the message):
esm_class=0x40
short_message = 0x05 0x00 0x03 0x05 0x02 0x02 NHK. This will allow sport and other live broadcasts to be shown in the format.
Concatenation UDH structure:
| Byte | Description |
|---|---|
| 05 | Length of UDH (5 bytes) |
| 00 | Indicator for concatenated message |
| 03 | Subheader Length (3 bytes) |
| xx | message identification - can be any hexadecimal number that matches with the UDH Reference Number of all concatenated SMS. |
| YY | Number of pieces of the concatenated message. |
| ZZ | Sequence number (used by the mobile to concatenate the split messages) |
The maximum number of characters per concatenated message depends on the encoding:
- 67 characters for 16-bit encoding (Unicode)
- 134 characters for 8-bit encoding (Binary)
- 153 characters for 7-bit encoding (Example Latin-1/9 and GSM8)
Receive SMS through SMPP
The SMPP server will forward the inbound/reply (MO) messages sent to numbers allocated to your account via the active SMPP bind. To forward these messages, the SMPP server will issue the SMPP request.
Messages will only be forwarded over SMPP sessions with BIND_RECEIVER or BIND_TRANSCEIVER mode.
Follow these steps to receive SMS:
- From your IMIconnect account, purchase a number.
- Create a service and configure the purchased number in your service.
- Under the General settings of your service, configure INBOUND SETTINGS with the URL as
smpp://. - Click SAVE.
All the SMS messages coming to the purchased number will be forwarded to the SMPP client through SMPP server.
Receive DR
To receive a DR you should take BIND_TRANSCEIVER so that all DRs will be notified to the SMPP client through SMPP server.
Example:
id:1_14839433040000 sub:001 submit date:170100935 done date:170100940 stat:DELIVRD err:000 text:"Sending SMS through SMPP "
| Field | Description |
|---|---|
| id | The message ID allocated to the message by the IMIconnect gateway when originally submitted. |
| sub | The number of short messages originally submitted. |
| submit date | The date and time at which the short message was submitted in YYMMDDhhmm. |
| done date | The date and time at which the short message reached its final state in YYMMDDhhmm. |
| stat | The final status of the message. |
| err | The SMPP error code. |
| text | Part of the original text message. |
Submission Failure Error Codes
IMIconnect SMPP server returns the following error codes on submission failure:
| Error Code | Error Name | Error Description |
|---|---|---|
| 0x00000000 | ESME_ROK | No Error |
| 0x00000001 | ESME_RINVMSGLEN | Message Length is too long |
| 0x00000002 | ESME_RINVCMDLEN | Command length is invalid |
| 0x00000003 | ESME_RINVCMDID | Command ID is invalid or not supported |
| 0x00000004 | ESME_RINVBNDSTS | Incorrect bind status for given command |
| 0x00000005 | ESME_RALYBND | ESME Already in Bound State |
| 0x00000006 | ESME_RINVPRTFLG | Invalid Priority Flag |
| 0x00000007 | ESME_RINVREGDLVFLG | Invalid registered delivery flag |
| 0x00000008 | ESME_RSYSERR | System error |
| 0x0000000A | ESME_RINVSRCADR | Invalid source address |
| 0x0000000B | ESME_RINVDSTADR | Invalid destination address |
| 0x0000000D | ESME_RBINDFAIL | Bind failed |
| 0x0000000E | ESME_RINVPASWD | Invalid password |
| 0x0000000F | ESME_RINVSYSID | Invalid System ID |
| 0x00000014 | ESME_RMSSQFUL | Message queue full |
| 0x00000043 | ESME_RINVESMCLASS | Invalid esm class field data |
| 0x00000058 | ESME_RTHROTTLED | Throttling error (ESME has exceeded allowed message limits) |
| 0x00000061 | ESME_RINVSCHED | Invalid scheduled delivery time |
| 0x00000062 | ESME_RINVEXPIRY | Invalid message validity period(Expiry time) |
| 0x000000C0 | ESME_RINVTLVSTREAM | Error in the optional part of the PDU body |
| 0x000000C2 | ESME_RINVTLVLEN | Invalid parameter length |
| 0x000000FE | ESME_RDELIVERYFAILURE | Transaction delivery failure |
| 0x000000FF | ESME_RUNKNOWNERR | Unknown error |
Delivery Report Error Codes
Following are the Delivery Report error codes returned by IMIconnect:
| IMIconnect code | Description |
|---|---|
| 2 | Delivered to Network (final) |
| 3 | Delivered to Network (Intermediate) |
| 4 | Operator is Retrying Message |
| 5 | Delivered to Phone |
| 6 | Failed @ operator |
| 10 | Formatting Error SMS too long |
| 11 | Unknown Subscriber |
| 12 | Insufficient Credit |
| 13 | Subscriber Barred |
| 14 | Incorrect Billing C2 |
| 15 | Invalid Originator |
| 16 | Message Expired @ Gateway |
| 17 | Invalid Expiry Value |
| 18 | Duplicate Message |
| 19 | Out of Credit. Billing system busy or prepay message already in pipe. |
| 20 | Zero length data |
| 21 | Binary too long |
| 22 | Binary incorrect format |
| 23 | Sim full |
| 24 | Absent subscriber |
| 25 | Error in delivery to operator |
| 26 | Message expired @ operator |
| 27 | Not defined - status unknown |
| 99 | SMS delivery receipt timeout |
| 101 | Multipart delivered to Network - Partial success |
| 102 | Multipart Delivered to Network - Total Failure |
Updated about 3 years ago