common.md

Common SMS Gateway documentation

Back to main page - Table of contents - Previous section - Next section

This section describes all relevant parameters used in the Puzzel SMS Gateway which is common for all interfaces.

Parameters for outgoing messages (MT)

The following lists of parameters are used when sending messages in either of our available protocols. In its simplest form, an outgoing message can consist of the common parameters, and at least one message object (basic message parameters) without any settings.

Common parameters

Parameter Name	Data Type	Description	Mandatory
serviceid	Integer	Identifies the service. Provided by Puzzel.	Yes
username	String	For authentication. Provided by Puzzel.	Yes
password	String	For authentication. Provided by Puzzel.	Yes
batchReference	String	Reference ID that will be returned in the response.	No
message	List of composite objects	At least one message.	Yes

Basic message parameters

Parameter Name	Data Type	Description	Mandatory
recipient	String	The MSISDN of the recipient. The format should follow the ITU-T E.164 standard with a + prefix. Example: +4792000001. Note: This must be a valid MSISDN, meaning mobile phone number. E.g. for Norway these numbers start with 4, 9, 58 or 59.	Yes
content	String	The message payload to send, typically the message text. Read here for more details.	Yes
price	Integer	The cost for the recipient to receive the message. In lowest monetary unit. See here for more details. For example a value of 200 means 2 NOK in Norway.	No
clientReference	String	Arbitrary client reference ID that will be returned in the message response.	No
settings	Composite object	For message settings, see below	No

Message settings parameters

Parameter Name	Data Type	Description	Mandatory
priority	Integer	Used to prioritize between messages sent from the same service. low (slower) medium high (faster) Example: 2 Uses value from service configuration unless specified.	No
validity	Integer	Specifies the TTL (time to live) for the message, i.e. how long before the message times out in cases where it cannot be delivered to a handset. See table here for valid values. Example: 173	No
differentiator	String	Arbitrary string defined by the client to enable grouping messages in certain statistic reports. Example: OTP message	No
invoiceNode	String	Arbitrary string defined by the client to enable grouping messages on the service invoice from Puzzel to the client. Example: marketing_dept	No
age	Integer	Only relevant for premium rate messages. Defines an age limit for message content. The mobile network operators enforces this. IMPORTANT: If the service is a subscription service, all premium rate messages must have age set to 18. Valid values are: 0 16 18 Example: 18	No
newSession	Boolean	Used to start a new session. Read here for more information. Example: true	No
sessionId	String	Used to continue an existing session. Read here for more information. Example: 01bxmt7f8b8h3zkwe2vg	No
autoDetectEncoding	Boolean	Default value is false and means that the message content must consist of characters in the GSM 7-bit alphabet and messages containing any other characters will get an error message. However if you set this field to true, you are able to use all characters defined in the UCS-2 character set. (Please note that if you use any non GSM-7 characters in your message, the message will be UCS-2 encoded and you might end up sending more messages than intended - so use with care.) Example: true	No
safeRemoveNonGsmCharacters	Deprecated	Check the documentation on message content for more information.	No
originatorSettings	Composite object	Used to specify the originator. See description below. Uses values from service configuration unless specified.	No
gasSettings	Composite object	Used if the message is a premium SMS transaction. See description below Uses values from service configuration unless specified.	No
sendWindow	Composite object	Used if the message should be queued and sent in the future instead of immediately. See description below Sends immediately unless specified.	No
parameter	Composite object	Used to specify special settings including settings for binary message.	No

Originator settings

Parameter Name	Data Type	Description	Mandatory
originatorType	String	Specifies the type of originator. See this section for more information. Valid values are: INTERNATIONAL ALPHANUMERIC NETWORK	Yes
originator	String	Value depends on the originatorType. Example: +4799999999, Puzzel, 1960	Yes

GAS settings

Parameter Name	Data Type	Description	Mandatory
serviceCode	String	Identifier for the category of Goods and services. See this section for more information. See list of valid servicecodes for valid parameter values for service codes here. Example: 05008	Yes
description	String	Further details of the Goods and services. The description may occur on the end-user invoice (together with category) for certain Mobile Network Operators. Example: Aftenposten	No

Send Window

See this section for more information about send window.

Parameter Name	Data Type	Description	Mandatory
startDate	Date, CCYY-MM-DD[Z|(+|-)hh:mm]	The date to send the message. Example: 2013-12-24	Yes
stopDate	Date, CCYY-MM-DD[Z|(+|-)hh:mm]	The date to stop sending messages, if messages still are enqueued. Example: 2013-12-25	No
startTime	Time, hh:mm:ss[Z|(+|-)hh:mm]	The time of day to start sending the messages. Example: 12:00:00, 12:00:00Z, 12:00:00+02:00	Yes
stopTime	Time, hh:mm:ss[Z|(+|-)hh:mm]	The time to stop sending messages, if messages still are enqueued. Example: 12:00:00, 12:00:00Z, 12:00:00+02:00	No

Parameters

Parameter Name	Data Type	Description	Mandatory
key	String	Parameter key, see valid values below. Example: dcs	Yes
value	String	The actual value to use with the chosen key. See description for each key below. Example: F5	Yes

List of valid parameters (key / value)

Key	Data Type	Description
businessModel	String	May be used to specify operator specific business models.. Example: productA
dcs	One octet (2 hex digits)	Data Coding Scheme for message Specifies what data coding scheme to be used for this message. This feature is defined in 3GPP TS 23.038 ch. 4. Should be one octet (2 hex digits). For example '15' or 'F5'. Example: F5
udh	String (hex octets)	User Data Header If non-empty will set the TP-User Data Header Indicator (UDHI) for the message. Defined in 3GPP TS 23.040 ch. 9.2.3.24 TP-User Data (TP-UD). Example: 0B0504158200000023AB0201
pid	Integer	Protocol Identifier – replace short message feature A message containing a PID will replace an existing message having the same PID. Valid values are 65 – 71. Note: It will only be replaced if the service center address and originating address match the previous message. Also note that this functionality is only guaranteed to work for messages that are free of charge to receive for the end user. Many MNOs does not allow this setting for premium SMS.
flash	Integer	Valid values: True (case-insensitive) - All other values, or if omitted means false. A flash SMS is a type of text message that - without user action - appears directly and fullscreen on the the mobile phone. Some terminals will allow you to store this message, other will not. This functionality may be useful in case of emergencies or if you want to send confidential information, such as a One Time Password. Note that these messages often are not displayed on lock screens if the phone OS do not already display messages on lockscreen as default (such as iOS). Also note that this functionality is only guaranteed to work for messages that are free of charge to receive for the end user. Many MNOs does not allow this setting for premium SMS.
parsing-type	String	Valid values: NONE SAFE_REMOVE_NON_GSM SAFE_REMOVE_NON_GSM_WITH_REPLACE AUTO_DETECT The parsing type can be set on the service level and it is recommended to only specify this parameter if you need to override it. See the chapter on message content for further details about the different parsing types.
skip_customer_report_delivery	Boolean	Do not request delivery report (overrides service configuration).
strex_verification_timeout	String	Used for Strex verification process. Specified time in minutes to wait for an end user to complete verification before timing out. Valid Values: 0-30
strex_merchant_sell_option	String	Used for Strex verification process. Specifies the type of verification process to be used. Use "confirmation" if nothing else is agreed with Strex. Valid Values: none confirmation pin
strex_confirm_channel	String	Used for Strex verification process. Specifies the type of channel to to be used for the verification process. Use "sms" if nothing else is agreed with Strex. Valid Values: sms ussd (deprecated) otp (not in use)
strex_authorization_token	String	Used for Strex pre-authentication / authentication process. Only applies to premium messages sent to Strex customers. Specifies a Strex authentication token to be used for recurring premium messages that verifies that users has accepted the payment agreement. See this section for more information on how to create Strex authentication tokens.

Response parameters

All interfaces except SMTP will return a synchronous response with at least the fields for status code, status message and message identifier populated per message. All available fields in the response are described in the tables below.

Message Response

Parameter Name	Data Type	Description
batchReference	String	Reference ID for the request. Either the value provided by the client in the request or an automatically generated ID if no such value is set.
messageStatus	List of composite objects	At least one element of messageStatus objects. See below.

Message Status

Parameter Name	Data Type	Description
statuscode	Integer	Statuscode Value Description MESSAGE_DELIVERED_OK 1 OK ACCESS_ERROR 2 No access. Authentication failed. ILLEGAL_ACTION 3 An illegal operation was tried. ILLEGAL_SERVICE 4 An illegal service was tried. SYNTAX_ERROR 5 The request contained syntax errors. INTERNAL_ERROR 6 An internal error occured in the gateway. QUOTA_EXCEEDED 24 To many messages sent to the same MSISDN. Message is queued but will not be sent before manually approved. ERROR_NOT_UNIQUE 25 Duplicate message error.
statusmessage	String	Textual information about status, e.g. which parameter failed
clientReference	String	The client reference ID if specified in the request
recipient	String	The recipient of the SMS message (MSISDN). Note: The SMS gateway runs all numbers through a number parser and so the recipient in the response may be in same format than in the request, i.e. “+47 41 00 00 00” will be “+4741000000” in the response. Use the clientReference if you need to match messages in the request and response.
messageId	String	Message identifier (used as reference for delivery reports).
sessionId	String	Session identifier for a session, see here for more information. Only returned if newSession parameter is set to true, or if a sessionid was specified.
sequenceIndex	Integer	The messages in the response will always be in the same order as in the request. The sequence index is a convenience counter starting at 1.

Receiving messages using the SMS Gateway (MO SMS)

If you want to enable end users to send SMS messages to your solution, you will need to set up a service able of receiving HTTP GET requests or HTTP POST requests through a REST API with either JSON or XML formatting. Whilst the HTTP GET API will only send one request for each message, the REST API will accumulate batches of messages and only send 1 request per second.

The SMSGW will invoke your HTTP service when MO- and DR-messages are slated for delivery to your server. The URL of your service must be provided to Puzzel Service Desk on help.puzzel.com for proper configuration of the service. You also need to provide information about which API you prefer for incoming (MO) messages. (HTTP GET, HTTP POST with JSON or HTTP POST with XML).

Parameters for incoming messages (MO)

Parameter Name	Data Type	Description
messageid	String	Unique message identifier generated by the SMS platform for this message.
sno	String	The short number associated with this message (e.g. 1960).
command	String	Also known as keyword. The pattern that caused the routing to the service. Usually a keyword e.g. “TLF”
content	String	The content of the SMS message. For regular text SMS messages this is a plain text, for binary messages this will be hex content.
strippedcontent	String	Same as content, but keyword is stripped from beginning of content.
timestamp	Date - Format: yyyyMMdd HH:mm:ss	The time when the message entered the Puzzel SMS platform.
sctimestamp	Date - Format: yyyyMMdd HH:mm:ss	Service Center time stamp represents the time the operator SMSC received the message.
serviceid	Integer	The id of the Puzzel service that has been identified for this message.
servicename	String	The name of the service as provisioned in Puzzel's systems
originator	String	The originator / sender of the SMS message. MSISDN with country code (international formatting) - e.g. +4799999999
mcc / mnc	Integer	Mobile Country Code / Mobile Network Code for this message. See here for a full list. Here are the common norwegian values: MNO (Operator) MCC MNC Telenor 242 1 Telia (Previous NetCom) 242 2 Telia (Previous Network Norway) 242 5 TDC Norway 242 8 ICE 242 14
sessionid	String	This contains the session identifier that this message is a reply to, this parameter allows you to bind an outgoing and incoming message together. This field will be empty if the message does not belong to a session
type	Integer	Always=1 (parameter used to distinguish between MO and DR). Note that this parameter is only available on the HTTP GET interface.

Response when receiving MO SMS messages from Puzzel

Your server must respond to the HTTP request with a HTTP 200 header response, any other response code will by default cause a retry of delivery.

If the gateway does not receive a HTTP 200 acknowledge, it will try resending the message to the CP. The MessageId will be the same as the previous attempt. Normally the MO-request will wait 60 seconds for the HTTP 200 response. If your server does not respond within the time limit, the message is marked as undelivered and the gateway will try to resend the message later.

IMPORTANT: Respond as fast as possible on the request before you start doing heavy business logic. It is strongly recommended to use an asynchronous model where you acknowledge the message and add it to an internal queue, for example database. Do not use a synchronous model where you do all the business logic and then send a response message. Our experience is that customers that fail to respond within the time limit of the request often experience that their messages are queued. This is because the system will use some of its resources to resubmit messages that your server has received earlier but failed to acknowledge. The higher the traffic peaks, the more significant this problem will be.

Receiving SMS delivery reports (DR)

If you need to know whether a specific message is received by the end users handset or not, you will need to implement a server side service able of receiving HTTP GET requests or HTTP POST requests through a REST API with either JSON or XML formatted content.

This is an asynchronous operation and you will need to implement a mechanism for storing messageid and/ or batchReference and / or clientReference from sent messages (MT) in order to associate an incoming delivery report to the correct MT message.

Parameters for delivery reports (DR)

Parameter Name	Data Type	Description
messageId	String	The messageid of the original message this report is for
customerbatchreference	String	The batchReference of the MT message. A system batch reference is generated if you do not specify one when sending the MT message.
customermessagereference	String	The clientReference you specified in the MT message.
serviceid	Integer	The id of the Puzzel service that has been identified for this message.
servicename	String	The name of the service as provisioned in Puzzel's systems
originator	String	The originator / sender of the SMS message. MSISDN with country code (international formatting) - e.g. +4799999999
mcc / mnc	Integer	Mobile Country Code / Mobile Network Code for this message. See here for a full list. Here are the common norwegian values: MNO (Operator) MCC MNC Telenor 242 1 NetCom 242 2 Network Norway 242 5 Phonero (Previous Ventelo Customers) 242 7 TDC Norway 242 8
statuscode	Integer	Code Description 0 Operation successful. 350 Non-existing or invalid network provider 354 The account cannot send bulk messages 355 Missing or illegal tariff for account 360 Syntax error - as reported by MNO (operator) 361 Validity period expired (without recipient receiving the message) 362 The message timed out in SMSC (before recipient received message) 363 SMSC operation failed - Internal SMSC error or the message contains errors and the SMSC is unable to process the message. 370 Unspecified error 371 Transmit error - The message was cancelled due to transmit errors towards the SMSC. 380 Illegal login towards MNO (operator) 368 Not connected/not logged in to SMSC. 369 SMSC Specific error - An error condition occurred on the SMSC. 351 Unknown recipient number - Recipient unknown (do not belong to current network operator) or illegal recipient. 356 Customer temporary barred - Customer is barred for an unspecified for an unspecified amount of time 357 Customer permanently barred - Remove MSISDN from all subscription services 358 Subscription barred for overcharged messages - The subscriber has explicit chosen to be permanently barred from receiving premium rate messages. The recipient is only allowed to receive messages that are free of charge 359 Age limit exceeded - The subscriber is not old enough to receive a premium rate message. Should only occur when an ageLimit is set for a message 364 Subscription temporary not reachable - For some reason, the subscription number cannot be reached for the moment 390 The message was sent successfully, but not billed (either it was not supposed to, or billing failed) 385 Illegal function - The message is stopped because of trying to use a function that requires a special agreement 386 Message billed but not sent - The recipient did not receive the message, but was billed for the message 650 Database problems, error connecting to Database or other database related problems 652 Missing system data - Crucial system data not found cannot perform task without this data. 651 No route to subscriber found 653 Unknown unexpected data. Please see error message in the message object 654 Invalid MSISDN - MSISDN is not recognized as a valid number 655 Inactive service - Service is no longer active, message discarded
statusdescription	String	Brief description of the internal statuscode (primarily used for logging).
extstatuscode	String	External statuscode (from mobile network operator)
extstatusdescription	String	Brief description of the external statuscode (primarily used for logging).
type	Integer	Always=6 (parameter used to distinguish between MO and DR). Note that this parameter is only available on the HTTP GET interface.

Reponse when receiving delivery reports (DR) from Puzzel

You must respond to the HTTP request with a HTTP 200 header response, otherwise any other header responses will cause a retry of delivery.