SMPP API Supplementary Documentation

SMPP API Supplementary Documentation


MessageMedia - SMPP API Supplementary Documentation 2

IntroductionThis document lists the specific features of the SMPP specification supported by the MessageMedia SMPP API.

The MessageMedia SMPP API supports v3.4 of the SMPP specification (except where indicated). http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf

Table of Contents

1. Connection details 3

- 1.1 Server 3

- 1.2 Security 3

- 1.3 Credentials 3

- 1.4 Bind types 3

- 1.5 Simultaneous bind limits 3

- 1.6 Throughput 4

- 1.7 Heartbeating / keep-alive (enquire_link) 4

2. SMPP command support 4

3. Message sending 5

- 3.1 TON and NPI values 5

3.1.1 Type of Number (TON) 5

3.1.2 Number Plan Indicator (NPI) 5

- 3.2 Source address 6

- 3.3 Destination address 6

- 3.4 Scheduled delivery 6

- 3.5 Validity period 7

- 3.6 Requesting delivery receipts (DR) (registered_delivery) 7

- 3.7 Character encoding (data_coding) 7

- 3.8 Long message support 8

3.8.1 About long message handling 8

- 3.9 Custom TLV (optional parameters) 9

4. Receiving DR (delivery receipt) messages 9

- 4.1 Message ID 9

- 4.2 Message (DR) statuses 10

4.2.1 Message status for long (concatenated) messages 10

5. Receiving MO (mobile originated) messages 11

- 5.1 Message ID 11

- 5.2 Character encoding 11

- 5.3 Long messages 11

6. Further information 11

http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf



1. Connection details1.1 Server

Address smpp.messagemedia.com

Port 2775

Port (TLS) 3775

The server is located in Sydney, Australia.

1.2 Security

SMPP over SSL / TLS is supported. The certificate is issued to *.messagemedia.com by Thawte.

1.3 Credentials

• Username (SMPP system_id) - maximum length of 15 ASCII characters (16 octets, including NULL terminator)

• Password - maximum length of 8 ASCII characters

These will be provided to you by the MessageMedia support team.

1.4 Bind types

The MessageMedia SMPP API supports the following bind types:

Bind type Capabilities SMPP PDU Required fields Notes

Transmitter (Tx) Submit MT messages bind_transmittersystem_id; password • system_type

is not required

• unbind is supported to cleanly unbind

Receiver (Rx)Receive MO and DR type messages

bind_receiversystem_id; password

Transceiver (TRx)Submit MT and receive MO and DR messages

bind_transceiversystem_id; password

1.5 Simultaneous bind limits

Simultaneous bind limits are configurable for each bind type. Bind limit policy enforcement is configurable to:

• Prevent new: additional binds beyond the configured limit are not accepted (default)

• Kick oldest: Accept the new bind request and terminate (after ~ 30 sec) the oldest bind for the account

MessageMedia will advise you of the number of simultaneous connections available for your account. Additional binds may be provided, based on your needs.



1.6 Throughput

Throughput per bind is dependent on the SMPP client capabilities and location, but rates of up to 60 MT/sec for each bind are possible in ideal circumstances.

1.7 Heartbeating / keep-alive (enquire_link)

Either server or client initiated heartbeats must be enabled (but not necessarily responded to).

Client initiated heartbeat

enquire_link• SMPP API will respond with enquire_link_resp

• Option to drop bind if no request is received after a timeout

Server initiated heartbeat

enquire_link• Interval can be configured

• Can be configured to drop the bind if a response from the client is not received

2. SMPP Command SupportEither server or client initiated heartbeats must be enabled (but not necessarily responded to).

Scope Command PDU PDU response Supported? Notes

Session management

bind_transmitter

bind_transmitter_resp

bind_receiverbind_receiver_resp

bind_transceiver

bind_transceiver_resp

unbind unbind_resp

enquire_linkenquire_link_resp

Message submission & delivery

submit_sm submit_sm_resp

Refer below for details

deliver_sm deliver_sm_resp

Ancillary generic_nack deliver_sm_resp

If we receive a generic_nack, delivery will be retried several times, before giving up. The connection will be unbound and you will need to re-connect.



3. Message Sending3.1 TON and NPI values

3.1.1 Type of Number (TON)

TON Definition Source Destination Notes

0 UnknownMay work for certain numbers, but is not recommended; contact MessageMedia for more details.

1 InternationalTON 1 is the preferred value for most destination numbers. Refer examples below.

2 National

3 Network Specific

4 Subscriber number

5 Alphanumeric

6 Abbreviated

3.1.2 Number Plan Indicator (NPI)

NPI Definition Source Destination Notes

0 Unknown

1 ISDN (E.164) Preferred

6 Land mobile

8 National



3.2 Source address

You may specify null for source_addr and a source address will be assigned from the MM rotary or based on your account preferences.

Number format Example(s) TON value NPI value Notes

International (E.164)+61497675300,61497675300

1 1 This is the preferred format

National 0497675300 2 1

Shortcode 19926646 3, 4

Either TON is acceptable for use of a shortcode

• Maximum length is 20 characters, butmany downstream providers onlysupport 11 characters

• 0-9, a-z, A-Z only; characters such as . - +may be supported, but delivery can notbe guaranteed

Alphanumeric MsgMedia 5

3.3 Destination address

Number format Example(s) TON value NPI value Notes

International (E.164)+61497675300,61497675300

1 1 This is the preferred format

National 0497675300 2 1

Shortcode 19926646Delivery to shortcode numbers is not supported.

Alphanumeric MsgMediaDelivery to alphanumeric addresses is not supported.

3.4 Scheduled delivery

Not currently supported via our SMPP API.

Scheduling is available by using our REST API.



3.5 Validity period

Customers may specify a validity period for a message, after which the message will be discarded. If the message is passed to a downstream service provider who does not support the validity period, it may be delivered after the validity period specified.

Both absolute and relative validity periods are supported.

3.6 Requesting delivery receipts (DR) (registered_delivery)

Delivery receipts may be requested for MT messages by using the registered_delivery parameter. The SMPP API does not currently support returning DRs only on failure or success.

Refer to DR statuses for details of the status values being returned.

3.7 Character encoding (data_coding)

The MessageMedia SMPP API supports the following character sets. The default character set (DCS=0) is GSM Extended 03.38. Refer:

https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38

Character set Support DCS value Message unit Notes

GSM 03.38 basic & extended characters

0140 bytes (octets) = 160 GSM 03.38 basic characters

• Supported for both sending (MT) and receiving (MO)

• GSM Extended characters such as { ^ and € require 2-bytes

Latin 1 / ISO-8859-1 3140 bytes (octets) = 140 ISO-8859-1 characters

MT only

UCS-2 (ISO/IEC-10646) 8140 bytes (octets) = 70 UCS-2 characters

This character set allows use of characters in the Unicode BMP (Basic Multilingual Plane)



3.8 Long message support

The MessageMedia SMPP API supports the sending of messages greater than 160 standard GSM characters. Long messages may be sent using one of the following methods:

Long message method Limits Notes

short_message 255 octetsThe MM gateway will handle segmentation of your message

message_payload 65,535 octets (configurable)

UDH concatenation

• 134 bytes available for message content

• 6 bytes used by UDH header

• Maximum of 255 segments supported

Message content may contain up to 153 GSM 03.38 basic characters or 67 UCS-2 encoded characters

SAR concatenation • 255 segments

3.8.1 About long message handling

Note the following important points in relation to long message handling:

• A message will be considered ‘long’ when the content is more than 140 bytes (octets). This equates to 160 basic GSM characters or 70 UCS-2 encoded characters

• Extended GSM characters require an escape character, and thus consume two bytes.

• Where content includes characters outside of the GSM character set, the message may be sent as Unicode (UCS-2) in 70 character segments.

• Long messages may be concatenated and re-segmented in order to ensure the content can be delivered as intended.

• All segments of a long message must be received by the SMPP API for the message to be successfully delivered.

• MessageMedia will always try to use downstream service providers that support re-concatenation of long messages, but in rare cases this may not be possible.



3.9 Custom TLV (optional parameters)

The MessageMedia SMPP API supports the sending of messages greater than 160 standard GSM characters. Long messages may be sent using one of the following methods:

Name Tag Length Type Description / purpose Use

sending_account

0x1400 1 ~ 65,535 C-Octet String

When authorised to do so, SMPP clients may include this TLV in submit_sm requests to specify the account that the client is sending on behalf of.

May be optional, required or forbidden depending on the configuration of the SMPP account (system ID).

Contact MessageMedia support for more information.

message_flags

0x1401 1 ~ 65,535 C-Octet String

This parameter allows SMPP clients to pass specific flags that can be used to control how MessageMedia sends a message.

Contact MessageMedia support for more information.

May be optional, required or forbidden depending on the configuration of the SMPP account (system ID).

Only characters Aa-Zz and _ (underscore) are allowed. Case in-sensitive.

4. Receiving DR (delivery receipt) messages4.1 Message ID

The receipted_message_id parameter will contain the message ID of the MT message being receipted.

This will be in the format of UUID, version 4, random. These are in the form: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx



4.2 Message (DR) statuses

The MessageMedia SMPP API will return message status as a delivery receipt (DR) type message, using a deliver_sm command. Status will be encoded in both:

• the stat sub-field of the short_message parameter, as an abbreviated text status value;

• the message_state optional parameter, as a value

The API makes use of the following message statuses:

Message statusMessage_state value

Stat (short_message)

Type Description

ENROUTE 1 ENROUTE IntermediateThe message is being processed by the messaging centre or has been submitted to a downstream service provider for delivery.

DELIVERED 2 DELIVRD FinalMessage delivery has been confirmed by the service provider, including to the handset (where possible)

EXPIRED 3 EXPIRED FinalThe message validity period expired and the message has been discarded.

UNDELIVERABLE 5 UNDELIV Final

The message can not be delivered. Reasons may include the handset being offline, number being invalid.

An error code value may provide further information.

UNKNOWN 7 UNKNOWN n/aAn error occurred in the SMPP server. The message status can not be returned.

REJECTED 8 REJECTD Final

The message will not be delivered - permanent failure. Reasons may include the destination number being blocked; an account usage threshold being reached;

An error code value may provide further information.

4.2.1 Message status for long (concatenated) messages

Where delivery receipts have been requested for a long (UDH or SAR concatenated) message, the SMPP API will produce DRs for each message segment. Where segments in a long message have different status values, this will be represented in the DRs.



ABOUT MESSAGEMEDIAAs Australia’s largest business mobile messaging service provider and a leading player globally, our mission is to connect our customers with theirs through innovative mobile messaging solutions. Our unparalleled messaging platform ensures customer messages arrive on time and deliver optimum return on investment. The platform is underpinned by our service reliability and quality support to ensure communication solutions are never compromised.

AUSTRALIALevel 24 367 Collins Street Melbourne VIC 3000

T: 1800 009 767E: [email protected]

www.messagemedia.com.au

USA580 Howard Street, Suite 102 San Francisco CA 94111

T: 888-799-9767E: [email protected]

www.messagemedia.com

UKLevel 6 52 Grosvenor Gardens Victoria London SW1W 0AU

T: 0808 234 8246E: [email protected]

www.messagemedia.co.uk

5. Receiving MO (mobile originated) messages5.1 Message ID

Where applicable, MO responses will include the ID of the MT message being responded to within the receipted_message_id parameter.

5.2 Character encoding

MOs will use GSM 03.38 basic & extended character encoding, and DCS value of 0.

5.3 Long messages

If the message content is =< 254 octets, it will be contained within the short_message parameter of the deliver_sm request.

Long MO messages are supported, and depending on the SMPP account configuration, are delivered as:

• Single deliver_sm request, content contained in message_payload. Maximum length of message_payload is configurable.

• Content segmented over multiple MO messages

- Use message_payload if configured; otherwise short_message

- concatenated with either SAR or UDH

- if neither enabled, then as individual message fragments

6. Further informationIf you require further assistance, or would like more information on working with our SMPP API, please contact our Support team.

Documents

SMPP API Supplementary Documentation