Name

SMPP — provides access to an SMSC (Short Message Service Center) over the SMPP protocol

Overview

This component provides access to an SMSC (Short Message Service Center) over the SMPP protocol to send and receive SMS. The JSMPP library is used to implement the connections.

As of Apache Camel 2.9, you can also execute ReplaceSm, QuerySm, SubmitMulti, CancelSm, and DataSm.

Dependencies

Maven users need to add the following dependency to their pom.xml file:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-smpp</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>
        

URI format

The URI scheme for an SMPP endpoint is as follows:

smpp://[username@]hostname[:port][?options]
smpps://[username@]hostname[:port][?options]

If no username is provided, Apache Camel provides the default value smppclient.

If no port number is provided, Apache Camel provides the default value 2775.

If the protocol name is smpps, Apache Camel tries to use SSLSocket to initialize a connection to the server.

URI Options

Table 42, “SMPP Options” lists the uri options for a SMPP endpoint.

Table 42. SMPP Options

NameDefaultDescription
password password Specifies the password to use for logging into to the SMSC.
systemType cp Categorizes the type of ESME (External Short Message Entity) that is binding to the SMSC (max. 13 characters).
dataCoding 0

Apache Camel 2.11: Defines encoding of data according the SMPP 3.4 specification, section 5.2.19. Example data encodings are:

  • 0—SMSC default alphabet

  • 3—Latin 1 (ISO-8859-1)

  • 4—Octet unspecified (8-bit binary)

  • 8—UCS2 (ISO/IEC-10646)

  • 13—Extended Kanji JIS(X 0212-1990)

alphabet 0

Apache Camel 2.5: Defines the encoding of data according to the SMPP 3.4 specification, section 5.2.19. This option is mapped to Alphabet.java and used to create the byte[] sent to the SMSC.

Example alphabets:

  • 0—SMSC default alphabet

  • 4—8-bit alphabet

  • 8—UCS2 alphabet

encoding ISO-8859-1 Apache Camel 2.5, only for SubmitSm, ReplaceSm and SubmitMulti: Defines the encoding scheme of the short message user data.
enquireLinkTimer 5000 Defines the interval in milliseconds between the confidence checks. The confidence check is used to test the communication path between an ESME and an SMSC.
transactionTimer 10000 Defines the maximum period of inactivity allowed after a transaction, after which an SMPP entity may assume that the session is no longer active. This timer may be active on either communicating SMPP entity (i.e. SMSC or ESME).
initialReconnectDelay 5000 Defines the initial delay in milliseconds after the consumer/producer tries to reconnect to the SMSC, after the connection was lost.
reconnectDelay 5000 Defines the interval in milliseconds between the reconnect attempts, if the connection to the SMSC was lost and the previous was not succeed.
registeredDelivery 1

Only for SubmitSM, SubmitMulti, CancelSm, and DataSm: Is used to request an SMSC delivery receipt and/or SME originated acknowledgements. The following values are defined:

  • 0: No SMSC delivery receipt requested.

  • 1: SMSC delivery receipt requested where final delivery outcome is success or failure.

  • 2: SMSC delivery receipt requested where the final delivery outcome is delivery failure.

serviceType CMT

The service type parameter can be used to indicate the SMS Application service associated with the message. The following generic service_types are defined:

  • CMT: Cellular Messaging

  • CPT: Cellular Paging

  • VMN: Voice Mail Notification

  • VMA: Voice Mail Alerting

  • WAP: Wireless Application Protocol

  • USSD: Unstructured Supplementary Services Data

sourceAddr 1616 Defines the address of SME (Short Message Entity) which originated the message.
destAddr 1717 Only for SubmitSM, SubmitMulti, CancelSm, and DataSm: Defines the destination SME address. For mobile terminated messages, this is the directory number of the recipient MS.
sourceAddrTon 0

Defines the type of number (TON) to be used in the SME originator address parameters. The following TON values are defined:

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

destAddrTon 0

Only for SubmitSM, SubmitMulti, CancelSm, and DataSm: Defines the type of number (TON) to be used in the SME destination address parameters. Use the values defined in sourceAddrTon.

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

sourceAddrNpi 0

Defines the numeric plan indicator (NPI) to be used in the SME originator address parameters. The following NPI values are defined:

  • 0: Unknown

  • 1: ISDN (E163/E164)

  • 2: Data (X.121)

  • 3: Telex (F.69)

  • 6: Land Mobile (E.212)

  • 8: National

  • 9: Private

  • 10: ERMES

  • 13: Internet (IP)

  • 18: WAP Client Id (to be defined by WAP Forum)

destAddrNpi 0

Only for SubmitSM, SubmitMulti, CancelSm, and DataSm: Defines the numeric plan indicator (NPI) to be used in the SME destination address parameters. Use the values defined in sourceAddrNpi.

priorityFlag 1

Only for SubmitSM and SubmitMulti: Allows the originating SME to assign a priority level to the short message. Four Priority Levels are supported:

  • 0: Level 0 (lowest) priority

  • 1: Level 1 priority

  • 2: Level 2 priority

  • 3: Level 3 (highest) priority

replaceIfPresentFlag 0

Only for SubmitSM and SubmitMulti: 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. The following replace if present flag values are defined:

  • 0: Don't replace

  • 1: Replace

typeOfNumber 0

Defines the type of number (TON) to be used in the SME. Use the values defined in sourceAddrTon.

numberingPlanIndicator 0

Defines the numeric plan indicator (NPI) to be used in the SME. Use the values defined in sourceAddrNpi.

lazySessionCreation false

Apache Camel 2.8: Specifies whether to create sessions lazily to avoid exceptions that occur if the SMSC is unavailable when the Camel producer is started.

Camel 2.11 onwards: Camel checks the in message headers CamelSmppSystemId and CamelSmppPassword of the first exchange. If they are present, Camel uses this data to connect to the SMSC.

httpProxyHost null

Apache Camel 2.9.1: Enables tunneling SMPP through the specified HTTP proxy. To enable, set this option to the hostname or ip address of your HTTP proxy.

httpProxyPort 3128

Apache Camel 2.9.1: Enables tunneling SMPP through the specified HTTP port. To enable, set this option to the port number of your HTTP proxy.

httpProxyUsername null

Apache Camel 2.9.1: Enables basic authentication for an HTTP proxy. If your HTTP proxy requires basic authentication, set this option to the required username.

httpProxyPassword null

Apache Camel 2.9.1: Enables basic authentication for an HTTP proxy. If your HTTP proxy requires basic authentication, set this option to the required password.

sessionStateListener null

Apache Camel 2.9.3: Specifies a reference to an org.jsmpp.session.SessionStateListener in the Camel Registry to receive callbacks when the session state changes.

addressRange "" Apache Camel 2.11: Specifies the address range for the SmppConsumer as defined in section 5.2.7 of the SMPP 3.4 specification. The SmppConsumer will receive messages only from SMSC's which target an address (MSISDN or IP address) within this range.

You can include as many of these URI options as you like, for example:

smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer

Message headers

Table 43, “SMPP producer headers” describes the message headers that affect the behavior of the SMPP producer.

Table 43. SMPP producer headers

HeaderTypeDescription
CamelSmppDestAddr

List/

String

Defines the destination SME address. For mobile terminated messages, this is the directory number of the recipient MS.
CamelSmppDestAddrTon Byte

Defines the type of number (TON) to be used in the SME destination address parameters. The following TON values are defined:

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

CamelSmppDestAddrNpi Byte

Defines the numeric plan indicator (NPI) to be used in the SME destination address parameters. The following NPI values are defined:

  • 0: Unknown

  • 1: ISDN (E163/E164)

  • 2: Data (X.121)

  • 3: Telex (F.69)

  • 6: Land Mobile (E.212)

  • 8: National

  • 9: Private

  • 10: ERMES

  • 13: Internet (IP)

  • 18: WAP Client Id (to be defined by WAP Forum)

CamelSmppSourceAddr String Defines the address of SME (Short Message Entity) which originated this message.
CamelSmppSourceAddrTon Byte

Defines the type of number (TON) to be used in the SME originator address parameters. The following TON values are defined:

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

CamelSmppSourceAddrNpi Byte

Defines the numeric plan indicator (NPI) to be used in the SME originator address parameters. The following NPI values are defined:

  • 0: Unknown

  • 1: ISDN (E163/E164)

  • 2: Data (X.121)

  • 3: Telex (F.69)

  • 6: Land Mobile (E.212)

  • 8: National

  • 9: Private

  • 10: ERMES

  • 13: Internet (IP)

  • 18: WAP Client Id (to be defined by WAP Forum)

CamelSmppServiceType String

The service type parameter can be used to indicate the SMS Application service associated with the message. The following generic service_types are defined:

  • CMT: Cellular Messaging

  • CPT: Cellular Paging

  • VMN: Voice Mail Notification

  • VMA: Voice Mail Alerting

  • WAP: Wireless Application Protocol

  • USSD: Unstructured Supplementary Services Data

CamelSmppRegisteredDelivery Byte

Is used to request an SMSC delivery receipt and/or SME originated acknowledgements. The following values are defined:

  • 0: No SMSC delivery receipt requested.

  • 1: SMSC delivery receipt requested where final delivery outcome is success or failure.

  • 2: SMSC delivery receipt requested where the final delivery outcome is delivery failure.

CamelSmppPriorityFlag Byte

Allows the originating SME to assign a priority level to the short message. Four Priority Levels are supported:

  • 0: Level 0 (lowest) priority

  • 1: Level 1 priority

  • 2: Level 2 priority

  • 3: Level 3 (highest) priority

CamelSmppScheduleDeliveryTime Date This parameter specifies the scheduled time at which the message delivery should be first attempted. It defines either the absolute date and time or relative time from the current SMSC time at which delivery of this message will be attempted by the SMSC. It can be specified in either absolute time format or relative time format. The encoding of a time format is specified in chapter 7.1.1. in the smpp specification v3.4.
CamelSmppValidityPeriod

String/

Date

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. The encoding of absolute and relative time format is specified in chapter 7.1.1 in the smpp specification v3.4.
CamelSmppReplaceIfPresentFlag Byte

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. The following values are defined:

  • 0: Don't replace

  • 1: Replace

CamelSmppAlphabet/

CamelSmppDataCoding

Byte

Apache Camel 2.5 For SubmitSM, SubmitMulti, and ReplaceSM (Prior to Apache Camel 2.9: use CamelSmppDataCoding instead of CamelSmppAlphabet.) The data coding according to the SMPP 3.4 specification, section 5.2.19. Use the URI option alphabet settings.

CamelSmppOptionalParameters Map<String,String> Deprecated and slated for removal in v 2.13.0/3.0.0 Apache Camel 2.10.5, 2.11.1 onwards and only for SubmitSM, SubmitMulti, and DataSM: The optional parameters sent back by the SMSC.
CamelSmppOptionalParameter Map<Short,Object>

Apache Camel 2.11:Apache Camel 2.10.5, 2.11.1 onwards and only for SubmitSM, SubmitMulti, and DataSM: Specifies the optional paramter sent to the SMSC. The value is converted this way:

  • String to org.jsmpp.bean.OptionalParameter.COctetString

  • byte[] to org.jsmpp.bean.OptionalParameter.OctetString

  • Byte to org.jsmpp.bean.OptionalParameter.Byte

  • Integer to org.jsmpp.bean.OptionalParameter.Int

  • Short to org.jsmpp.bean.OptionalParameter.Short

  • null to org.jsmpp.bean.OptionalParameter.Null


The following message headers are used by the SMPP producer to set the response from the SMSC in the message header

Table 44. Message headers used by the SMPP Producer to set the response from the SMSC in the message header

HeaderTypeDescription
CamelSmppId

List<String>/

String

Specifies the id to use to identify the submitted short message for later use (delivery receipt, query sm, cancel sm, replace sm).
CamelSmppSentMessageCount Integer Apache Camel 2.9: only for SubmitSm and SubmitMultiSm: The total number of messages that have been sent.
CamelSmppError

Map<String,/

List<Map<String,

Object>>>

Apache Camel 2.9: only for SubmitMultiSm: The errors that occurred by sending short messages in the form Map<String, List<Map<String, Object>>> (messageID : (destAddr : address, error : errorCode)).
CamelSmppOptionalParameters Map<String,String> Deprecated and slated for removal in v 2.13.0/3.0.0 Apache Camel 2.10.5, 2.11.1 onwards and only for DataSM: The optional parameters sent back by the SMSC.
CamelSmppOptionalParameter Map<Short,Object>

Apache Camel 2.11:Apache Camel 2.10.5, 2.11.1 onwards and only for DataSM: Specifies the optional paramter returned by the SMSC. The key is the Short code for the optional parameter. The value is converted this way:

  • org.jsmpp.bean.OptionalParameter.COctetString to String

  • org.jsmpp.bean.OptionalParameter.OctetString to byte[]

  • org.jsmpp.bean.OptionalParameter.Byte to Byte

  • org.jsmpp.bean.OptionalParameter.Int to Integer

  • org.jsmpp.bean.OptionalParameter.Short to Short

  • org.jsmpp.bean.OptionalParameter.Null to null


The following message headers are used by the SMPP consumer to set the request data from the SMSC in the message header.

Table 45. Consumer message headers

HeaderTypeDescription
CamelSmppSequenceNumber Integer only for alert notification, DeliverSm and DataSm: A sequence number allows a response PDU to be correlated with a request PDU. The associated SMPP response PDU must preserve this field.
CamelSmppCommandId Integer only for alert notification, DeliverSm and DataSm: The command id field identifies the particular SMPP PDU. For the complete list of defined values see chapter 5.1.2.1 in the smpp specification v3.4.
CamelSmppSourceAddr String only for alert notification, DeliverSm and DataSm: Defines the address of SME (Short Message Entity) which originated this message.
CamelSmppSourceAddrNpi Byte

only for alert notification and DataSm: Defines the numeric plan indicator (NPI) to be used in the SME originator address parameters. The following NPI values are defined:

  • 0: Unknown

  • 1: ISDN (E163/E164)

  • 2: Data (X.121)

  • 3: Telex (F.69)

  • 6: Land Mobile (E.212)

  • 8: National

  • 9: Private

  • 10: ERMES

  • 13: Internet (IP)

  • 18: WAP Client Id (to be defined by WAP Forum)

CamelSmppSourceAddrTon Byte

only for alert notification and DataSm: Defines the type of number (TON) to be used in the SME originator address parameters. The following TON values are defined:

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

CamelSmppEsmeAddr String only for alert notification: Defines the destination ESME address. For mobile terminated messages, this is the directory number of the recipient MS.
CamelSmppEsmeAddrNpi Byte

only for alert notification: Defines the numeric plan indicator (NPI) to be used in the ESME originator address parameters. The following NPI values are defined:

  • 0: Unknown

  • 1: ISDN (E163/E164)

  • 2: Data (X.121)

  • 3: Telex (F.69)

  • 6: Land Mobile (E.212)

  • 8: National

  • 9: Private

  • 10: ERMES

  • 13: Internet (IP)

  • 18: WAP Client Id (to be defined by WAP Forum)

CamelSmppEsmeAddrTon Byte

only for alert notification: Defines the type of number (TON) to be used in the ESME originator address parameters. The following TON values are defined:

  • 0: Unknown

  • 1: International

  • 2: National

  • 3: Network Specific

  • 4: Subscriber Number

  • 5: Alphanumeric

  • 6: Abbreviated

CamelSmppId String only for smsc delivery receipt and Data Sm: The message ID allocated to the message by the SMSC when originally submitted.
CamelSmppDelivered Integer only for smsc delivery receipt: Number of short messages delivered. This is only relevant where the original message was submitted to a distribution list. The value is padded with leading zeros if necessary.
CamelSmppDoneDate Date only for smsc delivery receipt: The time and date at which the short message reached it's final state. The format is as follows: YYMMDDhhmm.
CamelSmppFinalStatus DeliveryReceiptDate

only for smsc delivery receipt and DataSm: The final status of the message. The following values are defined:

  • DELIVRD: Message is delivered to destination

  • EXPIRED: Message validity period has expired.

  • DELETED: Message has been deleted.

  • UNDELIV: Message is undeliverable

  • ACCEPTD: Message is in accepted state (i.e. has been manually read on behalf of the subscriber by customer service)

  • UNKNOWN: Message is in invalid state

  • REJECTD: Message is in a rejected state

CamelSmppCommandStatus Integer only for DataSm: The command status of the message.
CamelSmppError String only for smsc delivery receipt: Where appropriate this may hold a Network specific error code or an SMSC error code for the attempted delivery of the message. These errors are Network or SMSC specific and are not included here.
CamelSmppSubmitDate Date only for smsc delivery receipt: 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.
CamelSmppSubmitted Integer only for smsc delivery receipt: Number of short messages originally submitted. This is only relevant when the original message was submitted to a distribution list. The value is padded with leading zeros if necessary.
CamelSmppDestAddr String only for DeliverSm and DataSm: Defines the destination SME address. For mobile terminated messages, this is the directory number of the recipient MS.
CamelSmppScheduleDeliveryTime String only for DeliverSm and DataSm: This parameter specifies the scheduled time at which the message delivery should be first attempted. It defines either the absolute date and time or relative time from the current SMSC time at which delivery of this message will be attempted by the SMSC. It can be specified in either absolute time format or relative time format. The encoding of a time format is specified in Section 7.1.1. in the smpp specification v3.4.
CamelSmppValidityPeriod String only for DeliverSm: 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. The encoding of absolute and relative time format is specified in Section 7.1.1 in the smpp specification v3.4.
CamelSmppServiceType String only for deliver sm and data sm: The service type parameter indicates the SMS Application service associated with the message.
CamelSmppRegisteredDelivery Byte

only for data sm: Is used to request an delivery receipt and/or SME originated acknowledgements. The following values are defined: 0: No SMSC delivery receipt requested. 1: SMSC delivery receipt requested where final delivery outcome is success or failure. 2: SMSC delivery receipt requested where the final delivery outcome is delivery failure.

CamelSmppDestAddrNpi Byte

only for data sm: Defines the numeric plan indicator (NPI) in the destination address parameters. The following NPI values are defined: 0: Unknown 1: ISDN (E163/E164) 2: Data (X.121) 3: Telex (F.69) 6: Land Mobile (E.212) 8: National 9: Private 10: ERMES 13: Internet (IP) 18: WAP Client Id (to be defined by WAP Forum)

CamelSmppDestAddrTon Byte

only for data sm: Defines the type of number (TON) in the destination address parameters. The following TON values are defined: 0: Unknown 1: International 2: National 3: Network Specific 4: Subscriber Number 5: Alphanumeric 6: Abbreviated

CamelSmppMessageType String

Apache Camel 2.6: Defines the type of incoming messages:

  • AlertNotification—an SMSC alert notification

  • DataSm>—an SMSC data short message

  • DeliveryReceipt—an SMSC delivery receipt

  • DeliverSm—an SMSC deliver short message

CamelSmppOptionalParameters Map<String,Object> Deprecated and slated for removal in v 2.13.0/3.0.0 Apache Camel 2.10.5 onwards and only for DeliverSM: The optional parameters sent back by the SMSC.
CamelSmppOptionalParameter Map<Short,Object>

Apache Camel 2.10.7 and 2.11.2 onwards and only for DeliverSM: Specifies the optional paramter returned by the SMSC. The key is the Short code for the optional parameter. The value is converted this way:

  • org.jsmpp.bean.OptionalParameter.COctetString to String

  • org.jsmpp.bean.OptionalParameter.OctetString to byte[]

  • org.jsmpp.bean.OptionalParameter.Byte to Byte

  • org.jsmpp.bean.OptionalParameter.Int to Integer

  • org.jsmpp.bean.OptionalParameter.Short to Short

  • org.jsmpp.bean.OptionalParameter.Null to null


Exception handling

This component supports the general Camel exception handling capabilities. Camel 2.8 onwarts: When the SMPP consumer receives a DeliverSm or DataSm short message and the processing of these messages fails, you can also throw a ProcessRequestException instead of handle the failure. In this case, this exception is forwarded to the underlying JSMPP library which will return the included error code to the SMSC. This feature is useful to e.g. instruct the SMSC to resend the short message at a later time. This could be done with the following lines of code:

from("smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer")
   .doTry()
     .to("bean:dao?method=updateSmsState")
   .doCatch(Exception.class)
     .throwException(new ProcessRequestException("update of sms state failed", 100))
   .end();

Please refer to the SMPP specification for the complete list of error codes and their meanings.

Samples

A route which sends an SMS using the Java DSL:

from("direct:start")
  .to("smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=producer");

A route which sends an SMS using the Spring XML DSL:

<route>
  <from uri="direct:start"/>
  <to uri="smpp://smppclient@localhost:2775?password=password&nquireLinkTimer=3000&ransactionTimer=5000&ystemType=producer"/>
</route>

A route which receives an SMS using the Java DSL:

from("smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer")
  .to("bean:foo");

A route which receives an SMS using the Spring XML DSL:

  <route>
     <from uri="smpp://smppclient@localhost:2775?password=password&nquireLinkTimer=3000&ransactionTimer=5000&ystemType=consumer"/>
     <to uri="bean:foo"/>
  </route>
[Note]Note

If you need an SMSC simulator for your test, you can use the simulator provided by Logica.

Debug logging

This component has log level DEBUG, which can be helpful in debugging problems. If you use log4j, you can add the following line to your configuration:

log4j.logger.org.apache.camel.component.smpp=DEBUG

See also

JSMPP Library