v1.1, 2024-10-17
Copyright © 2024 Telia Company. All rights reserved.
Revisions
| Version | Date | Changes |
|---|---|---|
v1.0 |
2024-09-18 |
First version |
v1.1 |
2024-10-17 |
Updated TLS documentation for SMPP |
1. Introduction
1.1. Audience
This document is intended for developers who are implementing messaging services. It provides detailed technical information necessary for successfully integrating an IT application with the messaging infrastructure provided by Telia.
The document assumes a thorough understanding of the GSM/UMTS Short Message Service (SMS) architecture.
Additionally, users should be familiar with the Bulk Messaging agreement.
1.2. Service overview
Telia Bulk Messaging consists of several different services and offerings. Below you will find a description of all the services.
1.2.1. Bulk SMS
Bulk SMS is a service that offers the customer a connection to the Bulk Messaging Platform of Telia for sending and receiving SMS messages via a technical interface (API). The messages can be sent to mobile terminals connected to the SMS central in the mobile networks of Telia via a SMS access number. The service supports receipt of messages sent to an access number only from mobile terminals connected to the mobile network and SMS central of Telia.
1.2.2. SMS Long Number
A virtual mobile number used for receiving SMS messages sent from mobile terminals. Together with the Bulk SMS service for sending messages, this enables two-way SMS messaging. This service supports receiving SMS messages sent from end user terminals with a subscription from all mobile operator that Telia has an SMS interconnect agreement with.
1.2.3. Sender ID Protection
The SenderID Protection service makes sure an SMS with a specific senderID/Originating Address (OA) only can be sent from a predefined list of access number(s). Purpose is to avoid misuse (spoofing) of senderID/OA. If the senderID/OA originates from an access number not on the list, Telia will block the message and return an error code.
Each protected senderID/OA will also have a blacklist of alias/look-alike senderIDs. If a message uses a blacklisted senderID, the API will return OK, but the message will be blocked and charged. The invoice will have a separate line for blacklisted messages.
1.2.4. RBM
RBM (RCS Business Messaging) is a messaging service provided by Google that enables businesses to communicate with end users using RCS messages. The messaging service features several capabilities like: Verified SenderID (name and logo), photo, video, chat, buttons, usage statistics and more for branded, interactive mobile end user experiences.
The RBM product sold by Telia is based on the Messages app from Google (or other messaging apps supported by Google) and the Jibe back-end platform from Google. The product charges communication with end users in the Telia mobile network in the country that is covered by the Telia Bulk Messaging agreement signed.
Link to the Google website with service description and detailed functional and technical documentation of the RBM service:
https://developers.google.com/business-communications/rcs-business-messaging
Technical support inquiries shall be directed to Google, not to the Telia Bulk Messaging Support.
2. Getting started
2.1. Sign Bulk Messaging agreement with Telia
This agreement is offered uniquely for each Telia country meaning you must sign a separate agrement with Telia in the country you would like to send SMS messages to. You can get in contact with the person signing the agreement from Telia by contacting the Telia Bulk Messaging Support team. The contact details are found in the Bulk Messaging agreement Appendix 2 - Contact information and ordering process document. These documents can be downloaded from the Bulk Messaging Web portal: https://messaging.teliacompany.com/documents.
2.2. Order service
Send the documents "General customer form" and "Technical information form" filled with the relevant information to the Bulk Messaging Support team to be set up as a customer. These documents can be downloaded from the Bulk Messaging Web portal: https://messaging.teliacompany.com/documents.
2.3. Welcome e-mail
Receive the welcome e-mail from the Bulk Messaging Support team with instructions on how to log in to the Telia Bulk Messaging Web portal. This is sent to the commercial contact person of the customer signing the Bulk Messaging agreement.
2.4. Update login credentials
Log in to the portal with the credentials provided to the Commercial contact. To create API credentials, the user must have an Administrator or Technical user role assigned. Administrators can create users and assign roles. It is recommended to create at least one Administrator and Technical user.
2.5. Update contact information
Log in to the Web portal and create communication contacts that will be informed by Telia in relevant situations according to the contact type.
You are now ready to order one or several of the Telia Bulk Messaging services listed in the Bulk Messaging agreement appendix 3 Product Summary.
3. API Reference
Telia provides several APIs to send and receive SMS and RCS messages. Google RCS Business Messaging APIs are used to send and receive RCS messages. Documentation of RCS APIs can be found on Google RCS Business Messaging site here: https://developers.google.com/business-communications/rcs-business-messaging.
SMS APIs are provided by Telia Company and this document will provide information on how to get access and use these APIs. Telia Company Bulk Messaging platform provdides the following APIs for sending and receiving SMS:
-
SMS REST API for sending SMS
-
SMS REST Callback API for receiving SMS and delivery reports
-
SMPP API for sending and receiving SMS and delivery reports
There are three prerequisties that must be in place before start using Telia Company Bulk Messaging SMS APIs:
-
Signed Bulk Messaging Agreement (more information here)
-
User with access to Telia Company Business Messaging Web Portal
-
Active SMS service
3.1. Telia Company Bulk Messaging Web Portal
The Telia Company Bulk Messaging Web portal is a self-service portal where customers can create users, API credentials and get access to statistics, reports and related information.
To enable API access customer need to sign in as a user with administrator or technical user role. This will allow user to access product page with functionality to select API protocol and create API credentials.
3.2. Create API credentials
To create an API user customer first need to sign in as a user with an administrator or technical role assigned. After sign-in, click on the SMS product of choice under "Provisioning" sub-section. This section will give access to multiple sub pages like company information, users, contracts, services and communication:
Select Services section and click on selected service. Under the selected service you will have the option to select protocol and create API credentials under "Technical Configuration" section. For REST Callback API customer can also provide callback address and credentials for the callback API.
3.3. Select protocol
Both SMPP and REST API protocols support sending and receiving SMS messages. REST API is recommended for new integrations as it is easier to use. SMPP is recommended for high volume messaging and for customers that already have SMPP integration in place.
3.4. Addressing
Each SMS API has its own set of guidelines on how to format addresses in SMS messages. The following section provides common guidelines which is valid for all APIs.
3.4.1. Phone numbers
Mobile subscribers are identified using MSISDN number (e.g. +4712345678) matching E.164 numbering plan. MSISDN can be maximum 15 digits long including country code. Not all APIs require country code to be included in the MSISDN. Please refer to addressing sections for each API for more information.
3.4.2. Access numbers
Access numbers (or short numbers) are typically 4-digit or 5-digit numbers used for sending SMS messages. They are typically used for sending SMS messages to mobile subscribers and will be displayed as the originating address on the handset. If SMS service is associated with access number, then mobile subscribers can reply to the SMS messages. Access numbers are formatted without + prefix and country code.
3.4.3. Alphanumeric
SMS can have an alphanumeric Sender ID. Alphanumeric Sender ID is formatted as text as it will appear on handset. Alphanumeric addresses can be maximum 11 characters long. It can contain letters (A-Z), digits (0-9) and special characters part of GSM7 character set. However, spaces or special characters may not be supported by all carriers and handsets and must be tested prior sending batches of messages.
| SMS messages with an alphanumeric Sender ID cannot be replied to in the same way as those with access numbers. Additionally, some Sender IDs are reserved and cannot be used without an authorization from the brand using the SenderID. Trademarks and company names can also be reserved using the Sender ID Protection product. SMS messages with such alphanumeric addresses will not be delivered to recipients. |
3.4.4. Sub-numbers
A sub-number is a customer-defined number that is appended to an access number. It is used for enhanced message routing and tracking of messages. Use cases include SMS conversations, order tracking, and other personalized messaging.
Sub-numbers are currently supported only for Norwegian SMS services. Sub-numbers in Norway must be excatly 9-digits to avoid conflicts in the national numbering plan. Sub-numbers are supported for 4-digit and 5-digit acceess numbers.
Examples for sub-number 987654321:
| 4-digit (1989) |
1989987654321 |
| 5-digit (12345) |
12345987654321 |
3.4.4.1. Addressing policies
Each service on Telia Bulk Messaging Platform has defined rules for what is allowed to use in Sender ID field of a SMS. There are currently two categories:
| All |
No restrictions except reserved Sender IDs (trade marks, company names etc.) |
| Restricted |
Only allowed to use associated access number for SMS service for Sender ID |
Please contact Telia Company Bulk Messaging Support if you have questions regarding addressing policies and what is currently configured for your product.
3.5. SMS REST API
|
This guide describes the updated REST API which will be launched September/October 2024. If you are using older version of the API, you will still find the documentation in the Bulk Messaging Web Portal. |
The REST APIs has operations for sending SMS and receiving SMS and delivery reports. The SMS REST API is actually two different APIs:
-
SMS API
-
SMS Callback API
SMS API is for sending SMS. SMS Callback API is used for receiving callbacks from Telia Company Bulk Messaging Platform. This is used for delivery reports and mobile originated SMS. To receive SMS and delivery reports the customer is required to implement SMS Callback API for receiving callbacks from Telia Company Bulk Messaging Platform. The REST Callback API service implementation must match Open API specification that Telia Company provides.
All REST APIs are documented using industry standard Open API specification (https://www.openapis.org). The specifications are hosted on Telia Company Bulk Messaging Portal under the Documents section: https://messaging.teliacompany.com/documents.
3.5.1. Base URL
Complete URLs are specified in Open API specification. Base URL for all REST APIs are:
https://api.messaging.teliacompany.com/sms/rest/v2
3.5.2. Authentication
Create your credentials in Telia Bulk Messaging web portal as described in Update login credentials.
REST API use HTTP basic authentication. Here is an example sending a minimal "Hello World" message using cURL command line tool:
curl -X POST \
-H "Authorization: Basic dXNlcjpwYXNzd29yZAo=" \
-H "Content-Type: application/json" \
-d ' \
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "12345",
"message": "Hello World"
}' \
"https://api.messaging.teliacompany.com/sms/rest/v2/messages3.5.3. Formatting and conventions
REST API supports JSON (application/json) content type in all requests and responses. The following guidelines must be followed when integration towards SMS REST API.
3.5.3.1. Addressing
Each country has its own national numbering plan. But all countries share same formatting guidelines in the REST API. Please refer to the following sections for more information on addressing in SMS REST API.
Phone numbers
Mobile subscribers are identified using MSISDN number (e.g. +4712345678). All MSISDN numbers are required to be formatted with + prefix and country code matching E.164 numbering plan. Examples:
| Swedish number |
+46123456789 |
| Norwegian number |
+4712345678 |
| Lithuanian number |
+37012345678 |
Access numbers
Access numbers (or short numbers) are formatted without country code. They are typically 5 digits, but that may vary between countries and SMS services. Examples:
| 5-digit access number |
12345 |
| 4-digit access number |
1984 |
| EU harmonized 6-digit access number |
116000 |
It is recommended not to apply country code and + prefix to access numbers. Adding country code to access numbers may result in errors when sending SMS messages.
Alphanumeric
Alphanumeric Sender ID is formatted as text as it will appear on handset. Please refer to Addressing section for more information on alphanumeric addressing.
Sub-numbers
Sub-numbers are currently supported only for Norwegian SMS services. Sub-numbers are formatted as access numbers without country code.
Sub-numbers in Norway must be excatly 9-digits to avoid conflicts in the national numbering plan. Sub-numbers are supported for 4-digit and 5-digit acceess numbers. Examples for sub-number 987654321:
| 4-digit (1989) |
1989987654321 |
| 5-digit (12345) |
12345987654321 |
3.5.3.2. Timestamps
All timestamps are formatted using ISO-8601 standard. Example: 2024-07-01T14:00:00.000Z.
Timestamps can use any timezone or offset, but local offset or UTC timezone is recommended. Callbacks from SMS Callback API can also use any timezone or offset, but will typically use UTC timezone.
3.5.3.3. Empty values and fields
Fields which are optional can be omitted from requests and responses. Client should not send null for empty fields in requests.
3.5.4. Operations
SMS REST API has two operations:
| Submit SMS message (MT) |
Send SMS messages to mobile subscribers |
| Submit SMS content (MT) |
Sends SMS messages with full control over content (advanced usage) |
SMS REST Callback API has two operations
| Receive SMS (MO) |
Receive SMS messages from mobile subscribers |
| Receive delivery report (DLR) |
Receive delivery reports for sent SMS messages |
| MT, MO and DLR are abbrevations for Mobile Terminated, Mobile Originated and Delivery Report. Abbrevations indicate message type and direction of message. |
Submit SMS message is used to send SMS messages to mobile subscribers. Submit SMS content is used to send SMS messages with content that is not plain text. Receive SMS is used to receive SMS messages from mobile subscribers. Receive delivery report is used to receive delivery reports for sent SMS messages.
3.5.4.1. Submit SMS message
Submit SMS message is used to send SMS messages to mobile subscribers. Submit SMS requests are sent as HTTP POST to ~/messages endpoint. This operation is recommended for sending simple text messages. If you need to send messages with custom content and UDH headers, please use Submit SMS content operation.
For detailed description on each field, please refer to Open API specification.
Minimal example
The following REST API request illustrates a minimum submit message sent from access number 12345 to mobile subscriber identity +4712345678
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "12345",
"message": "Hello World"
}Send SMS message with more than 140 bytes
Long text messages can be sent the same way as short messages. The message will be split into multiple segments automatcially and sent as separate SMS messages. The message will be concatenated on the handset. The maximum number of segments varies between SMSCs and operators. SMS Bulk Messaging API accepts up to 16 segments. The maximum number of characters in a segment is 153 if using GSM character set.
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "8400",
"message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
}Send SMS message with emoji
Emojis can be sent by specifying UNICODE as data coding. The emoji in the REST payload can be encoded using the character encoding in the HTTP request (typically UTF-8) or use escape sequences.
Example text encoding in HTTP request:
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "8400",
"message": "😀",
"dataCoding": "UNICODE"
}Submit SMS message as flash SMS
Flash SMS is a type of SMS message that appears directly on the recipient’s phone screen without needing to be opened and typically doesn’t get saved in the message inbox. Flash SMS can be sent setting flash element to true:
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "8400",
"message": "Flash SMS",
"flash": true
}3.5.4.2. Submit SMS content
Submit SMS content is used to send SMS messages with custom content. The content can be a simple text message, a message with custom data coding scheme (DCS), message with multiple segments and message with binary content. Submit SMS content requests are sent as HTTP POST to ~/content endpoint. This operation is recommended for sending messages with custom content. If you need to send simple text messages, recommendation is to use Submit SMS message operation.
Minimal Submit Content SMS
This example uses submit content SMS operation to send a message with custom content. The content is a simple text message.
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "Telia",
"content": {
"message": "Hello World"
}
}Submit Content SMS with custom DCS
This example uses the submit content SMS operation to send a message with custom data coding scheme (DCS). The DCS is set to 8 which is used for Unicode messages.
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "Telia",
"content": {
"message": "Hello World"
},
"dcs": 8
}Submit Content SMS with multiple segments
This example uses the submit content SMS operation to send a message with multiple segments. The submit content API allows sending messages with multiple segments by providing a list of content items. Each content item can have a header and a message. This can be used if customer wants complete control over the message content and how it is split into segments.
Please note that the header needs to be formatted according to SMS specification. The header is used to identify the message content and is used by the handset to concatenate the message. The header must be unique for each message. The header is typically a 16-bit number. Also note that each segment can be max 140 bytes long.
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "Telia",
"content": [
{
"header": "06080400040301",
"message": "This is first part."
},
{
"header": "06080400040302",
"message": "This is second part."
},
{
"header": "06080400040303",
"message": "This is third part."
}
]
}Submit Content SMS with Custom HEX Encoded Body
This example uses the submit content SMS operation to send a message with custom HEX encoded body. The content is a simple text message encoded as HEX. The data coding scheme (DCS) is set to 0 which is used foto specify default SMSC character set (GSM 7-bit).
{
"cref": "47aaf1fd-0910-4a69-bc64-affe49df9dfb",
"to": "+4712345678",
"from": "Telia",
"content": {
"message": "C8329BFD06DDDF723619",
"format": "HEX"
},
"dcs": 0
}3.6. SMPP API
The Telia Bulk Messaging platform supports the SMPP protocol for sending and receiving SMS messages. SMPP is recommended for high-volume messaging and for customers that already have SMPP integration in place.
The SMPP API is documented using SMPP 3.4 specification. The specification can be downloaded from https://smpp.org.
This document will provide information on which operations and parameters are supported by the Telia Company Bulk Messaging SMPP API.
3.6.1. Endpoint
The SMPP API is accessed over a TLS connection (minimum TLS 1.2). The endpoint for the SMPP API is:
smpp.messaging.teliacompany.com:3550
3.6.1.1. TLS ciphers
The following ciphers are supported for SMPP TLS connections:
-
TLS_AES_128_GCM_SHA256
-
TLS_AES_256_GCM_SHA384
-
TLS_CHACHA20_POLY1305_SHA256
-
ECDHE-ECDSA-AES128-GCM-SHA256
-
ECDHE-RSA-AES128-GCM-SHA256
-
ECDHE-ECDSA-AES128-SHA256
-
ECDHE-RSA-AES128-SHA256
-
ECDHE-ECDSA-AES256-GCM-SHA384
-
ECDHE-RSA-AES256-GCM-SHA384
-
ECDHE-ECDSA-AES256-SHA384
-
ECDHE-RSA-AES256-SHA384
3.6.2. Access Control List (ACL)
The SMPP API requires a static IP addresses to be whitelisted in the ACL. The IP address must be provided to Telia Company Bulk Messaging Support team for whitelisting. The IP address must be static.
3.6.3. Definitions of Terms Used in This SMPP Guide
| ESME |
External Short Message Entity. The application that sends and receives SMS messages using the SMPP protocol. |
| SMSC |
Short Message Service Center. The Telia Bulk Messaging SMPP API. The entity that receives and delivers SMS messages to mobile subscribers. |
| SME |
Short Message Entity. The mobile subscriber that sends and receives SMS messages. |
| TON |
Type of number. Used in addressing to specify the type of number being used in the address. |
| NPI |
Numbering plan indicator. Used in addressing to specify the numbering plan being used in the address. |
3.6.4. Addressing
Addressing in the SMPP API requires TON (type of number) and NPI (number plan indicator) values to be set for source and destination addresses in the SMPP requests and responses. TON and NPI values are used to specify the type of number and numbering plan being used in the address. The following tables show the supported TON and NPI values:
3.6.4.1. TON
| TON | Value | Description |
|---|---|---|
Unknown |
0x00 |
Used if the number type is unknown. It is recommended to use specific TON values for predictable results. |
International |
0x01 |
International numbers with country code. Example with country code 47 and local number 12345678: 4712345678. |
Network specific |
0x03 |
Access numbers (short numbers). Example short code 12345: 12345 |
Alphanumeric |
0x05 |
Alphanumeric addresses. Example: Telia. |
Using other TON values than the ones listed above may result in errors when sending SMS messages. Please refer to SMPP specification for more information on addressing in the SMPP protocol.
3.6.4.2. NPI
| NPI | Value | Description |
|---|---|---|
Unknown |
0x00 |
Used for alphanumeric and short numbers. |
ISDN/telephone numbering plan (E.164/E.163) |
0x01 |
Used for E164 encoded numbers. |
Using NPI values other than the ones listed above may result in errors when sending SMS messages. Please refer to SMPP specification for more information on addressing in the SMPP protocol.
3.6.4.3. TON and NPI combinations
The following table shows the recommended TON and NPI combinations for different types of addresses:
| Address type | Example | TON | NPI |
|---|---|---|---|
International number |
4712345678 |
International (0x01) |
ISDN/telephone numbering plan (0x01) |
Short number |
12345 |
Network specific (0x03) |
Unknown (0x00) |
Alphanumeric address |
Telia |
Alphanumeric (0x05) |
Unknown (0x00) |
3.6.5. Connect and read timeouts
Recommended connect and read timeouts for SMPP connections are 10 seconds. If the SMSC or ESME does not respond within 10 seconds, the connection should be closed and re-established.
3.6.6. SMPP connection count
The number of SMPP connections that can be established between the ESME and the SMSC is limited. The number of connections is defined in the Bulk Messaging Web portal. The ESME must not establish more connections than the number defined in the Web portal. If the ESME tries to establish more connections than the defined number, the SMSC will reject the connection request.
It is important to note that the number of connections is defined per service. If the ESME has multiple services, the number of connections is defined per service.
3.6.7. Graceful unbind and patching
The ESME should always send an unbind request to the SMSC before closing a connection. The SMSC will respond with an unbind response. The ESME should wait for the unbind response before closing the connection. If the SMSC does not respond with an unbind response, the ESME should close the connection after timeout period defined in Connect and read timeouts section.
An unbind can also be initiated by the SMSC at any time. The ESME must respond with an unbind response to acknowledge the unbind request. SMSC will close the connection if it does not receive an unbind response within timeout defined in Connect and read timeouts section. The ESME should immediately re-establish the connection and send a bind request to the API to re-establish the connection.
To trigger a graceful unbind initiated by SMSC, customer can log into Bulk Messaging Web Portal and click unbind in the SMPP connections view. This will send an unbind request to the ESME.
Graceful unbind from SMSC is implemented to support patching and maintenance of the SMSC. The SMSC will send an unbind request to the ESME before shutting down the connection. The ESME must respond with an unbind response to acknowledge the unbind request. The ESME must close the connection after sending the unbind response. The ESME should then immediately re-establish the connection and send a bind request to the SMSC to re-establish the connection. SMSC will send unbind with a delay between each SMPP session so avoid downtime on ESME side.
3.6.8. Character sets
Default character set for the SMPP API can be configured on Telia Bulk Messaging Web Portal. Default setting is GSM character set encoded into octects (also called GSM8).
The following character sets can be configured as default SMSC character set on Bulk Messaging Web Portal:
-
GSM 7-bit alphabet encoded into octets (GSM8)
-
GSM 7-bit alphabet encoded into septets (GSM7)
-
Latin-1 (ISO-8859-1)
-
Latin-9 (ISO-8859-15)
The following character sets are supported by using correct data coding scheme (DCS) in the SMPP requests and responses:
-
Latin-1 (ISO-8859-1)
-
UCS-2 (Unicode)
3.6.9. SMPP window size
Default window size is set to 10, but can be adjusted by contacting Telia Bulk Messaging Support team. The window size is the number of PDUs that can be sent before receiving a response from the SMSC. The ESME must not send more PDUs than the window size before receiving a response from the SMSC. If the ESME sends more PDUs than the window size, the SMSC will reject the PDUs.
3.6.10. Error codes
The Telia Company SMPP API use standard SMPP error codes. Please refer to SMPP specification for more information on error codes.
3.6.11. Operations supported
| Operation | Description |
|---|---|
bind_transmitter |
The bind operations are used to establish a connection between the ESME and the SMSC. The ESME can be either a transmitter, receiver or transceiver. The ESME must send a bind request to the SMSC to establish a connection. The SMSC will respond with a bind response. The ESME must send a bind request before sending any other requests. |
unbind |
The unbind operation is used to terminate an SMPP session. The ESME must send an unbind request to the SMSC to terminate the session. The SMSC will respond with an unbind response. The ESME must send an unbind request before closing the connection. |
enquire_link |
The enquire_link operation is used to check the status of the connection between the ESME and the SMSC. The ESME can send an enquire_link request to the SMSC to check if the connection is still alive. The SMSC will respond with an enquire_link response. |
submit_sm |
The submit_sm operation is used to send an SMS message from the ESME to the SMSC. The ESME must send a submit_sm request to the SMSC to send an SMS message. The SMSC will respond with a submit_sm response. The ESME can also receive a deliver_sm request from the SMSC with the status of the submitted message. |
deliver_sm |
The deliver_sm operation is used to deliver an SMS message or delivery report from the SMSC to the ESME. The SMSC will send a deliver_sm request to the ESME with the status of the delivered message. The ESME must respond with a deliver_sm response to acknowledge the delivery of the message. |
The following sections will provide detailed information on each operation supported by the SMPP API. Compliance levels are defined as follows:
| FC |
Fully compliant |
| PC |
Partially compliant |
| NC |
Not compliant |
3.6.11.1. bind_transmitter, bind_receiver, bind_transceiver
| Field | Description | Compliance |
|---|---|---|
command_length |
Defines the overall length of the bind_transmitter PDU. |
FC |
command_id |
Value corresponding to bind_receiver (0x00000001), bind_transmitter (0x00000002) or bind_transceiver request (0x00000009). |
FC |
command_status |
Not in use in bind_transmitter. Set to NULL. |
FC |
sequence_number |
Set to a unique sequence number. The associated bind_transmitter_resp PDU will echo this sequence number. |
FC |
system_id |
The user name used for authentication. |
FC |
password |
The password used for authentication. |
FC |
system_type |
Not in use - should be set to NULL. |
PC |
interface_version |
Must be set to 0x34. |
FC |
addr_ton |
Not in use - should be set to NULL. |
PC |
addr_npi |
Not in use - should be set to NULL. |
PC |
address_range |
Not in use - should be set to NULL. |
NC |
3.6.11.2. unbind
| Field | Description | Compliance |
|---|---|---|
command_length |
Defines the overall length of the unbind PDU. |
FC |
command_id |
Value corresponding to unbind request (0x00000006). |
FC |
command_status |
Not in use in unbind. Set to NULL. |
FC |
sequence_number |
Set to a unique sequence number. The associated unbind_resp PDU will echo this sequence number. |
FC |
3.6.11.3. enquire_link
| Field | Description | Compliance |
|---|---|---|
command_length |
Defines the overall length of the enquire_link PDU. |
FC |
command_id |
Value corresponding to enquire_link request (0x00000015). |
FC |
command_status |
Not in use in enquire_link. Set to NULL. |
FC |
sequence_number |
Set to a unique sequence number. The associated enquire_link_resp PDU will echo this sequence number. |
FC |
3.6.11.4. submit_sm
| Field | Description | Compliance |
|---|---|---|
command_length |
Defines the overall length of the submit_sm PDU. |
FC |
command_id |
Value corresponding to submit_sm request (0x00000004). |
FC |
command_status |
Not in use in submit_sm. |
FC |
sequence_number |
Set to a unique sequence number. The associated submit_sm_resp PDU will echo this sequence number. |
FC |
service_type |
Must be empty string for SMS. Other values will be ignored. |
PC |
source_addr_ton |
The source_addr_ton parameter is used to specify the type of number being used in the source address. |
FC |
source_addr_npi |
The source_addr_npi parameter is used to specify the numbering plan being used in the source address. |
FC |
source_addr |
The source_addr parameter is used to specify the address of the SME which originated this message. |
FC |
dest_addr_ton |
The dest_addr_ton parameter is used to specify the type of number being used in the destination address. |
FC |
dest_addr_npi |
The dest_addr_npi parameter is used to specify the numbering plan being used in the destination address. |
FC |
destination_addr |
The destination_addr parameter is used to specify the address of the SME which is to receive the message. |
FC |
esm_class |
See section esm_class (submit_sm) for supported values |
PC |
protocol_id |
Must be set to 0x00. |
PC |
priority_flag |
Not in use. Should be set to 0x00 (default priority). |
PC |
schedule_delivery_time |
The schedule_delivery_time parameter is used to specify the scheduled delivery time of the message. |
FC |
validity_period |
The validity_period parameter is used to specify the validity period of the message. |
FC |
registered_delivery |
The registered_delivery parameter is used to request an SMSC delivery receipt. See section registered delivery (submit_sm) for supported values. |
PC |
replace_if_present_flag |
Not in use. |
NC |
data_coding |
The data_coding parameter is used to indicate the data coding scheme of the message. |
PC |
sm_default_msg_id |
Not in use. |
NC |
short_message |
The short_message parameter is used to specify the short message to be sent. |
FC |
esm_class (submit_sm)
The esm_class parameter is used to indicate special message attributes associated with the short message. The ESM Class byte is structured into three sections. The following table shows supported values for each section in submit_sm operation:
| Section | Supported values |
|---|---|
Message Mode (bits 1-2) |
0x00: Default, 0x03: Store and Forward |
Message Type (bits 3-5) |
0x00: Default, 0x01: Delivery Receipt |
GSM features (bits 6-8) |
0x00: Default, 0x01: UDHI Indicator |
registered delivery (submit_sm)
registered_delivery parameter is used to request an SMSC delivery receipt. The following table shows supported values for registered_delivery parameter in submit_sm operation:
| Section | Supported values |
|---|---|
SME Originated Acknowledgment Requests (bits 1-2) |
0x00: No receipt requested, 0x01: Delivery receipt requested. |
SME Delivered Acknowledgment Requests (bits 3-4) |
0x00: No acknowledgment requested from the SME (default). |
Intermediate Notification Request (bit 5) |
0x00: No intermediate notification requested (default). |
Receipt on Message Replacement (bit 8) |
0x00: No special notification for message replacement (default). |
3.6.11.5. deliver_sm
| Field | Description | Compliance |
|---|---|---|
command_length |
Defines the overall length of the deliver_sm PDU. |
FC |
command_id |
Value corresponding to deliver_sm request (0x00000005). |
FC |
command_status |
Not in use in deliver_sm. Set to NULL. |
FC |
sequence_number |
Set to a unique sequence number. The associated deliver_sm_resp PDU will echo this sequence number. |
FC |
service_type |
Always empty string. |
PC |
source_addr_ton |
The source_addr_ton parameter is used to specify the type of number being used in the source address. |
FC |
source_addr_npi |
The source_addr_npi parameter is used to specify the numbering plan being used in the source address. |
FC |
source_addr |
The source_addr parameter is used to specify the address of the SME which originated this message. |
FC |
dest_addr_ton |
The dest_addr_ton parameter is used to specify the type of number being used in the destination address. |
FC |
dest_addr_npi |
The dest_addr_npi parameter is used to specify the numbering plan being used in the destination address. |
FC |
destination_addr |
The destination_addr parameter is used to specify the address of the SME which is to receive the message. |
FC |
esm_class |
The esm_class parameter is used to indicate special message attributes. Message type 0x01 is set if message is a DLR. |
PC |
protocol_id |
Always set to 0x00. |
PC |
priority_flag |
Always set to 0x00. |
PC |
schedule_delivery_time |
The schedule_delivery_time parameter is used to specify the scheduled delivery time of the message. |
PC |
validity_period |
The validity_period parameter is used to specify the validity period of the message. |
FC |
registered_delivery |
Always set to 0x00. |
FC |
replace_if_present_flag |
Not in use. |
NC |
data_coding |
The data_coding parameter is used to indicate the data coding scheme of the message. |
PC |
sm_default_msg_id |
Not in use. |
PC |
short_message |
The short_message parameter is used to specify the short message to be sent. |
FC |
3.6.12. TLV support
The SMPP API supports TLV (Tag-Length-Value) parameters. TLV parameters are used to provide additional information in the SMPP requests and responses. The following table shows the currently supported TLV parameters:
| Tag | Description | Compliance |
|---|---|---|
message_payload |
The message_payload TLV parameter is used to specify the message payload. This can be used to send long SMS messages without splitting into separate submit_sm |
FC |
network_error_code |
The network_error_code TLV parameter is used to specify the network error code. This can be used to provide additional information about the error. |
FC |
(C)2024 All rights reserved. No part of this document may be reproduced in any form without the written permission of the copyright holder. The contents of this document are subject to revision without notice. Telia Company shall have no liability for any error or damages of any kind resulting from the use of this document.