IMIconnect Developer Hub

Welcome to the IMIconnect developer hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started

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).

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 IMIconnect operations 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:

  1. From your IMIconnect account, purchase a number.
  2. Create a service and configure the purchased number in your service.
  3. Under the General settings of your service, configure INBOUND SETTINGS with the URL as smpp://.
  4. 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