Short Message Peer to Peer. Application Reference. Release 3.0/1.5

Transcription

1 5 Short Message Peer to Peer Application Reference Release 3.0/1.5

2 Telepath SMSC Short Message Peer to Peer Application Reference. August 2000 Logica Mobile Networks Limited, 2000 All rights reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, electronic, mechanical, xerographic, optical, magnetic, or otherwise, without prior written permission from Logica Mobile Networks Limited. Printed in Dublin, Ireland. The information furnished herein is believed to be accurate and reliable. However, no responsibility is assumed by Logica Mobile Networks Limited for its use by any means whatsoever, nor for any infringements of patents or any other rights of third parties whatsoever resulting from its use. The information contained in this document is subject to change without notice. This document corresponds to the Telepath SMSC SMPP release 3.0, and also to any subsequent release, unless otherwise indicated in technical notes or new documentation. All rights conferred by the law in relation to trademarks and copyrights and by the virtue of international trademarks and copyright conventions are secured to the owners of the trademarks used within this publication. Reproduction requires the prior written consent of the trademark owners. Logica Mobile Networks Limited trades as Logica

3 Telepath SMSC SMPP Application Reference Table of Contents Table of Contents Preface...ix About this Document...ix Intended Audience...x Customer Feedback...x 1. Introduction Purpose Scope References Glossary SMS Applications Overview Typical Applications Using the Short Message Service in Voice Mail Applications Using the Short Message Service in Paging Applications Initiating ESME Communication with SMSC Establishing a Network level connection Establishing an SMPP Connection SMPP Operations Introduction Integers and Network byte order String Definitions BIND Operation ESME System Identification Address Routing UNBIND Operation SUBMIT_SM Operation SUBMIT_SM - Normal Operation SUBMIT_SM - Operation with replace_if_present_flag set SUBMIT_SM_RESP SUBMIT_MULTI Operation SUBMIT_MULTI to a Single SME Address SUBMIT_MULTI to a Single Distribution List SUBMIT_MULTI to Multiple Recipients SUBMIT_MULTI_RESP DELIVER_SM Operation DELIVER_SM - Normal Operation DELIVER_SM - Registered Operation DELIVERY_RECEIPT FORMAT DELIVER_SM_RESP QUERY_SM Operation QUERY_LAST_MSGS Operation QUERY_MSG_DETAILS Operation CANCEL_SM Operation REPLACE_SM Operation ENQUIRE_LINK Operation SMPP-3.0/1.5-UD1 iii

4 Table of Contents Telepath SMSC SMPP Application Reference 4. System Configuration Messages originated by the ESME Messages originated by the SMSC Regular Expressions Special Characters used for Address Routing Examples of using Regular Expressions for Address Routing System Definitions Command IDs Error Codes SMPP Error and Status Codes System Error Codes GSM Error Codes Telepath SMSC Error Codes Message States Allowed TON and NPI values Allowable values for esm_class field Appendix A - Implementation using TCP/IP...A-1 Appendix B - Implementation using X.25...B-1...B-2 Appendix C - Predefined Short Message...C-1 Appendix D - Typical Voice Mail Applications...D-1 Index...Index-1 iv SMPP-3.0/1.5-UD1

5 Telepath SMSC SMPP Application Reference List of Figures List of Figures Figure 2-1: ESME to SMSC communication Figure 2-2: ESME address routing to/from an SMSC SMPP-3.0/1.5-UD1 v

6 List of Figures Telepath SMSC SMPP Application Reference vi SMPP-3.0/1.5-UD1

7 Telepath SMSC SMPP Application Reference List of Tables List of Tables Table 2-1: Format of an SMPP address Table 3-1: Two byte integer in Big Endian format Table 3-2: Four byte integer in Big endian format Table 3-3: Service Type Description Table 3-4: deliver_sm - normal operation - supported fields Table 3-5: deliver_sm - normal operation - unsupported fields Table 3-6: deliver_sm - registered operation - supported fields Table 3-7: Delivery_Receipt - Message Structure Table 3-8: deliver_sm - registered operation - unsupported Table 3-9: Delivery_Receipt Message Format Table 4-1: SMPP Configurable Parameter subset Table 5-1: Regular Expression Examples Table 6-1: SMPP Command ID Values Table 6-2: SMPP Error and Status Codes Table 6-3: GSM Error Codes Table 6-4: SMSC Error Codes Table 6-5: SMPP Message States Table 6-6: Allowed TON and NPI Values Table 6-7: Allowed values for esm_class Table C-1: Predefined Short Message Options... C-1 Table C-2: Example Trigger Sequences... C-2 SMPP-3.0/1.5-UD1 vii

8 List of Tables Telepath SMSC SMPP Application Reference viii SMPP-3.0/1.5-UD1

9 Telepath SMSC SMPP Application Reference Preface Preface This document outlines an implementation of the open standard Short Message Peer to Peer (SMPP) protocol. SMPP offers a flexible message handling interface between a Logica Telepath Short Message Service Centre (SMSC) and one or more non-plmn Short Message Entities (SMEs), called ESMEs (External Short Message Entities), e.g Voic systems, Paging Bureaux, systems and various types of Information services. About this Document The SMPP Application Reference contains the following chapters: Chapter 1: Introduction This chapter provides an Introduction to the guide and related documentation. Chapter 2: Applications Overview This chapter provides an overview of the application and the communication levels. Chapter 3: SMPP Operations This chapter provides details on the SMPP Operations. Chapter 4: System Configuration This chapter provides details on how to install and configure SMPP. Chapter 5: Protocol Message Sequences and Sequence Numbering This chapter provides details on the message sequences and sequence numbering. Chapter 6: Regular Expressions This chapter provides details on regular expressions. Chapter 7: TPSMPP AIM Diagnostics This chapter provides details on SMPP diagnostics. Chapter 7: System Definitions This chapter provides details on command IDs and error codes. Index The index is designed to be used as a quick reference to the features discussed in this document. SMPP-3.0/1.5-UD1 ix

10 Preface Telepath SMSC SMPP Application Reference Intended Audience This document is intended for designers wishing to implement an SMPP interface between an SMSC and one or more ESMEs (External Short Message Entities). Customer Feedback In order to maintain the high standard of service that Logica Mobile Networks provides, we welcome any suggestions and comments that you may have on the quality and usability of the documentation. A Reader s Comment Form is included with this document and has been inserted at the back of the SMPP DTK Users Guide. We would be grateful if you could take the time to complete this form and return it to us at your earliest possible convenience. Please submit any comments that you may have to this address: Application Provider Program Logica 5 Custom House Plaza Harbourmaster Place Dublin 1 Ireland Telephone #: (353) Fax #: (353) appservices@logica.com x SMPP-3.0/1.5-UD1

11 Telepath SMSC SMPP Application Reference Introduction 1. Introduction 1.1 Purpose This document outlines the implementation of the open Short Message Peer to Peer Protocol for interfacing between a Short Message Service Centre (SMSC) and an ESME (External Short Message Entity) or non PLMN SME. The SMPP Protocol may operate on either a TCP/IP or X.25 network connection. 1.2 Scope This Application Reference is intended for designers and implementers of Short Message Applications on wireless networks. It defines an open interface implementation between an ESME system and a Short Message Service Centre (SMSC) via the open Short Message Peer to Peer Protocol. 1.3 References [1] SMPP Technical Reference SMPP-3.0/3.3-UD1 [2] GSM European Digital Cellular Telecommunications System v4.6.0 (published by ETSI) [3] Telepath SMSC TPSMT Users s Guide SMS-2600-TPSMT-xxxx-UD1 SMPP-3.0/1.5-UD1 1-1

12 Introduction Telepath SMSC SMPP Application Reference 1.4 Glossary AIM BSD CDR Application Interface Module Berkeley Software Distribution Call Detail Record ESME External Short Message Entity. Refer to note [1] ETSI MSB MSISDN MS European Telecommunications Standards Institute Most Significant Byte Mobile Station ISDN Number, i.e. a telephone number Mobile Station NPI Numbering Plan Indicator. Refer to GSM [2] NACK PLMN SME SMS SMSC SMPP SM-VMA Negative Acknowledgement Public Land Mobile Network Short Message Entity Short Message Service Short Message Service Centre Short Message Peer to Peer Protocol Short Message Voice Mail Alert TON Type Of Number. Refer to GSM [2] TPSMT Telepath SMSC System Manager Terminal VC Virtual Connection. Refer to note [2] VMA Voic Alert or Message Waiting Indication (MWI) Note: Note: [1] External Short Message Entity. In the context of this document this refers to such external sources and sinks of short messages as Voice Processing or Message Handling computers. It specifically excludes SMEs which are part of the interface to the PLMN. [2] Virtual Connection. This refers to a virtual circuit in the X.25 implementation. In the TCP/IP implementation this is a logical connection over 4.3 BSD Internet domain sockets. 1-2 SMPP-3.0/1.5-UD1

13 Telepath SMSC SMPP Application Reference SMS Applications Overview 2. SMS Applications Overview 2.1 Typical Applications An External Short Message Entity (ESME) can establish communication with a Telepath SMSC via the SMPP protocol interface as described in the SMPP Technical Reference [1]. Typical examples include Voice Mail Systems, Paging systems, and Information Services etc Using the Short Message Service in Voice Mail Applications Voice Mail Alert Short Message This application issues a Voice Mail Alert (VMA) indication to a Mobile Station (MS) or handset via the Short Message Service. In this case a short message will typically be sent to the handset when an event occurs within the Voice Mail System (VMS), for example:- A new Voice Mail message is deposited for the MS. In this case, the current number of unread messages in the user s mailbox could be provided as a short message. One or more messages are read by the user. In this case, the remaining number of unread messages in the user s mailbox could be provided as a short message. In the case where a user listens to all of their messages, a message could be sent indicating that there are no unread messages remaining Replace Short Message The replace_sm feature in SMPP can be used advantageously to reduce the number of messages that are actually sent to a Mobile Station (MS), thus conserving channel bandwidth and also reducing the data storage requirements in the handset and/or in the handset s SIM Card Outdial Voice Mail Alert An efficient Outdial Voice Mail Alert service can be implemented in a GSM network through the use of the short message service to identify when an MS reattaches to the PLMN. An example of a typical scenario of Outdial Voice Mail Alert handling is described in Appendix D Using the Short Message Service in Paging Applications A paging bureau can submit short messages to an SMSC which can then be routed to an MS. An advantage of this method, is that the originator can receive confirmation from the SMSC that the message was received by the MS. SMPP-3.0/1.5-UD1 2-1

14 SMS Applications Overview Telepath SMSC SMPP Application Reference 2.2 Initiating ESME Communication with SMSC Establishing communications between an ESME Application and the SMSC follows a two stage approach as described below:- Stage 1:-Establish a network level connection, Stage 2:-Open an SMPP connection Establishing a Network level connection Two network connections are required for communication between an ESME and the SMSC. One is used for messages originating in the ESME system (e.g. submit_sm, query_sm, cancel_sm etc.), and the SMSC responses to these messages (e.g. submit_sm_resp, query_sm_resp, cancel_sm_resp etc.). The other connection is used for messages originating in the SMSC (e.g. deliver_sm) and the corresponding ESME responses (e.g. deliver_sm_resp). In the case of a TCP/IP network, two socket connections are required. One socket connection will be used for each direction of data transfer as mentioned above. With an X.25 network, two X.25 Switched Virtual Circuits (SVCs) must be established, one for each direction of data transfer, corresponding to the network connections mentioned above Establishing an SMPP Connection Once the network connection has been established, SMPP communication can be initiated. An ESME establishes an SMPP connection with the SMSC by issuing a bind request. Each of the two processes running on the ESME should send either a bind_transmitter request or a bind_receiver request to the SMSC (See Figure 2.1). If a bind_transmitter request is sent, the receiving process on the SMSC will accept messages originated by the ESME. If a bind_receiver request is sent, the receiving process on the SMSC will forward messages originated in the SMSC to the ESME. Message responses will invariably be returned on the same network connection as the corresponding message. 2-2 SMPP-3.0/1.5-UD1

15 Telepath SMSC SMPP Application Reference SMS Applications Overview Application ESME network connections Communications Provider for example, TCP/IP, X.25 SMSC Application (bound as Transmitter) SMSC Application (bound as Receiver) SMSC Kernel ESME Authentication Figure 2-1: ESME to SMSC communication Before authorising access, the SMSC will authenticate the ESME system s unique system_id, system_type and password, which must be included as part of the bind request. These identifiers must be assigned by the SMSC Administrator to identify the ESME System to the SMSC, before a successful bind operation can take place Default Interface Addressing The ESME system is also assigned a unique default callback address, by the SMSC System Administrator. This callback address is used as a substitute source address for routing to the ESME system in cases where the actual ESME address is not supplied. Note: In the context of communications between an ESME and an SMSC, an address consists of the following constituent parts or fields: Field addr_ton addr_npi address Description Type of Number (TON) Numeric Plan Indicator (NPI) Telephone Number (MSISDN Address) Table 2-1: Format of an SMPP address SMPP-3.0/1.5-UD1 2-3

16 SMS Applications Overview Telepath SMSC SMPP Application Reference Refer to Table 6-6: Allowed TON and NPI Values for a listing of allowed TON and NPI values Address Routing The ESME system may act either as a stand-alone entity or alternatively as a gateway or agent for transporting messages to and from other ESMEs (refer to Figure 2.2 below). When acting as a gateway, the ESME system may advertise the range of addresses which it serves. This can be defined explicitly in the bind operation or may be configured by the SMSC Administrator. Refer to the SMPP Technical Reference [1] for details on the format of the bind command. ESME ESME ESME SME Agent SMSC ESME Figure 2-2: ESME address routing to/from an SMSC 2-4 SMPP-3.0/1.5-UD1

17 Telepath SMSC SMPP Application Reference SMPP Operations 3. SMPP Operations 3.1 Introduction This chapter details the functional implementation and operation of the SMPP protocol functions. For details on the message format of each operation, refer to the SMPP Technical reference [1] Integers and Network byte order All SMPP integer fields are transmitted in Big Endian format, i.e. Most Significant Byte (MSB) first. Thus, the high order byte is stored at the starting address as illustrated below:- Addr A Addr A +1 High-order byte Low-order byte Table 3-1: Two byte integer in Big Endian format Addr A Addr A +1 Addr A + 2 Addr A+3 High-order byte 2nd highest order byte 3rd highest order byte Low-order byte Table 3-2: Four byte integer in Big endian format String Definitions Integer C-Octet String C-Octet String (Decimal) C-Octet String (Hex) Octet String C-Octet Fixed Length String A signed value with the defined number of bytes. The bytes will always be transmitted MSB first. A series of ASCII characters terminated with the NUL character. A series of ASCII characters terminated with the NUL character. The octet string should represent a sequence of decimal digits. A series of ASCII characters terminated with the NUL character. The octet string should represent a sequence of hexadecimal digits. Series of octets which may/may not be null terminated. The octets themselves can contain nulls. A string of defined length containing a series of ASCII characters and terminated with the NUL character. SMPP-3.0/1.5-UD1 3-1

18 SMPP Operations Telepath SMSC SMPP Application Reference 3.2 BIND Operation The purpose of the bind operation is to register an ESME system with the SMSC. An ESME may bind as either a transmitter or receiver by using one of two possible variations of bind operation, namely bind_transmitter and bind_receiver. The Command ID field in the SMPP message header specifies which of the two options is selected. For further details on the format of the bind operation message, refer to the SMPP Technical Reference [1] ESME System Identification As described in Section : ESME Authentication, the ESME system must provide a unique system_id, system_type and password as part of the bind request. These fields uniquely identify the ESME system and must be assigned by the SMSC Administrator before binding to the SMSC Address Routing When an ESME has bound to the SMSC, via either the bind_receiver or bind_transmitter operations, it may act either as a stand-alone entity or alternatively as a gateway serving a number of other ESMEs. The ESME address is specified by the addr_ton, addr_npi and the address_range field in the bind command. The addr_ton and addr_npi fields should be supplied by, or alternatively set in consultation with the network provider and must conform to the standards defined by the ETSI GSM [2]. Refer to Table 6-6: Allowed TON and NPI Values. The address_range field is represented by a regular expression as described in Chapter 6 and may contain either a single address or a range of addresses according to whether the ESME is acting as a stand alone system or as a gateway Address Routing Administration The range of ESME addresses can be defined explicitly in the bind operation or may be configured by the SMSC Administrator through the Telepath SMSC System Manager Terminal (TPSMT). Refer to the Telepath SMSC TPSMT Users Guide [3] for details. Refer to the SMPP Technical Reference [1] for details on the format of the bind command. Note: Typically the SMSC configuration will take precedence over the values supplied in the bind operation. However, the SMSC System Administrator may assign precedence to the values supplied by the ESME as part of the SMPP message. 3-2 SMPP-3.0/1.5-UD1

19 Telepath SMSC SMPP Application Reference SMPP Operations 3.3 UNBIND Operation The purpose of the unbind operation is to close the current session and de-register the ESME system from the SMSC. On receiving an unbind command, the network connection between the ESME and the SMSC is released. For further details on the unbind operation, refer to the SMPP Technical Reference [1]. 3.4 SUBMIT_SM Operation The submit_sm operation is typically issued by the ESME to send a short message to the SMSC for transmission to the specified subscriber. Two modes of operation are supported:- i) Normal submission ii) Replace existing message SUBMIT_SM - Normal Operation In normal operation, the ESME issues a message to the SMSC which is then entered into the SMSC database for forwarding to the subscriber. A message sent using the submit_sm operation can be: - Registered (submit_sm with the registered_delivery_flag set) - Prioritised (submit_sm with the priority_flag set) - Scheduled (submit_sm using the schedule_delivery_time field to specify the desired delivery time). For further details on format of the submit_sm command, refer to the SMPP Technical Reference [1] Default Address Handling When the ESME itself is the originator of the messages submitted (i.e. the ESME is not acting as a gateway) or where the ESME does not have an assigned source address, the Source_Address fields (i.e. source_addr_ton, source_addr_npi and source_addr) may be set to NULL and the relevant fields will then be substituted with the associated default callback address field by the SMSC as follows: - If source_addr is NULL then: source_addr_ton is set to the callback_addr_ton by the SMSC source_addr_npi is set to the callback_addr_npi by the SMSC source_addr is set to the callback_addr by the SMSC - If source_addr_ton is set to NULL then: source_addr_ton is set to the callback_addr_ton by the SMSC - If source_addr_npi is set to NULL: source_addr_npi is set to the callback_addr_npi by the SMSC SMPP-3.0/1.5-UD1 3-3

20 SMPP Operations Telepath SMSC SMPP Application Reference Service Type Support The purpose of the service_type field is to allow operations to be performed on groups of messages belonging to a particular type of service e.g. NOTIFY, ALERT, CALLBACK etc. (Refer to Table 3-3: Service Type File ). The service_type option is supported in the submit_sm, submit_multi and cancel_sm operations and is defined as a six character ASCII string. It is possible to allocate the type of service associated with each message submitted by the ESME. When the incoming message from the ESME is received by the SMSC, the service_type is mapped to known or defined service types in the SMSC. When not required, the service_type field should be set to NULL which is equivalent to the NOTIFY service type. It is also possible to create user defined service types by assigning a value between 128 and in the service_type field, as defined in Table 3-3: Service Type Description. ESME Service Type value SMSC Service type value Service Type Description NULL 0 NOTIFY string a 1 ALERT string b 2 CALLBACK 3...,127 Reserved string n 128,...,32767 Available for use -can be assigned by ESME Table 3-3: Service Type Description SUBMIT_SM - Operation with replace_if_present_flag set The submit_sm operation can also be used to replace a previously submitted message in the SMSC by setting the replace_if_present_flag. In this case, if the Message ID and Source_Address (i.e. source_addr_ton, source_addr_npi, and source_addr) fields of the incoming message from the ESME match those of an existing message in the SMSC, the short_message text of the message in the SMSC will be replaced by that contained in the incoming message. This may be used for example, by a Voice Mail System wishing to alert an out of range mobile subscriber (MS) that a new voice mail message has been received for that subscriber, which has now increased the total of unread voice messages from one message which already existed, to two. Rather than issue a new short message alerting the MS to this, which would result in two separate messages being transmitted to the MS when it reattaches to the PLMN, it is preferable to replace the existing alert message with new text reflecting the updated total of unread voice mail messages. 3-4 SMPP-3.0/1.5-UD1

21 Telepath SMSC SMPP Application Reference SMPP Operations The message fields which can be replaced by the submit_sm with the replace_if_present_flag set operation are the same as those which can be replaced by the replace_sm command. When a message is sent using the submit_sm with the replace_if_present_flag set; if no message matching the supplied Message ID and Source_Address fields is found in the SMSC, the incoming message is considered to be a new message and is added to the SMSC database. However, with the replace_sm operation, if no messages exist in the SMSC which match the Message ID and Source_Address fields (i.e. source_addr_ton, source_addr_npi, and source_addr) of the message to be replaced, then the message is NOT submitted to the SMSC. The following SMPP message fields can be replaced when using the submit_sm with the replace_if_present_flag set operation:- schedule_delivery_time Can only be replaced when the original message submitted was a scheduled delivery message. validity_period Contact the network provider for recommended settings for this field. registered_delivery_flag sm_default_msg_id sm_length short_message The following SMPP message fields cannot be replaced when using the submit_sm operation with the replace_if_present_flag set:- service_type Source_Address (i.e. source_addr_ton, source_addr_npi, source_addr) Destination_Address (i.e. dest_addr_ton, dest_addr_npi, destination_addr) esm_class protocol_id priority_flag data_coding For further details on the submit_sm with the replace_if_present_flag set operation, refer to the SMPP Technical Reference [1] SUBMIT_SM_RESP The SMSC returns the Message ID of the submitted message in the submit_sm_resp acknowledgement. For further details on the submit_sm_resp operation, refer to the SMPP Technical Reference [1]. Note: When a message is sent by the ESME using the submit_sm operation with the replace_if_present_flag set, the Message ID returned by the SMSC in the submit_sm_resp acknowledgement is the Message ID of the originally submitted message. SMPP-3.0/1.5-UD1 3-5

22 SMPP Operations Telepath SMSC SMPP Application Reference 3.5 SUBMIT_MULTI Operation The submit_multi operation can be used to send a short message to:- i) a Single SME Address ii) iii) a single Distribution List Multiple SME Addresses and/or Distribution Lists A message sent using the submit_multi operation can also be: - Registered (submit_sm with the registered_delivery_flag set) - Prioritised (submit_sm with the priority_flag set) - Scheduled (submit_sm using the scheduled_delivery_time field to specify the desired delivery time). In all of the above cases, the submit_multi operation is followed by a submit_multi_resp acknowledgement from the SMSC. For further details on the submit_multi operation, refer to the SMPP Technical Reference [1] SUBMIT_MULTI to a Single SME Address In this mode, submit_multi operates in a similar fashion to the submit_sm command (normal submission), with the following exceptions:- number_of_dests This field indicates the number of destination address structures that are to follow. The field must be set to a value one (1) if the message is to be submitted to only one SME address. dest_flag This flag indicates whether the destination is an SME address or a Distribution List. It should be set to a value one (1) when the message is to be submitted to an SME address. dest_address Contains the destination SME address. The replace_if_present_flag is supported in the submit_multi operation when sending a short message to a single SME address SUBMIT_MULTI to a Single Distribution List The submit_multi command can be used to send a short message to all of the subscribers on a provisioned Distribution List. The message format of the submit_multi operation is similar to that of the submit_sm command. However, there are some differences when submitting to a Distribution List as follows: number_of_dests This field indicates the number of destination address structures that are to follow. It must be set to a value one (1) when the message is sent to a single Distribution List. 3-6 SMPP-3.0/1.5-UD1

23 Telepath SMSC SMPP Application Reference SMPP Operations dest_flag This flag indicates whether the destination is an SME address or a Distribution List. It should be set to a value two (2) for a Distribution List. dest_address Contains the destination DL Name. replace_if_present_flag This option is NOT supported for submission to Distribution Lists. Note: Refer to the SMPP Provisioning Reference Guide for information on provisioning Distribution Lists SUBMIT_MULTI to Multiple Recipients The submit_multi command can be used to send a short message to multiple SME addresses and/or Distribution Lists. Thus an ESME can use this operation to send a message to a number of individual SME addresses and to a number of provisioned Distribution Lists at the same time. The message format of the submit_multi operation is similar to that of the submit_sm command. However, there are some differences when sending to multiple recipients as follows: number_of_dests This field indicates the number of destination address structures that are to follow. For multiple recipients, this should be a value greater than one (1). dest_flag This flag indicates whether the destination is an SME address or a Distribution List. It should be set as follows: - SME Address= 1 - Distribution List= 2 dest_address Contains the destination SME Addresses or DL Names. replace_if_present_flag This option is NOT supported for submission to multiple recipients, whether individual SME addresses or Distribution Lists. Note: Each copy of a message submitted to multiple recipients (whether individual SME addresses or Distribution Lists) will be assigned the same Message ID. The dest_address field is comprised of dest_flag and the SME Address or DL Name fields (Refer to SMPP Technical Reference [1]). A maximum of 200 destination addresses are allowed in the dest_address field, which can include any combination of individual SME Addresses and Distribution List members. For example, a message could be sent to a Distribution List containing 50 members and up to 150 individual SME Addresses. Another message could be sent to a Distribution List containing 25 members, another Distribution List containing 75 members and up to 100 other individual SME Addresses. SMPP-3.0/1.5-UD1 3-7

24 SMPP Operations Telepath SMSC SMPP Application Reference SUBMIT_MULTI_RESP The submit_multi_resp operation returns the Message ID, the total number of unsuccessful destinations to which the message was submitted (No_UnSuccess), the individual Destination_Address (i.e. dest_addr_ton, dest_addr_npi, destination_addr) of each unsuccessful submission and an Error_status_code indicating the reason why the message may not have been delivered. For further details on the submit_sm_resp operation, refer to the SMPP Technical Reference [1]. 3-8 SMPP-3.0/1.5-UD1

25 Telepath SMSC SMPP Application Reference SMPP Operations 3.6 DELIVER_SM Operation In normal mode, the deliver_sm operation is used by the SMSC to send a short message to the ESME for delivery. However, it is also used to return a Delivery_Receipt to the ESME for a registered message, i.e. a message submitted using submit_sm with the registered_delivery_flag set DELIVER_SM - Normal Operation The format of the deliver_sm message in normal operation is similar to that of submit_sm. However, some of the fields used in the submit_sm message are not used with deliver_sm and should be set to the values supplied below. The following fields are supported in deliver_sm and must be entered in the message body. Field Name service_type Source_Address (i.e. source_addr_ton, source_addr_npi, source_addr) Destination_Address (i.e. dest_addr_ton, dest_addr_npi, destination_addr) esm_class sm_default_msg_id protocol_id data_coding sm_length short_message Table 3-4: deliver_sm - normal operation - supported fields SMPP-3.0/1.5-UD1 3-9

26 SMPP Operations Telepath SMSC SMPP Application Reference The following options are NOT supported in the deliver_sm operation: Field Name Type priority_flag schedule_delivery_time validity_period registered_delivery_flag replace_if_present_flag sm_default_msg_id Integer C-Octet String C-Octet String Integer Integer Integer Table 3-5: deliver_sm - normal operation - unsupported fields Note: Those fields in Table 3-5 above which are of type C-Octet, should be set to a single NULL byte. Those fields in Table 3-5 above which are of type Integer, should be set to zero (0) SMPP-3.0/1.5-UD1

27 Telepath SMSC SMPP Application Reference SMPP Operations DELIVER_SM - Registered Operation When a message is sent by the ESME to the SMSC using submit_sm with the registered_delivery_flag set, a Delivery_Receipt (Refer to Table 3.5: Delivery_Receipt Message Format ) is returned to the ESME. This occurs when the message reaches a final state (e.g. DELIVERED, EXPIRED, DELETED, UNDELIVERABLE etc.). The Delivery_Receipt is issued by the SMSC using the deliver_sm command and the ESME may distinguish it from other short messages by the value included in the esm_class field of the message (refer to Table 6-7: esm_class values ) The following fields are relevant in the deliver_sm message, when used for returning a Delivery_Receipt: Field Name Source_Address (i.e. source_addr_ton, source_addr_npi, source_addr) Destination_Address (i.e. dest_addr_ton, dest_addr_npi, destination_addr) esm_class Value returned This is equivalent to the destination address of the originally submitted short message. This is equivalent to the source address of the originally submitted short message. Set to SMC_RECEIPT by the SMSC to Distinguish the deliver_sm as a Delivery_Receipt protocol_id data_coding sm_length short_message See Note below. Table 3-6: deliver_sm - registered operation - supported fields Note: The deliver_sm short message containing a Delivery_Receipt follows the structure outlined in Table 3-7: Delivery Receipt - Message Structure and Table 3-9: Delivery Receipt Message Format. Message ID sub dlvrd submit_date done_date stat err text IIIIIIIIII SSS DDD YYMMDDhhmm YYMMDDhhmm DDDDDDD E (up to 20 bytes) Table 3-7: Delivery_Receipt - Message Structure SMPP-3.0/1.5-UD1 3-11

28 SMPP Operations Telepath SMSC SMPP Application Reference The following fields are NOT relevant in the deliver_sm message, when used for returning a Delivery_Receipt: Field Name Type priority_flag schedule_delivery_time validity_period registered_delivery_flag replace_if_present_flag sm_default_msg_id Integer C-Octet String C-Octet String Integer Integer Integer Table 3-8: deliver_sm - registered operation - unsupported Note: Those fields in Table 3-8 above which are of type C-Octet, should be set to a single NULL byte. Those fields in Table 3-8 above which are of type Integer, should be set to zero (0) DELIVERY_RECEIPT FORMAT Field Name Size (bytes) Type Description Message ID 10 C-Octet String Message ID assigned by the SMSC to the originally submitted message. sub 3 C-Octet String Number of destinations to which the short message was originally submitted. This is relevant only when the original message was submitted to multiple recipients or to a Distribution List. This value is padded with leading zeros if necessary. dlvrd 3 C-Octet Fixed String Length Number of destinations to which the short message was actually delivered This is relevant only when the original message was submitted to multiple recipients or to a Distribution List. This value is padded with leading zeros if necessary. Table 3-9: Delivery_Receipt Message Format 3-12 SMPP-3.0/1.5-UD1

29 Telepath SMSC SMPP Application Reference SMPP Operations Field Name Size (bytes) Type Description submit_date 10 C-Octet String The date and time at which the short message was originally submitted to the SMSC. In the case of a message which has been replaced, the date and time or replacement will be entered here. The format is outlined in Table 3-7 where: - YY denote the last two digits of the year (00-99) - MM denotes the month (01-12) - DD is the day (01-31) - hh is the hour (00-23) - mm is the minute(00-59) done_date 10 C-Octet String The time and date at which the short message reached its final state. stat 7 C-Octet String The final status of the message. See Table 6-5 SMPP Message States for details. err 3 C-Octet String Where appropriate, this holds a GSM Error Code or Telepath SMSC Error Code corresponding to the reason the message could not be delivered successful. Refer to Section for details on System Error Codes. This value is padded with leading zeros if necessary. text 20 C-Octet String The first 20 characters of the short message DELIVER_SM_RESP Table 3-9: Delivery_Receipt Message Format Following receipt of a deliver_sm message, the ESME must return a deliver_sm_resp to the SMSC. The format of the deliver_sm_resp acknowledgement is similar to that of the submit_sm_resp message and should contain the Message ID of the original message received from the SMSC. The ESME will substitute the Command ID value corresponding to the deliver_sm_resp operation and it should also return a Command Status value. Refer to Table 6-2: SMPP Error and Status Codes. For further details on the deliver_sm_resp operation, refer to the SMPP Technical Reference [1]. SMPP-3.0/1.5-UD1 3-13

30 SMPP Operations Telepath SMSC SMPP Application Reference 3.7 QUERY_SM Operation The query_sm operation is used by the ESME to query the status of a short message previously submitted to the SMSC. It is typically used to obtain the status and time of delivery (if the message has been delivered) of unregistered messages (i.e. messages submitted using submit_sm command without having set the replace_if_present_flag). The status parameters are returned in the query_sm_resp message from the SMSC. Refer to Chapter 6 for details on the Error and Status Codes and on the defined SMPP Message States. Default addressing handling for the query_sm operation is identical to that used for submit_sm. Refer to Section : Default Address Handling, for details. For further details on the query_sm operation, refer to the SMPP Technical Reference [1] SMPP-3.0/1.5-UD1

31 Telepath SMSC SMPP Application Reference SMPP Operations 3.8 QUERY_LAST_MSGS Operation The query_last_msgs operation is used by the ESME to query the details of a number of messages, as defined by the Num_Messages field, stored in the SMSC for the originating source address, as specified by the source_addr_ton, source_addr_npi, and source_addr fields of the command. The number of messages found in the SMSC which match the Source_Address and the Message ID fields specified are returned in the query_last_msgs_resp from the SMSC. For further details on the query_last_msgs operation, refer to the SMPP Technical Reference [1]. SMPP-3.0/1.5-UD1 3-15

32 SMPP Operations Telepath SMSC SMPP Application Reference 3.9 QUERY_MSG_DETAILS Operation The query_msg_details operation is used by the ESME to query the details of a specific message, as defined by the Message ID. The details are returned by the SMSC in the query_msg_details_resp message. Three categories of message may exist in the SMSC database for an originating source address : i) Messages sent to single recipient or SME address ( Normal message ), ii) iii) Messages sent to a single Distribution List ( Distribution List message ), Messages sent to multiple Distribution Lists or SME addresses ( Multiple Recipients message ). The status and destination SME address (defined by the dest_addr_ton, dest_addr_npi, and destination_addr fields) of a message in each of the three categories are returned in the query_msg_details_resp message as follows: i) In the case of Normal messages, the destination address returned will be that supplied in the submit_sm or submit_multi command. A message_status corresponding to one of the states listed in Table 6-5: SMPP Message States is also returned. ii) iii) For a Distribution List message, the destination address returned will be the single Distribution List name (dl_name) supplied in the submit_multi operation. The message_status is updated only after the SMSC has attempted to forward the message to each member in the Distribution List. With a Multiple Recipients message, a number of SME addresses or Distribution List names may be returned corresponding to those supplied in the submit_multi operation. The message_status is updated only after the SMSC has attempted to forward the message to each of the multiple recipient addresses. For further details on the query_msg_details operation, refer to the SMPP Technical Reference [1] SMPP-3.0/1.5-UD1

33 Telepath SMSC SMPP Application Reference SMPP Operations 3.10 CANCEL_SM Operation This command is issued by the ESME to cancel one or more outstanding short messages. The command may specify a particular message, or all messages for a particular source and destination. A typical use of the command is to cancel outstanding undelivered Voic Alert messages for a subscriber whose mailbox has just been directly accessed by the subscriber. The response cancel_sm_resp indicates whether the message(s) have already been sent. Default addressing handling for the cancel_sm operation is identical to that used for submit_sm. Refer to Section : Default Address Handling, for details. Note: It is not possible to cancel a message submitted to a Distribution List, It is not possible to cancel a message submitted to Multiple Recipients. For further details on the cancel_sm operation, refer to the SMPP Technical Reference [1]. SMPP-3.0/1.5-UD1 3-17

34 SMPP Operations Telepath SMSC SMPP Application Reference 3.11 REPLACE_SM Operation This command is issued by the ESME to replace a previously submitted short message stored in the SMSC for delivery to a subscriber. The replace_sm operation is similar in function to the submit_sm operation with the replace_if_present_flag set. However, with the replace_sm operation, if no messages exist in the SMSC which match the Message ID and Source_Address fields (i.e. source_addr_ton, source_addr_npi, and source_addr) of the message to be replaced, then the message is NOT submitted to the SMSC. In this regard, the submit_sm command with the replace_if_present_flag set is potentially more flexible, since if no matching message is found, a new message WILL be submitted to the SMSC. The submit_sm command with the replace_if_present_flag set is typically used in Voice Mail applications for this reason. Default addressing handling for the replace_sm operation is identical to that used for submit_sm. Refer to Section : Default Address Handling, for details. Note: It is not possible to replace a message submitted to a Distribution List, It is not possible to replace a message submitted to Multiple Recipients. For further details on the replace_sm operation, refer to the SMPP Technical Reference [1] SMPP-3.0/1.5-UD1

35 Telepath SMSC SMPP Application Reference SMPP Operations 3.12 ENQUIRE_LINK Operation This operation is used to provide a confidence check of the communication path between an ESME and the SMSC. On receipt of this request the SMSC will simply respond with an enquire_link_resp, thus verifying that the application level connection between the ESME and the SMSC is functioning. The ESME can respond with any SMPP primitive. Since the enquire_link operation is an application primitive it is queued behind other outstanding requests/messages. An enquire_link command can also originate from the SMSC. In this event, the ESME must respond within a predefined timeout period as specified by the configurable parameter ext_sme_ack_timeout_sec, which is set by the SMSC Administrator (Refer to Table 4-1: SMPP Configurable Parameter subset ). The response from the ESME can take the form of either an enquire_link_resp acknowledgement or any valid SMPP message. For further details on the enquire_link operation, refer to the SMPP Technical Reference [1]. SMPP-3.0/1.5-UD1 3-19

36 SMPP Operations Telepath SMSC SMPP Application Reference 3-20 SMPP-3.0/1.5-UD1

37 Telepath SMSC SMPP Application Reference System Configuration 4. System Configuration Messages sent between the ESME and SMSC and the responses to those messages are associated by the Sequence Number field in the SMPP short message header. Allocation and tracking of this reference Sequence Number is the responsibility of the message originator, which must ensure that the Sequence Number is increased sequentially for each subsequently submitted message. The associated message response must preserve this field. 4.1 Messages originated by the ESME In this case the ESME must allocate the Sequence Number field contained in the SMPP short message header and must ensure that it is increased sequentially for each subsequently submitted message. However, if a particular message is being retransmitted, the Sequence Number should be identical to that used in the original message. For example:- if a submit_sm message sent by the ESME is not responded to by the SMSC within the defined timeout period, the ESME should resend the submit_sm message using the same Sequence Number in the message header. If the same Sequence Number is not used, the second submit_sm message issued will be treated as a new transaction by the SMSC. The associated message response from the SMSC will preserve the Sequence Number value contained in the original message sent from the ESME. 4.2 Messages originated by the SMSC For the most part, the messages issued by the SMSC will be in response to commands initiated by and submitted from the ESME. However, the SMSC can also originate messages such as unbind, deliver_sm and enquire_link etc. In the case of deliver_sm, the SMSC will allocate a sequentially increasing Sequence Number for each deliver_sm message issued and the ESME should preserve this field in the corresponding deliver_sm_resp acknowledgement. The SMSC may also issue multiple deliver_sm messages without receiving an immediate response from the ESME. In this event, the SMSC will maintain a table of the unacknowledged deliver_sm messages together with a time stamp corresponding to the time of transmission. The maximum number of outstanding unacknowledged deliver_sm, commands is specified by the ext_sme_buf_pool_sze parameter which is configurable within the Telepath SMSC System Manager Terminal (TPSMT) by the SMSC Administrator. If the ESME does not respond to a deliver_sm message from the SMSC within a predefined timeout period specified by the ext_sme_ack_timeout_sec parameter, which is also configurable by the SMSC Administrator via the Telepath SMSC System Manager Terminal (TPSMT), the SMSC considers that the operation has been unsuccessful. SMPP-3.0/1.5-UD1 4-1

38 System Configuration Telepath SMSC SMPP Application Reference The SMSC will remove the unsuccessful deliver_sm message from the table of unacknowledged deliver_sm messages and will then retransmit the deliver_sm message which will be tracked via a new Sequence Number. The deliver_sm_resp from the ESME must then preserve the new Sequence Number value in the header portion of the message. Note: Telepath SMSC provides a number of configurable parameters which are managed by the SMSC Administrator from within the Telepath SMSC System Manager Terminal (TPSMT). The configurable parameters relevant to ESME operations are defined in Table 4-1: SMPP Configurable Parameter subset. Parameter Name Default Value Unit Type Description ext_sme_ack_timeout_sec 5 Seconds Timeout period within which the ESME must respond to with an acknowledgement to a message issued from the SMSC. The SMSC retains a record of all messages or commands issued to the ESME along with a time stamp indicating the time of transmission. If an acknowledgement to a particular message is not received within the timeout period, a corrective action may be taken by the SMSC. For example, if the ESME does not respond to a deliver_sm message within the timeout period, the SMSC will consider the operation to be unsuccessful and will retransmit the deliver_sm message ext_sme_buf_pool_sze 100 Integer Maximum number of outstanding unacknowledged deliver_sm commands allowed. Table 4-1: SMPP Configurable Parameter subset 4-2 SMPP-3.0/1.5-UD1

39 Telepath SMSC SMPP Application Reference Regular Expressions 5. Regular Expressions The ESME system may act as a stand-alone entity or alternatively as a gateway for transporting messages to and from other ESMEs (refer to Figure 2.2). An ESME gateway bound as a receiver (via the bind_receiver command), may specify a range of ESME addresses to which it will route messages. The range of addresses to which the ESME will route messages is defined by an addr_ton, addr_npi field and an address_range field. The address_range field is represented by a regular expression as described in Section : Default Interface Addressing. In this context a regular expression is defined as a text pattern representing a specific address or a range of addresses. The text pattern may include both normal and special characters. 5.1 Special Characters used for Address Routing. matches any single character. [123] defines a character class of the numbers 123. [^123] defines a character class that does not match 123. [1-3] defines a character class range 1 to 3 exclusive. ( ( 1 2 ) states match 1 OR 2 ) * matches zero or more occurrences of a match of the preceding character. ^ Forces a match at the beginning. $ Forces a match at the end. Or Character. SMPP-3.0/1.5-UD1 5-1

40 Regular Expressions Telepath SMSC SMPP Application Reference 5.2 Examples of using Regular Expressions for Address Routing Routing Expression Description ^ Routes to all numbers beginning with (^ means match all numbers beginning with ) ^ [4-6]...$ Routes to all numbers in the range : to Note: -([4-6] defines a character class range) -(The 4 period characters at the end of the expression indicate the number of remaining characters in the telephone number). -($ forces a match at the end) ^0044( ) ^ ([1-2] [4-5] [7-9])...$ Routes to two independent number sets, i.e. all numbers beginning with : and Note: - (The expression (a b) means match a OR b ). Routes to three independent number sets, i.e. all numbers in the ranges : to OR to OR to Note: ($ forces a match at the end) [02468]$ Routes to all even numbers Note: ($ forces a match at the end) ^ [0-9]*[13579]$ Routes to all odd numbers beginning with Note: (* means match one or more occurrences of the preceding character ) -($ forces a match at the end) Table 5-1: Regular Expression Examples 5-2 SMPP-3.0/1.5-UD1