SMPP Connector Reference

The following operations allow you to work with the SMPP Connector. Click an operation name to see parameter details and samples on how to use it.

Create SMSC Connection

To use the SMPP connector, need to have a SMSC connection. To create a SMSC connection add the <SMPP.init> element as a local entry configuration before carrying out any other SMPP operation. This is used to bind with the SMSC (Short Message service center). Once a connection is defined this can be reused among other SMPP operators.

init

The init operation appends content to an existing file in a specified location.

Parameter Name Description Required
host IP address of the SMSC. Yes
port Port to access the SMSC. Yes
systemId username to access the SMSC. Yes
password password to access the SMSC. Yes
enquireLinkTimer Used to check the connectivity between the SMPP connector and SMSC. Optional
transactionTimer Time elapsed between SMPP connector request and corresponding response. Optional
systemType It is used to categorize the type of ESME that is binding to the SMSC. Examples include “CP” (Content providers), “VMS” (voice mail system) and “OTA” (over-the-air activation system). Optional
addressTon Indicates Type of Number of the ESME address. Optional
addressNpi Numbering Plan Indicator for ESME address. Optional

Sample configuration

  <?xml version="1.0" encoding="UTF-8"?>
  <localEntry key="SMSC_CONFIG_1" xmlns="http://ws.apache.org/ns/synapse">
     <SMPP.init>
        <host>{$ctx:host}</host>
        <port>{$ctx:port}</port>
        <systemId>{$ctx:systemId}</systemId>
        <password>{$ctx:password}</password>
        <enquireLinkTimer>{$ctx:enquireLinkTimer}</enquireLinkTimer>
        <transactionTimer>{$ctx:transactionTimer}</transactionTimer>
        <systemType>{$ctx:systemType}</systemType>
        <addressTon>{$ctx:addressTon}</addressTon>
        <addressNpi>{$ctx:addressNpi}</addressNpi>
        <connectionType>init</connectionType>
        <name>SMSC_CONFIG_1</name>
     </SMPP.init>
  </localEntry>

Sample request

Following is a sample REST/JSON request that can be handled by the init operation. 

{
  "host": "127.0.0.1",
  "port": 2775,
  "systemId": "DAMIEN",
  "password": "neimad",
  "systemType": "UNKNOWN",
  "addressTon": "UNKNOWN",
  "addressNpi": "UNKNOWN",
  "enquireLinkTimer": "50000",
}

Send SMS Message

sendSMS

Use to send SMS Message to the SMSC (Short Message Service Center),

Parameter Name Description Required
serviceType Indicates SMS application service. The following generic service_types are defined:
"" (NULL) Default
"CMT" Cellular Messaging
"CPT" Cellular Paging
"VMN" Voice Mail Notification
"VMA" Voice Mail Alerting
"WAP" Wireless Application Protocol
"USSD" Unstructured Supplementary Services Data
Optional
sourceAddressTon Type of number for source address. Optional
sourceAddressNpi Numbering plan indicator for source address. Optional
sourceAddress Source address of the SMS message. Yes
destinationAddressTon Type of number for destination. Used as a default for the destination address. Optional
destinationAddressNpi numbering plan indicator for destination. Optional
destinationAddress Destination address of the SMS message. Source address TON, Destination address TON
TON VALUE
Unknown 0
International 1
National 2
Network Specific 3
Subscriber Number 4
Alphanumeric 5
Abbreviated 6
All other values reserved
Source address NPI, Destination address NPI
NPI VALUE
Data (X.121) 2
ERMES 16
Internet (IP) 20
ISDN (E163/E164) 1
Land Mobile (E.212) 4
National 8
Private 9
Telex (F.69) 3
Unknown 0
WAP Client Id (to be defined by WAP Forum) 24
Yes
message Content of the SMS message. Yes
esmClass The esmClass parameter is used to indicate special message attributes associated with the short Message(message mode and type).
Bits 7 6 5 4 3 2 1 Meanning
x x x x x x 0 0
x x x x x x 0 1
x x x x x x 1 0
x x x x x x 1 1
 Messaging Mode (bits 1-0)
Default SMSC Mode (e.g. Store and Forward)
Datagram mode
Forward (i.e. Transaction) mode
Store and Forward mode
(use to select Store and Forward mode if Default SMSC Mode is non Store and Forward)
x x 0 0 0 0 x x
x x 0 0 1 0 x x
x x 0 1 0 0 x x
 Message Type (bits 5-2)
Default message Type (i.e. normal message)
Short Message contains ESME Delivery Acknowledgement
Short Message contains ESME Manual/User Acknowledgement
0 0 x x x x x x
0 1 x x x x x x
1 0 x x x x x x
1 1 x x x x x x
 GSM Network Specific Features (bits 7-6)
No specific features selected
UDHI Indicator (only relevant for MT short messages)
Set Reply Path (only relevant for GSM network)
Set UDHI and Reply Path (only relevant for GSM network)
Optional
protocolId protocol identifier (network specific).
GSM - Set according to GSM 03.40 [ GSM 03.40]
ANSI-136 (TDMA)
For mobile terminated messages, this field is not used and is therefore ignored by the SMSC.
For ANSI-136 mobile originated messages, the SMSC should set this value to NULL.
IS-95 (CDMA)
For mobile terminated messages, this field is not used and is therefore ignored by the SMSC.
For IS-95 mobile originated messages, the SMSC should set this value to NULL.
 Optional
priorityFlag sets the priority of the message. All other values reserved
Priority Level GSM ANSI-136 IS-95
0 Non-priority Bulk Normal
1 Priority Normal Interactive
2 Priority Urgent Urgent
3 Priority Very Urgent Emergency
Priority
There are two types of priority.
  1. Delivery priority - Message delivery is attempted even if the mobile is temporarily absent. E.g., Temporarily out of reach or another short message is being delivered at the same time.
  2. Content priority - No free message memory capacity. E.g., The user does not delete any received message and maximum storage space has been reached.
Non-priority
It will attempt delivery if the mobile has not been identified as temporarily absent. 		Optional
scheduleDeliveryTime This parameter specifies the scheduled time at which the message delivery should be first attempted. Set to NULL for immediate delivery. Optional
validityPeriod The validity_period parameter indicates the SMSC expiration time, after which the message should be discarded if not delivered to the destination. It can be defined in absolute time format or relative time format. Optional
registeredDelivery Indicator to signify if an SMSC delivery receipt or acknowledgment is required - Value other than 0 represents delivery report request. Optional
validityPeriod The validity_period parameter indicates the SMSC expiration time, after which the message should be discarded if not delivered to the destination. It can be defined in absolute time format or relative time format. Optional
replaceIfPresentFlag The replace_if_present_flag parameter is used to request the SMSC to replace a previously submitted message, that is still pending delivery. The SMSC will replace an existing message provided that the source address, destination address and service_type match the same fields in the new message.
Value Description
0 Don't replace (default)
1 Replace
2-255 reserved
Optional
alphabet Alphabet is used in the data encoding of SMS message. Following alphabets are supported.
  1. ALPHA_DEFAULT
  2. ALPHA_8_BIT
  3. ALPHA_UCS2
  4. ALPHA_RESERVED
 Optional
charset Charset is used when decoding the message in SMSC. Following charsets are supported.
  1. UTF-8
  2. UTF-16
 Optional
isCompressed It allows SMS message compression. Optional
messageClass
Value Message Class
CLASS0 Flash messages. Display only not store into the phone
CLASS1 ME specific - the SMS is stored in the mobile phone memory
CLASS2 SIM specific - the SMS is stored on the SIM
CLASS3 TE specific - this means the SMS is sent to a computer attached to the receiving mobile phone
Data encoding - defines the encoding scheme of the SMS message. You can find general data coding scheme from here for different combination of alphabet, message class, isCompressed values. 		Optional
submitDefaultMsgId Indicates short message to send from a predefined list of messages stored on SMSC.
Value Description
0 reserved
1 - 254 Allowed values
255 reserved
Optional

Sample configuration

<SMPP.sendSMS configKey="SMSC_CONFIG_1">
  <serviceType>{$ctx:serviceType}</serviceType>
  <sourceAddressTon>{$ctx:sourceAddressTon}</sourceAddressTon>
  <sourceAddressNpi>{$ctx:sourceAddressNpi}</sourceAddressNpi>
  <sourceAddress>{$ctx:sourceAddress}</sourceAddress>
  <destinationAddressTon>{$ctx:destinationAddressTon}</destinationAddressTon>
  <destinationAddressNpi>{$ctx:destinationAddressNpi}</destinationAddressNpi>
  <destinationAddress>{$ctx:destinationAddress}</destinationAddress>
  <alphabet>{$ctx:alphabet}</alphabet>
  <charset>{$ctx:charset}</charset>
  <message>{$ctx:message}</message>
  <smscDeliveryReceipt>{$ctx:smscDeliveryReceipt}</smscDeliveryReceipt>
  <messageClass>{$ctx:messageClass}</messageClass>
  <isCompressed>{$ctx:isCompressed}</isCompressed>
  <esmclass>{$ctx:esmclass}</esmclass>
  <protocolid>{$ctx:protocolid}</protocolid>
  <priorityflag>{$ctx:priorityflag}</priorityflag>
  <replaceIfPresentFlag>{$ctx:replaceIfPresentFlag}</replaceIfPresentFlag>
  <submitDefaultMsgId>{$ctx:submitDefaultMsgId}</submitDefaultMsgId>
  <validityPeriod>{$ctx:validityPeriod}</validityPeriod>
</SMPP.sendSMS>

Sample request

Following is a sample REST/JSON request that can be handled by the sendSMS operation. 

{
  "serviceType": "CMT",
  "sourceAddressTon": "NETWORK_SPECIFIC",
  "sourceAddressNpi": "INTERNET",
  "sourceAddress": "16116",
  "destinationAddressTon": "SUBSCRIBER_NUMBER",
  "destinationAddressNpi": "LAND_MOBILE",
  "destinationAddress": "628176504657",
  "messageClass":"CLASS1",
  "alphabet": "ALPHA_DEFAULT",
  "charset": "UTF-8",
  "isCompressed":"true",
  "esmclass": "0",
  "protocolid": "0",
  "priorityflag":"1",
  "replaceIfPresentFlag": "0",
  "submitDefaultMsgId": "1",
  "validityPeriod": “020610233429000R”,
  "message": "hi hru",
  "smscDeliveryReceipt": "SUCCESS_FAILURE",
  "enquireLinkTimer": "50000",
  "transactionTimer": "100"
}

Sample configuration in a scenario

The following is a sample proxy service that illustrates how to connect to the SMPP connector and use the sendSMS operation to send a SMS message to the SMSC (Short Message Service Center). You can use this sample as a template for using other operations in this category.

Sample Proxy 

<proxy xmlns="http://ws.apache.org/ns/synapse"
      name="SMPP"
      transports="http,https,local"
      statistics="disable"
      trace="disable"
      startOnLoad="true">
   <target>
       <inSequence>
           <property name="OUT_ONLY" value="true"/>
           <property name="serviceType" expression="json-eval($.serviceType)"/>
           <property name="sourceAddressTon" expression="json-eval($.sourceAddressTon)"/>
           <property name="sourceAddressNpi" expression="json-eval($.sourceAddressNpi)"/>
           <property name="sourceAddress" expression="json-eval($.sourceAddress)"/>
           <property name="destinationAddressTon" expression="json-eval($.destinationAddressTon)"/>
           <property name="destinationAddressNpi" expression="json-eval($.destinationAddressNpi)"/>
           <property name="destinationAddress" expression="json-eval($.destinationAddress)"/>
           <property name="alphabet" expression="json-eval($.alphabet)"/>
           <property name="message" expression="json-eval($.message)"/>
           <property name="smscDeliveryReceipt" expression="json-eval($.smscDeliveryReceipt)"/>
           <property name="messageClass" expression="json-eval($.messageClass)"/>
           <property name="isCompressed" expression="json-eval($.isCompressed)"/>
           <property name="esmclass" expression="json-eval($.esmclass)"/>
           <property name="protocolid" expression="json-eval($.protocolid)"/>
           <property name="priorityflag" expression="json-eval($.priorityflag)"/>
           <property name="replaceIfPresentFlag" expression="json-eval($.replaceIfPresentFlag)"/>
           <property name="submitDefaultMsgId" expression="json-eval($.submitDefaultMsgId)"/>
           <property name="validityPeriod" expression="json-eval($.validityPeriod)"/>
           <property name="enquireLinkTimer" expression="json-eval($.enquireLinkTimer)"/>
           <property name="transactionTimer" expression="json-eval($.transactionTimer)"/>
           <SMPP.sendSMS configKey="SMSC_CONFIG_1">
               <serviceType>{$ctx:serviceType}</serviceType>
               <sourceAddressTon>{$ctx:sourceAddressTon}</sourceAddressTon>
               <sourceAddressNpi>{$ctx:sourceAddressNpi}</sourceAddressNpi>
               <sourceAddress>{$ctx:sourceAddress}</sourceAddress>
               <destinationAddressTon>{$ctx:destinationAddressTon}</destinationAddressTon>
               <destinationAddressNpi>{$ctx:destinationAddressNpi}</destinationAddressNpi>
               <destinationAddress>{$ctx:destinationAddress}</destinationAddress>
               <alphabet>{$ctx:alphabet}</alphabet>
               <charset>{$ctx:charset}</charset>
               <message>{$ctx:message}</message>
               <smscDeliveryReceipt>{$ctx:smscDeliveryReceipt}</smscDeliveryReceipt>
               <messageClass>{$ctx:messageClass}</messageClass>
               <isCompressed>{$ctx:isCompressed}</isCompressed>
               <esmclass>{$ctx:esmclass}</esmclass>
               <protocolid>{$ctx:protocolid}</protocolid>
               <priorityflag>{$ctx:priorityflag}</priorityflag>
               <replaceIfPresentFlag>{$ctx:replaceIfPresentFlag}</replaceIfPresentFlag>
               <submitDefaultMsgId>{$ctx:submitDefaultMsgId}</submitDefaultMsgId>
               <validityPeriod>{$ctx:validityPeriod}</validityPeriod>
           </SMPP.sendSMS>
           <respond/>
       </inSequence>
   </target>
   <description/>
</proxy>
Note: For more information on how this works in an actual scenario, see SMPP Connector Example.

Send bulk SMS message

sendBulkSMS

Used to send SMS messages to multiple destinations.

Parameter Name Description Required
serviceType Indicates the SMS application service used. The following generic service_types are defined:
"" (NULL) Default
"CMT" Cellular Messaging
"CPT" Cellular Paging
"VMN" Voice Mail Notification
"VMA" Voice Mail Alerting
"WAP" Wireless Application Protocol
"USSD" Unstructured Supplementary Services Data
Optional
sourceAddressTon Type of number for source address. Optional
sourceAddressNpi Numbering plan indicator for source address. Optional
sourceAddress Source address of the SMS message. Yes
destinationAddresses Destination addresses can be defined in the following 3 formats.
  1. Default Values: Default numbering plan and type will be added for all numbers
    2. {"mobileNumbers": ["+94715XXXXXX", "+1434XXXXXX"]}
  2. Custom numbering plan and type for all numbers. The specified plan and type will be set to all numbers.
    3.   {
    "type": "NATIONAL",
    "numberingPlan":"NATIONAL",
    "mobileNumbers": [
        "+94713089759",
        "+189718674"
    ]
  }
  3. Each number is assigned different properties. Numbers without the properties will be assigned default values (You can set a custom type and numbering plan as default, as mentioned in the previous format). Properties can be set to numbers individually.
    4.   {
  "mobileNumbers": 
  ["+9471XXXXXX", "+189718674",{ "type": "INTERNATIONAL", "numberingPlan": "NATIONAL", "mobileNumber": "222333" }]
  }
Yes
message Content of the SMS message. Yes
esmClass The esmClass parameter is used to indicate special message attributes associated with the short Message (message mode and type).
Bits 7 6 5 4 3 2 1 Meanning
x x x x x x 0 0
x x x x x x 0 1
x x x x x x 1 0
x x x x x x 1 1
 Messaging Mode (bits 1-0)
Default SMSC Mode (e.g. Store and Forward)
Datagram mode
Forward (i.e. Transaction) mode
Store and Forward mode
(use to select Store and Forward mode if Default SMSC Mode is non Store and Forward)
x x 0 0 0 0 x x
x x 0 0 1 0 x x
x x 0 1 0 0 x x
 Message Type (bits 5-2)
Default message Type (i.e. normal message)
Short Message contains ESME Delivery Acknowledgement
Short Message contains ESME Manual/User Acknowledgement
0 0 x x x x x x
0 1 x x x x x x
1 0 x x x x x x
1 1 x x x x x x
 GSM Network Specific Features (bits 7-6)
No specific features selected
UDHI Indicator (only relevant for MT short messages)
Set Reply Path (only relevant for GSM network)
Set UDHI and Reply Path (only relevant for GSM network)
Optional
protocolId protocol identifier (network specific).
GSM - Set according to GSM 03.40 [ GSM 03.40]
ANSI-136 (TDMA)
For mobile terminated messages, this field is not used and is therefore ignored by the SMSC.
For ANSI-136 mobile originated messages, the SMSC should set this value to NULL.
IS-95 (CDMA)
For mobile terminated messages, this field is not used and is therefore ignored by the SMSC.
For IS-95 mobile originated messages, the SMSC should set this value to NULL.
 Optional
priorityFlag sets the priority of the message. All other values reserved
Priority Level GSM ANSI-136 IS-95
0 Non-priority Bulk Normal
1 Priority Normal Interactive
2 Priority Urgent Urgent
3 Priority Very Urgent Emergency
Priority
There are two types of priority.
  1. Delivery priority - Message delivery is attempted even if the mobile is temporarily absent. E.g., Temporarily out of reach or another short message is being delivered at the same time.
  2. Content priority - No free message memory capacity. E.g., The user does not delete any received message and maximum storage space has been reached.
Non-priority
It will attempt delivery if the mobile has not been identified as temporarily absent. 		Optional
scheduleDeliveryTime This parameter specifies the scheduled time at which the message delivery should be first attempted. Set to NULL for immediate delivery. Optional
validityPeriod The validity_period parameter indicates the SMSC expiration time, after which the message should be discarded if not delivered to the destination. It can be defined in absolute time format or relative time format. Optional
registeredDelivery Indicator to signify if an SMSC delivery receipt or acknowledgment is required - Value other than 0 represents delivery report request. Optional
validityPeriod The validity_period parameter indicates the SMSC expiration time, after which the message should be discarded if not delivered to the destination. It can be defined in absolute time format or relative time format. Optional
replaceIfPresentFlag The replace_if_present_flag parameter is used to request the SMSC to replace a previously submitted message, that is still pending delivery. The SMSC will replace an existing message provided that the source address, destination address and service_type match the same fields in the new message.
Value Description
0 Don't replace (default)
1 Replace
2-255 reserved
Optional
alphabet Alphabet is used in the data encoding of SMS message. Following alphabets are supported.
  1. ALPHA_DEFAULT
  2. ALPHA_8_BIT
  3. ALPHA_UCS2
  4. ALPHA_RESERVED
 Optional
charset Charset is used when decoding the message in SMSC. Following charsets are supported.
  1. UTF-8
  2. UTF-16
 Optional
isCompressed It allows SMS message compression. Optional
messageClass
Value Message Class
CLASS0 Flash messages. These are display only and not stored in the phone
CLASS1 ME specific - the SMS is stored in the mobile phone memory
CLASS2 SIM specific - the SMS is stored on the SIM
CLASS3 TE specific - this means the SMS is sent to a computer attached to the receiving mobile phone
Data encoding - defines the encoding scheme of the SMS message. You can find general data coding scheme from here for different combination of alphabet, message class, isCompressed values. 		Optional
submitDefaultMsgId Indicates a short message to send from a predefined list of messages stored on SMSC.
Value Description
0 reserved
1 - 254 Allowed values
255 reserved
Optional

Sample configuration

<SMPP.sendBulkSMS configKey="SMSC_CONFIG_1">
  <serviceType>{$ctx:serviceType}</serviceType>
  <sourceAddressTon>{$ctx:sourceAddressTon}</sourceAddressTon>
  <sourceAddressNpi>{$ctx:sourceAddressNpi}</sourceAddressNpi>
  <sourceAddress>{$ctx:sourceAddress}</sourceAddress>
  <destinationAddress>{$ctx:destinationAddresses}</destinationAddress>
  <alphabet>{$ctx:alphabet}</alphabet>
  <charset>{$ctx:charset}</charset>
  <message>{$ctx:message}</message>
  <smscDeliveryReceipt>{$ctx:smscDeliveryReceipt}</smscDeliveryReceipt>
  <messageClass>{$ctx:messageClass}</messageClass>
  <isCompressed>{$ctx:isCompressed}</isCompressed>
  <esmclass>{$ctx:esmclass}</esmclass>
  <protocolid>{$ctx:protocolid}</protocolid>
  <priorityflag>{$ctx:priorityflag}</priorityflag>
  <replaceIfPresentFlag>{$ctx:replaceIfPresentFlag}</replaceIfPresentFlag>
  <submitDefaultMsgId>{$ctx:submitDefaultMsgId}</submitDefaultMsgId>
  <validityPeriod>{$ctx:validityPeriod}</validityPeriod>
</SMPP.sendBulkSMS>

Sample request

Following is a sample REST/JSON request that can be handled by the sendbulkSMS operation. 

  {
  "serviceType": "CMT",
  "sourceAddressTon": "NETWORK_SPECIFIC",
  "sourceAddressNpi": "INTERNET",
  "sourceAddress": "16116",
  "destinationAddresses": {
        "type": "ALPHANUMERIC",
        "numberingPlan": "LAND_MOBILE",
        "mobileNumbers": ["+189718785", "+189718674"]
     },
  "messageClass":"CLASS1",
  "alphabet": "ALPHA_DEFAULT",
  "charset": "UTF-8",
  "isCompressed":"true",
  "esmclass": "0",
  "protocolid": "0",
  "priorityflag":"1",
  "replaceIfPresentFlag": "0",
  "submitDefaultMsgId": "1",
  "validityPeriod": “020610233429000R”,
  "message": "hi hru",
  "smscDeliveryReceipt": "SUCCESS_FAILURE",
  "enquireLinkTimer": "50000",
  "transactionTimer": "100"
  }

Top