Introduction:
The SMSINDIAHUB Messaging Platform uses the SMPP v3.4 Protocol Specification Issue 1.5, However it has been designed to be backward compatible with SMPP v3.3.
This document should be read in conjunction with SMPP v3.4 Specification v1.5 and assumes with SMPP a level of familiarity functionality. All the TSP’s have been mandated to comply to the TCCCPR regulation of 2019 by TRAI. In regards to the same, there are several changes which have been triggered in the way the A2P SMS business is being performed.
Scrubbing Model
For understanding the preference scrubbing model, we would need to establish certain definitions and their inter-relationships.
Note:
The terms ‘Sender’, ‘Entity’ and ‘Principal Entity’ will be used interchangeably in this document depending on the context however they mean the same
| Terms | Definition and Remark |
| Transaction | Check for Sender registration, header registration and template |
| Service Implicit | Check for Sender registration, header registration and template |
| Service Explicit | Check for Sender registration, header registration, check for consent and template If the consent scrub fails then preferences will be checked w.r.t Fully Block. If preference scrub passes (i.e. Customer is not on FULLY BLOCK) then the message will be delivered. If both of these fail (i.e. Customer is on FULLY BLOCK), message will not be delivered. |
| Promotional | Check for Sender registration, header registration, check for consent and template If the consent scrub fails then preferences will be checked. If preference scrub passes then the message will be delivered. If both of these fails, message will not be delivered. |
| Terms | Definition and Remark |
| Sender/Principal Entity | As per the regulation – the definition is: “The person or entity who owns the telephone number or the header(s) that were used. A person or entity that publicly asserts or uses a Calling Line Identity (CLI) or the phone number(s) referred to in the communication, except where such assertion is fraudulent The person who sent the message or made a voice call, caused the message to be sent or the voice call to be made or authorized the sending of the message or making of the voice call The person or legal entity dealing with goods, or services, or land or property, or a business or investment opportunity that is offered or promoted; except where such entity maintains a distinct legal identity for the division or line of business dealing with offered goods, services or opportunity, in which case such division or line of business” Interpretation for implementation: When they will register on DLT – they will be given a unique ID – “Principal Entity ID (PE ID)”Have one category from the categories listed in the preference regulations (e.g. Real Estate, Health, and Education etc.). An Entity can have association with only one type of category of businessEntity will own Headers, Registered Templates |
| Telemarketer | As per regulation – means a person or legal entity engaged in the activity of transmission or delivery of commercial communication or scrubbing or aggregation. Interpretation for implementation: Once they register on DLT – they will be given a unique ID – “Telemarketer ID (TM ID)”They cannot own headers or templatesThey will have a billing relationship with the Operator.They do not have to prove their relationship with an entity to the Operator. They will directly send messages and the Operator will accept them for scrubbing on DLT. Based on scrubbing output the SMS will either be rejected or delivery will be attempted |
| Header/CLI | Header can be associated to Entities only and not to any TMHeader can be of two categories – Promotional or OthersOthers will encompass – government, stocks, transaction, service etc. all types of headers which are not promotional |
| Content Template (Script) | This is the message text that the sender wishes to send to the subscriber. It may contain some fixed part and variable partOnce it is registered on DLT – a unique ID will be associated with this. This ID is called “Content Template ID”Each content template will need to be associated with a header using which it can be sent |
| Terms | Definition and Remark |
| Consent | As per regulation – “Consent” means any voluntary permission given by the customer to sender to receive commercial communication related to specific purpose, product or service. Consent may be explicit or inferred as defined in these regulations Interpretation for implementation: There are total of three separate processes associated with consent: Consent Acquisition: process where the subscriber or the sender will initiate a consent acquisition process. The process will be initiated with bulk consent upload – other channels will be enabled subsequentlyConsent verification: process via which the TAP will verify the consent acquisition request received – Verification will be done by TAPConsent scrubbing: check whether the customer has provided the consent to the entity or notConsent will be stored in hashed format and encrypted format on DLT for added security measure |
| Consent Template | Means a template of content which is presented to the customer while acquiring his consent and clearly mentions purpose of the consent and details of sender When consent template is approved, consent template ID will be generated from DLT. When the subscriber gives the consent using the consent verification process, the consent template ID used to acquire it will be associated with the subscriber. This association of the consent template ID will be checked with the MSISDN for sending the message. |
| Preferences | Definition as per Regulation: “Means preference exercised by the customer to permit only a selected category of commercial communications out of available choices prescribed by relevant regulations” These preferences will map back to the category of business which the entity has selected during registration. |
Figure below provides an understanding of scrubbing framework for preference scrubbing.
What will SIH Need to scrub from Entity?
The list below provides the minimum set needed for scrubbing.
- PE ID (New)
- Content Template ID (New)
- CLI/Header (already part of request)
- SMS Content (already part of request)
Sending a Message
How to send a message?
- To Register on DLT to have – PE ID, Content Template ID and approved Header
- For sending the messages, the entity can either approach SIH directly or come via any of their preferred TM who have connectivity with SIH.
- There are three modes via which the messages can be sent using SIH as an Aggregator.
- Using SIH Web Interface
- Using SMPP interface
- Using SIH API interface
SMPP Interface
The SIH SMPP interface is provide the below facility.
- Connectivity between Telemarketer and Operator
- PDU validation check on Header, MSISDN, PE DLT ID, TM ID, Template ID
- Data Encoding (DCS)
- Scrubbing
For using the SMPP interface of SIH, there will four new mandatory parameters introduced in the SMPP PDU
| Parameter | Reason |
| Principal Entity ID (PE ID) | This will help the system execute overall scrubbing modelIn case of future customer complaints, PE will be held responsible for any message which has goneThis is also going to be used for the identity assertion by the TM for having an authority of sending the message on behalf of the PE. |
| Template ID | To check registration status of the messageTo perform scrubbing |
| Telemarketer ID (TM ID) | This is field will define the billing relation with the Operator. If a PE is having a direct billing relationship with the Operator, then in that case PE ID = TM IDThis will be used for executing billing.This field is also used to check the authenticity of the Telemarketer and its identity assertion. |
SMPP Protocol:
- SMPP will contain optional TLV fields which can be used for the purpose of submission of additional parameters. To integrate fully, PE ID would have to add the same TLVs on their end. This additional TLVs will need to be added within every message in Submit SM.
- Ref to new TLV Parameter, PE need to send the PE ID & TEMPLATE ID under the Two Optional Tag Value HEX 0x1400 & 0x1401.
Sample PDU for reference:
PDU:Submit_SM
BINARY:00000062000000040000000000000007000000424E4B425A5200000039 313931353835353539313500000000000001000000137465737420444C5420706C617
466726F6D20321490000631323334350014920006343536373800147C000400001C31c
ommand_length:98comman_d:0x00000004command_status:0x00000000sequenc e_number:7service_type:src_ton:0x00src_npi:0x00src_address:XXXXXXdest_ton:0x0 0dest_npi:0x00dest_address:919158XXXXXXesm_class:0x00protocol_id:0x00priority_ flag:0x00schedule_delivery_time:validity_period:registered_delivery:0x01replace_if_ present:0x00data_coding:t0x00sm_default_msg_id:0x00sm_length:0x0013 short
_message:7465737420444c5420706c617466726f6d2032 text:test DLTplatfrom 2 ExtraOptional 0x1400:(oct: (tlv: 5120) 313233343500) ExtraOptional0x1401:(oct:
(tlv:5121) 343536373800)
Hereafter, the revised definition of TLV fields are as follows:
Principal Entity ID TLV: 0x1400 (Hex), string, len = 30: this will be a unique client identifier on DLT platform.
Content Template ID TLV: 0x1401 (Hex), string, len = 30: this data corresponds to the content Template ID received when template is registered on DLT platform.
Sample PCAP screenshot is attached below which provides the information for SMPP new parameters:
TAGS
These new tags will be introduced in the optional parameter list; however, they will be checked mandatorily at operator’s end.
| Optional Parameters | Optional Tag value Decimal | Optional Tag value Hex |
| PE_ID | 5120 | 1400 |
| Template_ID | 5121 | 1401 |
| Telemarketer_ID (TM_ID) | 5122 | 1402 |
- Tag- PE_ID TAG_OPTIONAL_PARAM_1= 5120
- Tag- TEMPLATE_ID TAG_OPTIONAL_PARAM_2=5121
- Tag- TELEMARKETER_ID TAG_OPTIONAL_PARAM_3=5122
Connectivity
Clients may connect to the SMSINDIAHUB Messaging Platform Server multiple numbers of times. This may be of importance if the client wishes to deploy multiple applications simultaneously. To connect to the SMSINDIAHUB Messaging Platform one needs to specify the following parameters:
- IP Address and Port: This is the TCP/IP endpoint on which the ESME should connect to the SMSINDIAHUB Messaging Platform.
- system_id: This is the username of your account configured on the SMSINDIAHUB Messaging Platform.
- Password: Password for the above account. Required for security reasons to prevent unauthorized access to your account.
- system_type: This field is not used by us, hence set to null.
- interface_version: The client application should connect with the interface_version field set to 0x34 (52 decimal), if it is using SMPP v3.4, otherwise the SMSINDIAHUB Messaging Platform assumes that the application is using SMPP v3.3.
If the application uses SMPP v3.3 then the optional fields cannot be used. These optional fields may be required to implement extra facilities like long SMS, etc.
- enquire_link: The application should issue an enquire_link every minute. This will ensure the link stays active even when it is not in use. The SMSINDIAHUB Messaging Platform will automatically disconnect any link which is inactive for more than 5 min.
Submitting Messages
Submission Types
Messages may be submitted with either submit_sm or data_sm, using either the short_message or message_payload fields. The message length may not exceed the byte limit for the network that the message is being sent to (for example 140 bytes on GSM networks).
The SMSINDIAHUB Messaging Platform does not support submit_multi. If the same message has to be sent to multiple destinations, each message must be sent separately.
These are optional parameters are also not supported.
Concatenated messages are supported by using the User Data Header (UDH), which is included in the message size byte limit.
Submit Responses
A positive response to a ‘submit’ will contain an error code of zero and a non-null message reference.
A negative response will contain a SMSINDIAHUB vendor specific error code. The complete set of SMPP Error Codes and their associated values are defined in the following table.
Table 1 – SMPP Submission Error Codes
| Error Code | Value | Description |
| ESME_ROK | 0x00000000 | No error. |
| ESME_RINVMSGLEN | 0x00000001 | Message length is invalid. |
| ESME_RINVCMDLEN | 0x00000002 | Command length is invalid. |
| ESME_RINVCMDID | 0x00000003 | Invalid command ID. |
| ESME_RINVBNDSTS | 0x00000004 | Incorrect BIND status for given command. |
| ESME_RALYBND | 0x00000005 | ESME already in bound state. |
| ESME_RINVPRTFLG | 0x00000006 | Invalid priority flag. |
| ESME_RINVREGDLVFLG | 0x00000007 | Invalid registered delivery flag. |
| ESME_RSYSERR | 0x00000008 | System error. |
| ESME_RINVSRCADR | 0x0000000A | Invalid source address. |
| ESME_RINVDSTADR | 0x0000000B | Invalid destination address. |
| ESME_RINVMSGID | 0x0000000C | Message ID is invalid. |
| ESME_RBINDFAIL | 0x0000000D | Bind failed. |
| ESME_RINVPASWD | 0x0000000E | Invalid password. |
| ESME_RINVSYSID | 0x0000000F | Invalid system ID. |
| Error Code | Value | Description |
| ESME_RINVSERTYP | 0x00000015 | Invalid service type. |
| ESME_RINVESMCLASS | 0x00000043 | Invalid esm_class field data. |
| ESME_RSUBMITFAIL | 0x00000045 | submit_sm failed. |
| ESME_RINVSRCTON | 0x00000048 | Invalid source address TON. |
| ESME_RINVSRCNPI | 0x00000049 | Invalid Source address NPI. |
| ESME_RINVDSTTON | 0x00000050 | Invalid destination address TON. |
| ESME_RINVDSTNPI | 0x00000051 | Invalid destination address NPI. |
| ESME_RINVSYSTYP | 0x00000053 | Invalid system_type field. |
| ESME_RTHROTTLED | 0x00000058 | Throttling error (ESME has exceeded allowed message limits) |
| ESME_RINVEXPIRY | 0x00000062 | Invalid message validity period (Expiry time). |
| ESME_RINVOPTPARSTREAM | 0x000000C0 | Error in the optional part of the PDU body. |
| ESME_ROPTPARNOTALLWD | 0x000000C1 | Optional parameter not allowed. |
| ESME_RINVPARLEN | 0x000000C2 | Invalid parameter length. |
| ESME_RMISSINGOPTPARAM | 0x000000C3 | Expected optional parameter missing. |
| ESME_RINVOPTPARAMVAL | 0x000000C4 | Invalid optional parameter value. |
| ESME_RDELIVERYFAILURE | 0x000000FE | Delivery failure (used for data_sm_resp). |
| ESME_CREDIT_ERROR | 0x00000401 | Credits are over. |
| ESME_SPAM_MESSAGE | 0x00000404 | Spam content. |
| ESME_RINVSMLEN | 0x00000405 | Message length is exceeding in short_sm (e.g. for message type text max message length is 160 char). |
| ESME_RINVUDHLEN | 0x00000406 | Invalid UDH length indicator (Currently we allow 05, 06 with all type of data coding and 0b with data coding 245). |
| ESME_RINSMSEMPTY | 0x00000407 | Message body not found in either short_sm or message_payload. |
| ESME_RINDSTDND | 0x00000408 | Destination in DND. |
| ESME_RINSRCMSG | 0x00000409 | Invalid source/template. |
| ESME_RINSRCMSG | 0x00000410 | Source/template long message error code. |
| ESME_RINSRCMSG | 0x00000411 | Duplicate submission. |
| ESME_RINSRCMSG | 0x00000412 | Destination barred/Source barred. |
Character Sets, Class and Data Coding
The SMSINDIAHUB Messaging Platform supports the following two types of data coding schemes:
- GSM 03.38 Encoding (default)
- Latin 1 (ISO-8859-1) encoding
The default character set is GSM 338. Although for data_coding=1 the character set
GSM 03.38 is supported it is NOT RECOMMENDED, as it is known to cause problems with character encoding. Please set data_coding = 3 for ISO-8859-1(if and only if told so explicitly) encoded messages and data_coding=0 for GSM 03.38 encoded messages.
For Unicode messages you have to set data_coding = 8 and the message is expected in UTF-16 Big Endean format.
Originators and Destination
The default originator type is full International MSISDN. Alpha numeric o network short code originators can be sent by using the following ton values in source_addr_ ton field.
| Alpha-numeric | 5 |
| National / Network Short Code | 3 |
| International MSISDN | 1 |
Destination Address types are not supported. They can be set to any value but are always interpreted as 1. This requires all the destination numbers to be sent in an international format without the leading 00.
Long Messages
Long messages as the name suggests are messages whose length exceeds the normal length imposed on short messages (160 for text and 70 for Unicode).
The user can send long messages via the SMSINDIAHUB Messaging Platform using the following two methods:
• Concatenated Messages
In this method the long message is sent in parts as multiple short messages which are then joined together on the mobile (If the mobile supports long messages, else each message part will be displayed as a separate message).
In this method the client sends the UDH (User Data Header) as part of the short_ message field. The UDH contains all the details required for the mobile join the parts and make the complete message at its end. In this method the client has to set the esm_class field in the submit_sm pdu to 0x43 (Store and Forward with UDHI)
• Message Payload
Here the SMSINDIAHUB Messaging Platform can accept a message with length up to 64K octets. In this method the client uses the optional message_payload of the submit_sm pdu. To use this method the client should set the interface_version to 0x34; else this field will not be available for sending messages.
Delivery Reports
The SMSINDIAHUB Messaging Platform will return a delivery report (Intermediate and/or final depending on the route) for a specific message to the client application when the registered_delivery field, while submitting the message, is set to 1. In order to retrieve the delivery report from our server the client will have to connect to the SMSINDIAHUB Messaging Platform in the receiver or transceiver mode.
Table 2 – Delivery Statuses
| Status | Description |
| DELIVRD | Message delivered to device. |
| FAILED | Message could not be delivered. |
| EXPIRED | Message validity period expired, before any successful tries of submission. |
| UNDELIV | Message is undeliverable. |
| REJECTD | Message rejected. |
Adding the error codes and statuses which can be returned by Messaging Platform.
Table 3 – Error Codes and Statuses
| Status Error | Status | Description |
| 000 | DELIVRD | Delivered to SIM. |
| 001 | UNDELIV | Unidentified subscriber. |
| 005 | EXPIRED | Unidentified subscriber. |
| 009 | UNDELIV | Illegal subscriber. |
| 011 | UNDELIV | Tele service not provisioned. |
| 012 | UNDELIV | Illegal equipment. |
| 013 | UNDELIV | Call barred. |
| 021 | UNDELIV | Facility not supported. |
| 027 | EXPIRED | Absent subscriber. |
| 031 | EXPIRED | Subscriber busy for MT_SMS. |
| 032 | EXPIRED | SM-Delivery Failure. |
| 034 | EXPIRED | System failure. |
| 035 | UNDELIV | Data missing. |
| 036 | UNDELIV | Unexpected data value. |
| 144 | UNDELIV | Unrecognized component. |
| 145 | UNDELIV | Mistyped component. |
| 146 | UNDELIV | Body structured component. |
| 160 | EXPIRED | Duplicate invoke ID. |
| 161 | UNDELIV | Unrecognized operation. |
| 162 | UNDELIV | Mistyped parameter. |
| Status Error | Status | Description |
| 163 | EXPIRED | Resource limitation. |
| 164 | EXPIRED | Initiating release. |
| 165 | EXPIRED | Unrecognized linked ID. |
| 166 | EXPIRED | Linked response expected. |
| 167 | EXPIRED | Unexpected linked operation. |
| 176 | UNDELIV | Unrecognised invoke ID. |
| 177 | EXPIRED | Return result expected. |
| 178 | UNDELIV | Mistyped parameter. |
| 192 | EXPIRED | Unrecognised invoke ID. |
| 193 | EXPIRED | Return error unexpected. |
| 194 | UNDELIV | Unrecognised error. |
| 195 | UNDELIV | Unexpected error. |
| 196 | UNDELIV | Mistyped parameter. |
| 200 | UNDELIV | Unable to decode response. |
| 201 | EXPIRED | Provider abort. |
| 202 | UNDELIV | User abort. |
| 203 | EXPIRED | Timeout. |
| 204 | UNDELIV | API error. |
| 205 | UNDELIV | Unknown error. |
| 404 | REJECTD | Invalid message content. |
| 408 | REJECTD | DND error code. |
| 409 | REJECTD | Source/template error code. |
| 410 | REJECTD | Source/template long message error code. |
| 411 | REJECTD | Duplicate submission. |
| 412 | REJECTD | Destination barred/Source barred. |
| 600 | REJECTD | Entity not found. |
| 601 | REJECTD | Entity not registered. |
| 602 | REJECTD | Entity inactive. |
| 603 | REJECTD | Entity blacklisted. |
| 604 | REJECTD | Invalid entity ID. |
| 605 | REJECTD | Invalid optional parameter value. |
| 606 – 609 | REJECTD | Entity reserved. |
| 610 | REJECTD | Telemarketer not registered. |
| 611 | REJECTD | Telemarketer inactive. |
| 612 | REJECTD | Telemarketer blacklisted. |
| 613 | REJECTD | Invalid or missing TLV TM_ID. |
| 614-619 | REJECTD | Telemarketer reserved. |
| 620 | REJECTD | Header not found. |
| 621 | REJECTD | Header inactive. |
| 622 | REJECTD | Header blacklisted. |
| Status Error | Status | Description |
| 623 | REJECTD | EID not matched with header. |
| 624 | REJECTD | SMS type of header is not match template. |
| 625 | REJECTD | SMS type is not match with header/Template SMS type. |
| 626-629 | REJECTD | Header reserved. |
| 630 | REJECTD | Invalid or missing TLV template ID. |
| 631 | REJECTD | Template inactive. |
| 632 | REJECTD | Template blacklisted. |
| 633 | REJECTD | Template not matched. |
| 634 | REJECTD | Header not registered for template. |
| 635 | REJECTD | Template variable exceeded max length. |
| 636 | REJECTD | Error identifying template. |
| 637 | REJECTD | Invalid template ID. |
| 638 | REJECTD | Invalid SMS type. |
| 639-649 | REJECTD | Template reserved. |
| 650 | REJECTD | Preference not matched. |
| 651-659 | REJECTD | Preference reserved. |
| 660 | REJECTD | Consent failed. |
| 661-669 | REJECTD | Consent reserved. |
| 670 | REJECTD | Scrubbing failed. |
| 671 | REJECTD | DLT scrubbing timeout. |
| 672 | REJECTD | Invalid or missing mandatory TLV. |
| 673 | REJECTD | Invalid or missing TLV PE_ID. |
| 674-699 | REJECTD | Scrubbing reserved. |
| 700 | PRSBMIT | Promo submitted to operator. |
