Short Codes _ SMPP Guide

					Short Codes & SMPP Guide




Abstract
This document explains how to use short codes for both premium and non-premium
SMS using the OpenMarket™ Messaging Network.




Short Codes & SMPP Guide                                                         1
Revision History

 Version     Date          Description
 1.0         12/1/2003     - First Release
 1.1         3/1/2004      - Added Charge Type optional parameter.
                           - Added new Optional Parameters section to describe
                           each parameter in more detail.
 1.2         10/13/2004    - Added Charge Amount optional parameter.
 1.3         3/1/2005      - Added additional information throughout document.
 1.4         6/1/2005      - Changed OperatorId to CarrierId to match naming
                           scheme used in the OpenMarket Wireless Message
                           Protocol.
                           - Added Charge Amount and Charge Type for deliver_sm
                           primitive for support of Mobile Originated PSMS.

 1.5         12/1/2005     - Updated length field descriptions in all optional
                           parameters.




Short Codes & SMPP Guide                                                          2
Bind Interface Version

OpenMarket requires that customers use SMPP (Short Message Peer-to-Peer) API
version 3.4 or above for premium or non-premium SMS that use short codes. Version
3.3 of the SMPP protocol does not support “Optional Parameters”. OpenMarket’s
premium SMS implementation requires that several SMSC-specific optional
parameters are set in order to trigger premium billing charges.

OpenMarket’s SMSC defaults to SMPP version 3.3 during the bind process, unless the
interface_version value is set to 0x34 or higher in the “Bind SM” SMPP primitive.


MT (Mobile Terminated) SMS

When sending premium or non-premium SMS with short codes, please set the
following properties in the “Submit SM” SMPP primitive:

Required Fields

   Field                   Value         Description
   Source TON              0x03 (hex)    Type of number is set to “network specific”
   Source NPI              0x00 (hex)    Number plan indicator is set to “unknown” – 0x01 is also
                                         accepted, but OpenMarket recommends 0x00.
   Source Address          5 digits      The 5 digit short code assigned to your account. This is
                                         the address that will show up as the sender of the SMS
                                         on the recipient’s phone. For example, you might set this
                                         to 10132 if that was the assigned short code.
   Destination TON         0x01 (hex)    Type of number is set to “international” – 0x00 is also
                                         accepted, however OpenMarket recommends 0x00.
   Destination NPI         0x01 (hex)    Number plan indicator is set to “ISDN/E.164” – 0x00 is
                                         also accepted, but OpenMarket recommends 0x01.
   Destination Address     2-21 digits   The internationally formatted E.164 address (phone
                                         number) of the recipient. The international format
                                         requires the <country code> followed by the <national
                                         number>. For example, a recipient located in the United
                                         States (country code of 1) with a phone number of
                                         (3135551212), this value would be set to 13135551212.


Optional Fields

   Field                   Value         Description
   Charge Type             0x00, 0x01    Controls whether an SMS generates a charge on the
                           (Byte)        recipient’s phone bill.

                                         0x00 = (do not charge, non-premium SMS)
                                         0x01 = (charge, premium SMS)

                                         Omitting this optional field in the “Submit SM” results in
                                         OpenMarket defaulting its value to your pre-configured
                                         account setting. Please note that the default may differ
                                         from account to account. The default setting is usually
                                         that a charge will not be generated, which means you
                                         should always explicitly set this value.

                                         Please see below for more information on how to use


Short Codes & SMPP Guide                                                                              3
                                          this optional SMPP field.
   Charge Amount           50, 199, etc   Only valid when the Charge Type optional parameter is
                           (Short)        set to 0x01. Indicates the amount to charge (in cents,
                                          pence, etc.) on a premium SMS. The Charge Amount
                                          must be pre-approved by OpenMarket. In the United
                                          States, for a $1.99 charge, this value would be set to
                                          199. In other countries such as the United Kingdom, for
                                          a £0.25 charge, this value would be set to 25.
   Carrier Id              Integer        Instructs the OpenMarket Network which carrier to send
                                          the message to. Usually, this parameter is not permitted
                                          for an account and should not be used.

                                          Please see below for more information on how to use
                                          this optional SMPP field.




MO (Mobile Originated) SMS

When receiving premium or non-premium SMS with short codes, the following
properties will be in the “Deliver SM” SMPP primitive:

Required Fields

   Field                   Value          Description
   Source TON              0x01 (hex)     Type of number is set to “international”.
   Source NPI              0x01 (hex)     Number plan indicator is set to “ISDN/E.164”.
   Source Address          2-21 digits    The internationally formatted E.164 address (phone
                                          number) of the recipient. The international format
                                          requires the <country code> followed by the <national
                                          number>. For example, an originator located in the
                                          United States (country code of 1) with a phone number
                                          of (3135551212), this value would be set to
                                          13135551212.
   Destination TON         0x03 (hex)     Type of number is set to “network specific”
   Destination NPI         0x00 (hex)     Number plan indicator is set to “unknown”.
   Destination Address     5 digits       The 5 digit short code assigned to your account. This is
                                          the address that the originator sent their SMS to. For
                                          example, this might be set to 10132 if that was your
                                          assigned short code.


Optional Fields

   Field                   Value          Description
   Charge Type             0x00, 0x01     Flag indicating if this SMS generated a charge on the
                                          originator’s phone bill.

                                          0x00 = (no charge, non-premium SMS)
                                          0x01 = (charge, premium SMS)

                                          Omitting this optional field in the “Deliver SM” is the
                                          equivalent of a setting of 0x00.

                                          Please see below for more information on how to use
                                          this optional SMPP field.
   Charge Amount           50, 199, etc   Only valid when the Charge Type optional parameter is
                                          set to 0x01. Indicates the amount charged (in cents,


Short Codes & SMPP Guide                                                                             4
                                        pence, etc.) on the premium SMS. In the United States,
                                        for a $1.99 charge, this value would be set to 199. In
                                        other countries such as the United Kingdom, for a £0.25
                                        charge, this value would be set to 25.
   Carrier Id              Integer      Reports which network operator the originator (source
                                        address) of a mobile originated SMS resides on. Please
                                        see http://network.OpenMarket.com/ for a complete list
                                        of carrier ids.

                                        Please see below for more information on how to use
                                        this optional SMPP field.




Optional Parameters

“Optional Parameters” are fields which may be optionally included in an SMPP
message. Optional Parameters must always appear at the end of a message, in the
"Optional Parameters" section of the SMPP PDU. However, they may be included in
any convenient order within the "Optional Parameters" section of the SMPP PDU and
need not be encoded in the order presented in this document.

For a particular SMPP PDU, the customer or SMSC may include some, all, or none of
the defined optional parameters as required for the particular application context. All
SMPP optional parameters have a 16 bit Parameter Tag Identifier. OpenMarket
supports many of the standard SMPP optional parameters and defines several of its
own.

Carrier Id

The carrier_id optional parameter reports which network operator the originator
(source address) of a mobile originated SMS resides on. Alternatively, in a
submit_sm command, the carrier_id instructs which network OpenMarket should
send the message to. For example, if an ATT Wireless mobile phone sent the mobile
originated SMS, this field would be set to a value of 7. Likewise, a Verizon mobile
phone would result in a value of 77. Please visit http://network.OpenMarket.com/ for
an up-to-date list of network operators and their associated IDs.

   Field        Size (Octets)   Type        Description
   Tag          2               Short       0x2150 (hex)
   Value        2               Short       0 = unknown operator or lookup failed
                                            > 0 = please see http://network.OpenMarket.com/ for an
                                            up-to-date list of all supported networks and their
                                            associated IDs.



Charge Type

For Mobile Terminated SMS, the charge_type optional parameter controls whether an
SMS should trigger a charge to be placed on the recipient’s mobile phone bill. For
Mobile Originated SMS, this charge_type parameter informs you if a charge was
placed on the originator’s phone bill. This optional parameter allows the same short
code to be used for both premium and non-premium SMS.


Short Codes & SMPP Guide                                                                          5
If this field is omitted from the “Submit SM” primitive, then OpenMarket will default
its value to the account’s pre-configured setting. Please note that while this typically
defaults to 0x00 (non-premium), it is possible that the default is 0x01 (premium).

If this field is omitted from the “Deliver SM” primitive, then treat its value as though
it was explicitly set to 0x00.

NOTE: Concatenated SMS such as ringtones or long text-messages should only set
the first segment to a charge_type of 0x01. If all segments are set to 0x01, then it
will result in a charge for each segment.

   Field     Size (Octets)   Type       Description
   Tag       2               Short      0x2151 (hex)
   Value     1               Byte       0 = do not charge recipient (non-premium SMS)
                                        1 = charge recipient (premium SMS)


Charge Amount

The charge_amount optional parameter controls which price tier will be used for the
charge on the recipient’s mobile phone bill. This optional parameter is only valid
when the charge_type optional parameter is set to 0x01 and the Charge Amount
must be pre-approved by OpenMarket.

The charge_amount is an integer representation of the total number cents, pence,
etc. to charge for the premium SMS. The currency of the amount is always
considered local to the country of the destination address. For example, if the
destination is a US recipient, the charge_amount will be interpreted as US dollars.
On the other hand, if the destination address is within Australia, then the amount will
be interpreted as Australian dollars.

In the United States, for a $1.99 charge, this value would be set to 199. In other
countries such as the United Kingdom, for a £0.25 charge, this value would be set to
25.

NOTE: If the charge_type parameter is set to 0x01, but the charge_amount
parameter is omitted, OpenMarket will default to the customer’s pre-configured
default price tier.

   Field     Size (Octets)   Type       Description
   Tag       2               Short      0x2152 (hex)
   Value     2               Short      $1.99   charge   should   be   199 for this value.
                                        $0.30   charge   should   be   30 for this value.
                                        $1.50   charge   should   be   150 for this value.
                                        £0.25   charge   should   be   25 for this value.




Short Codes & SMPP Guide                                                                     6