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. initThe 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¶ sendSMSUse 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 smscDeliveryReceipt This parameter is used to request an SMSC delivery receipt. The following values can be defined: Value Description DEFAULT No SMSC Delivery Receipt requested. This is the default value. SUCCESS_FAILURE SMSC Delivery Receipt requested where final delivery outcome is delivery success or failure. FAILURE SMSC Delivery Receipt requested where the final delivery outcome is delivery failure. SUCCESS SMSC Delivery Receipt requested where the final delivery outcome is success. This is supported from SMPP 5.0. Optional 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. 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 All other values reserved Priority There are two types of priority. 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. 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 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. ALPHA_DEFAULT ALPHA_8_BIT ALPHA_UCS2 ALPHA_RESERVED Optional charset Charset is used when decoding the message in SMSC. Following charsets are supported. UTF-8 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¶ sendBulkSMSUsed 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. Default Values: Default numbering plan and type will be added for all numbers {"mobileNumbers": ["+94715XXXXXX", "+1434XXXXXX"]} Custom numbering plan and type for all numbers. The specified plan and type will be set to all numbers. { "type": "NATIONAL", "numberingPlan":"NATIONAL", "mobileNumbers": [ "+94713089759", "+189718674" ] } 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. { "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. 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 All other values reserved Priority There are two types of priority. 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. 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. ALPHA_DEFAULT ALPHA_8_BIT ALPHA_UCS2 ALPHA_RESERVED Optional charset Charset is used when decoding the message in SMSC. Following charsets are supported. UTF-8 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" }