Before you begin
...
Submits a message object for delivery to a mobile phone. Set Content-Type: application/json in your request header and POST a JSON object with the following properties:
Parameter | Data type | Description |
source | String | Required. This is the source number from where the message should be sent. The format is depending on the specified sourceTON. |
sourceTON | TON | This is the source type of number. See allowed TON values below. |
destination | String | Required. This is the destination number. The format is depending on the specified destinationTON. Remember that MSISDNS include the country code and a leading plus sign. (+) |
destinationTON | TON | This is the destination type of number. See allowed TON values below. |
dcs | DCS | Advanced. This is the Data Coding Scheme that should be used when sending the SMS. See allowed DCS values in a separate table. |
userDataHeader | String | Advanced. This value may be specified when sending concatenated SMS, WAP-push, etc. The format is hex encoded 8-bit bytes. More information about valid UDH for long SMS may be given by Support upon request. Common will handle the splitting and concatenation of messages if you do not have a specific reason to do it yourself. |
userData | String | This is the message content itself. The DCS specifies the format (encoding) on this value. Note that messages that messages of more than 140 bytes must be split into multiple messages. Common will do that automatically by default. |
useDeliveryReport | Boolean | True indicates that a delivery report should be sent back when the message has come to a final state. (Delivered or failed) TRUE is mandatory for premium messages. Defaults to TRUE, and it is recommended to use delivery reports. |
deliveryReportGates | List | One or more gates that should be used for sending delivery reports. If you do not specify any Gates to deliver Delivery Reports to, make sure to set useDeliveryReport to FALSE. See the chapter on delivery reports for more information. Required for premium messages. |
relativeValidityTime | Long | This specifies how long the message is supposed to live. If the message takes longer to deliver to the handset than the validityTime, the message will be discarded. The value is specified in milliseconds. Default is 48 hours (172800000). |
absoluteValidityTime | Date | The absolute time when a message should expire. Minimum 15 minutes and maximum 48h in the future. Formatted according to RFC3339, e.g. 2010-03-30T12:59:40+02:00. Overrides relativeValidityTime if both are set. |
tariff | Integer | Price, in local currency, in 1/100 of currency. For example, to send a message costing 5 NOK, this should be set to 500. If you are splitting a long message into multiple segments yourself, set price only on the first segment. Default 0. |
currency | Currency | The currency should be set if the default country currency not to be used. Supported currencies are NOK, SEK, DKK, EUR, LTL. |
vat | Integer | Deprecated - implementations should not use this field any more. The VAT that used for the premium transaction, default differ per market. 2500 equals 25%. Absence or value = -1 means not set. |
age | Integer | Allowed age for (adult) content. |
priority | Priority | See the Priority value table, Optional. |
platformId | String | Your platformId. Provided to you by Support. |
platformPartnerId | String | Your platformPartnerId. Provided to you by Support. |
refId | String | Your own internal transaction ID. Not used for anything except as a reference. |
productDescription | String | When sending premium messages, a description of the service. This will be printed on the end-user’s phone bill. |
productCategory | Integer | When sending premium messages, specify which category the service is. This lets the operator know which rates to apply to the message. Support or your sales contact will help you determine the correct productCategory to set. |
moReferenceId | String | A reference to the ID of the MO message which triggered the MT message. Required for some operators. |
customParameters | KeyValue | Advanced. Additional parameters may be specified if needed. Support will advise you if you need to use custom parameters. |
ignoreResponse | Boolean | Indicates whether you want a response in the body when you submit the message. This is not a delivery report, only a confirmation of message submission. Default is false. |
DCS
Data Coding Scheme sets the encoding used for the message. Default and recommended is TEXT.
...
https://[your assigned URL]/sms/sendbatch
batchSendRequest
Parameter | Data type | Description |
useDeliveryReport | Boolean | True indicates that a delivery report should be sent back when the message has come to a final state. (Delivered or failed) TRUE is mandatory for premium messages. Defaults to TRUE, and it is recommended to use delivery reports. |
deliveryReportGates | List | One or more gates that should be used for sending delivery reports. If you do not specify any Gates to deliver Delivery Reports to, make sure to set useDeliveryReport to FALSE. See the chapter on delivery reports for more information. Required for premium messages. |
relativeValidityTime | Long | This specifies how long the message is supposed to live. If the message takes longer to deliver to the handset than the validityTime, the message will be discarded. The value is specified in milliseconds. Default is 48 hours (172800000). |
absoluteValidityTime | Date | The absolute time when a message should expire. Minimum 15 minutes and maximum 48h in the future. Formatted according to RFC3339, e.g. 2010-03-30T12:59:40+02:00. Overrides relativeValidityTime if both are set. |
priority | Priority | See the Priority value table, optional. |
platformId | String | Your platformId. Provided to you by Support. |
platformPartnerId | String | Your platformPartnerId. Provided to you by Support. |
customParameters | KeyValue | Advanced. Additional parameters may be specified if needed. Support will advise you if you need to use custom parameters. |
ignoreResponse | Boolean | Indicates whether you want a response in the body when you submit the message. This is not a delivery report, only a confirmation of message submission. Default is true. |
sendRequestMessages | List | An array of messages. The maximum number of messages allowed within the array is 1000. See the following table for its content. |
sendRequestMessage
Parameter | Data type | Description |
source | String | Required. This is the source number from where the message should be sent. The format is depending on the specified sourceTON. |
sourceTON | TON | This is the source type of number. See allowed TON values below. |
destination | String | Required. This is the destination number. The format is depending on the specified destinationTON. Remember that MSISDNS include the country code and a leading plus sign. (+) |
destinationTON | TON | This is the destination type of number. See allowed TON values below. |
dcs | DCS | Advanced. This is the Data Coding Scheme that should be used when sending the SMS. See allowed DCS values in a separate table. |
userDataHeader | String | Advanced. This value may be specified when sending concatenated SMS, WAP-push, etc. The format is hex encoded 8-bit bytes. More information about valid UDH for long SMS may be given by Support upon request. Common will handle the splitting and concatenation of messages if you do not have a specific reason to do it yourself. |
userData | String | This is the message content itself. The DCS specifies the format (encoding) on this value. Note that messages that messages of more than 140 bytes must be split into multiple messages. Common will do that automatically by default. |
tariff | Integer | Price, in local currency, in 1/100 of currency. For example, to send a message costing 5 NOK, this should be set to 500. If you are splitting a long message into multiple segments yourself, set price only on the first segment. Default 0. |
currency | Currency | The currency should be set if the default country currency not to be used. Supported currencies are NOK, SEK, DKK, EUR. |
vat | Integer | Deprecated - implementations should not use this field anymore. The VAT that used for the premium transaction, default differ per market. 2500 equals 25%. Absence or value = -1 means not set. |
age | Integer | Allowed age for (adult) content. |
refId | String | Your own internal transaction ID. Not used for anything except as a reference. |
productDescription | String | When sending premium messages, a description of the service. This will be printed on the end-user’s phone bill. |
productCategory | Integer | When sending premium messages, specify which category the service is. This lets the operator know which rates to apply to the message. Support or your sales contact will help you determine the correct productCategory to set. The acceptable productCategory values are specified under productCategory values. |
moReferenceId | String | A reference to the ID of the MO message which triggered the MT message. Required for some operators. |
customParameters | KeyValue | Advanced. Additional parameters may be specified if needed. Support will advise you if you need to use custom parameters. These additional parameters are overridden by those that are in the batchSendRequest. |
productCategory values
Product categories defined by SERGEL:
Value | Description |
1 | CPA_REGULAR_RINGTONES |
2 | CPA_REGULAR_RINGBACK_TONES |
3 | CPA_REGULAR_MUSIC_FULL_TRACK |
4 | CPA_REGULAR_WALLP_ANIM |
5 | CPA_REGULAR_VIDEOS |
6 | CPA_REGULAR_NEWS |
7 | Not in use |
8 | CPA_REGULAR_LOTTERY |
9 | Not in use |
10 | CPA_REGULAR_VOTING |
11 | CPA_REGULAR_MOBILE_MARKETING |
12 | Not in use |
13 | Not in use |
14 | CPA_REGULAR_COMMUNITY |
15 | CPA_REGULAR_INFO_SERVICE |
16 | CPA_REGULAR_MIXED_CONTENT |
17 | GAS_CHARITY |
18 | GAS_CONCERT_TICKETS |
19 | GAS_MEMBERSHIP_FEE |
20 | GAS_PHYSICAL_GOODS_NON_FOOD |
21 | MEDIA_CPA_INTERNET_TV |
22 | MEDIA_CPA_INTERNET_FILM |
23 | MEDIA_CPA_E_BOOK |
24 | MEDIA_CPA_E_MAGAZINE |
25 | MEDIA_CPA_E_NEWSPAPER |
26 | Not in use |
27 | CPA_REGULAR_OTHER |
28 | GAS_CINEMA_TICKETS |
29 | GAS_BOOK |
30 | GAS_MUSIC_CD |
31 | GAS_MAGAZINE |
32 | GAS_ACCESS_FEE_SPORTS |
33 | GAS_ZERORATED_SMS |
34 | GAS_CLASSIFIED_ADS |
35 | GAS_CLASSIFIED_ADS_ABOVE_PRICE_200 |
36 | Note: --- NOT TO BE USED ---- |
37 | MANUAL_SERVICES |
38 | PHYSICAL_GOODS_FOOD_DRINK |
39 | TRANSPORT_BUS |
40 | TRANSPORT_TRAIN |
41 | HEALTH_SERVICES |
42 | PARKING |
43 | AUTOMATIC NUMBER DIRECTORY SERVICES |
44 | ALERT SERVICES |
45 | INFORMATION SERVICES |
46 | MEDIA |
47 | MEMBERSHIP_COMMERCIAL |
48 | FISHING_LICENSE |
49 | GIFT_CERTIFICATE |
50 | MANUAL_SERVICE_REGISTERED |
51 | CINEMA_TICKET |
52 | ROADTAX |
53 | NON_HUMANITARIAN_DONATIONS |
...
Strex productCategory values
The list of valid Strex business models: Strex Payment, Transport, Donation, Media, Information Services, Automatic Number Directory Service, Mobile Content Services, Mobile Content Services 18+, Alert Services, Voting.
Note: SERGEL CommonLayer product categories do not use these Strex business models: Media, Information Services, Automatic Number Directory Service, Alert Services.
Value | Description | Strex service code | Strex business model |
1 | CPA_REGULAR_RINGTONES | 03001 | MOBILECONTENTSERVICES |
2 | CPA_REGULAR_RINGBACK_TONES | 03002 | MOBILECONTENTSERVICES |
3 | CPA_REGULAR_MUSIC_FULL_TRACK | 03002 | MOBILECONTENTSERVICES |
4 | CPA_REGULAR_WALLP_ANIM | 03004 | MOBILECONTENTSERVICES |
5 | CPA_REGULAR_VIDEOS | 03007 | MOBILECONTENTSERVICES |
6 | CPA_REGULAR_NEWS | 02001 | MOBILECONTENTSERVICES |
7 | Not in use | N/A | N/A |
8 | CPA_REGULAR_LOTTERY | 03012 | MOBILECONTENTSERVICES |
9 | Not in use | N/A | N/A |
10 | CPA_REGULAR_VOTING | 04002 | VOTING |
11 | CPA_REGULAR_MOBILE_MARKETING | 02001 | MOBILECONTENTSERVICES |
12 | Not in use | N/A | N/A |
13 | Not in use | N/A | N/A |
14 | CPA_REGULAR_COMMUNITY | 03011 | MOBILECONTENTSERVICES |
15 | CPA_REGULAR_INFO_SERVICE | 04001 | MOBILECONTENTSERVICES |
16 | CPA_REGULAR_MIXED_CONTENT | 03011 | MOBILECONTENTSERVICES |
17 | GAS_CHARITY | 14002 | DONATION |
18 | GAS_CONCERT_TICKETS | 05010 | STREX-PAYMENT |
19 | GAS_MEMBERSHIP_FEE | 14001 | STREX-PAYMENT |
20 | GAS_PHYSICAL_GOODS_NON_FOOD | 15001 | STREX-PAYMENT |
21 | MEDIA_CPA_INTERNET_TV | 16001 | STREX-PAYMENT |
22 | MEDIA_CPA_INTERNET_FILM | 16002 | STREX-PAYMENT |
23 | MEDIA_CPA_E_BOOK | 16003 | STREX-PAYMENT |
24 | MEDIA_CPA_E_MAGAZINE | 16004 | STREX-PAYMENT |
25 | MEDIA_CPA_E_NEWSPAPER | 16005 | STREX-PAYMENT |
26 | Not in use | N/A | N/A |
27 | CPA_REGULAR_OTHER | 02001 | INFORMATIONSERVICES |
28 | GAS_CINEMA_TICKETS | 05010 | STREX-PAYMENT |
29 | GAS_BOOK | 15001 | STREX-PAYMENT |
30 | GAS_MUSIC_CD | 15001 | STREX-PAYMENT |
31 | GAS_MAGAZINE | 15001 | STREX-PAYMENT |
32 | GAS_ACCESS_FEE_SPORTS | 13003 | STREX-PAYMENT |
33 | GAS_ZERORATED_SMS | 89001 | STREX-PAYMENT |
34 | GAS_CLASSIFIED_ADS | 08001 | STREX-PAYMENT |
35 | GAS_CLASSIFIED_ADS_ABOVE_PRICE_200 | 08001 | STREX-PAYMENT |
36 | Note: --- NOT TO BE USED ---- | NA | STREX-PAYMENT |
37 | MANUAL_SERVICES | 02001 | STREX-PAYMENT |
38 | PHYSICAL_GOODS_FOOD_DRINK | 10001 | STREX-PAYMENT |
39 | TRANSPORT_BUS | 06002 | TRANSPORT |
40 | TRANSPORT_TRAIN | 06001 | TRANSPORT |
41 | HEALTH_SERVICES | 07001 | STREX-PAYMENT |
42 | PARKING | 06005 | TRANSPORT |
43 | AUTOMATIC NUMBER DIRECTORY SERVICES | 16008 | AUTOMATICNUMBERDIRECTORYSERVICE |
44 | ALERT SERVICES | 02001 | ALERTSERVICES |
45 | INFORMATION SERVICES | 02001 | INFORMATIONSERVICES |
46 | MEDIA | 16005 | MEDIA |
47 | MEMBERSHIP_COMMERCIAL | 14004 | STREX-PAYMENT |
48 | FISHING_LICENSE | 13001 | STREX-PAYMENT |
49 | GIFT_CERTIFICATE | 09001 | STREX-PAYMENT |
50 | MANUAL_SERVICE_REGISTERD | 13006 | STREX-PAYMENT |
52 | ROADTAX | 06007 | TRANSPORT |
...
In the case of batch sendings, this value can be added within the batchSendRequest or within the SendRequestMessage. But if this customParameter is added within the batchSendRequest, then it will override its value for all the messages within this single batchSendRequest.
Example 1
Here, all the messages will be sent as flash sms, even if the flash.sms customParameter is found with the value “false”within a sendRequestMessage:
...
"userData": "Hello world, second message",
"refId": "qts883r"
}
]
}
Example 2
Here, the first message will be sent as a flash SMS, meanwhile the second one and the third one will be sent as normal SMS. This will work if the customParameter “flash.sms” is absent in the batchSendRequest.
...
Please be aware that when you use the obfuscate function, you are not able to search in message logs for destination number or message content.
Obfuscation Example
Example for “obfuscate.userData” 
"customParameters" : { "obfuscate.userData" : "true" }
Example for “obfuscate”
"customParameters" : { "obfuscate" : "true" }
Delivery Reports
When an MT message is delivered to a handset, or fails for any reason, you will receive a callback with a delivery report. This is required for charged messages, optional (but recommended) for free messages. If the message is multi-part message, then it will get a delivery report for each part. It can be sent in JSON, XML, or HTTP GET/POST key/value pairs. If you want to change your format or your URL, please contact Support.
...
The most common result code is 1001 Delivered. This code indicates a successful delivery (and payment, if charged) of the message. Most statuses are final, indicating that the message either has been successfully delivered, or failed in a non-recoverable way.
resultCode | Description | Transaction State |
0 | Unknown error | FINAL: NOT DELIVERED, NOT BILLED* |
1 | Temporary routing error | FINAL: NOT DELIVERED, NOT BILLED* |
2 | Permanent routing error | FINAL: NOT DELIVERED, NOT BILLED* |
3 | Maximum throttling exceeded | FINAL: NOT DELIVERED, NOT BILLED* |
4 | Timeout | FINAL: UNKNOWN DELIVERY, UNKNOWN BILLING* |
5 | Operator unknown error | FINAL: UNKNOWN DELIVERY, UNKNOWN BILLING* |
6 | Operator error | FINAL: NOT DELIVERED, NOT BILLED* |
104 | Configuration error | FINAL: NOT DELIVERED, NOT BILLED* |
105 | Internal error (internal SERGEL error) | FINAL: NOT DELIVERED, NOT BILLED* |
1000 | Sent (to operator) | TEMP: NOT DELIVERED, NOT BILLED* |
1001 | Billed and delivered | FINAL: DELIVERED, BILLED* (if applicable) |
1002 | Expired | FINAL: NOT DELIVERED, NOT BILLED* |
1003 | Deleted | FINAL: NOT DELIVERED, NOT BILLED* |
1004 | Mobile full | FINAL: NOT DELIVERED, NOT BILLED* |
1005 | Queued | TEMP: NOT DELIVERED, NOT BILLED* |
1006 | Not delivered | FINAL: NOT DELIVERED, NOT BILLED* |
1007 | Delivered, Billed delayed | TEMP: DELIVERED, NOT BILLED* |
1008 | Billed OK (charged OK before sending message) | TEMP: NOT DELIVERED, BILLED* |
1009 | Billed OK and NOT Delivered | FINAL: NOT DELIVERED, BILLED* |
1010 | Expired, generated by SERGEL | FINAL: UNKOWN DELIVERY, UNKNOWN BILLING* |
1011 | Billed OK and sent (to operator) | TEMP: NOT DELIVERED, BILLED* |
1012 | Delayed (temporary billing error, system will try to resend) | TEMP: NOT DELIVERED, NOT BILLED* (resending) |
1013 | Message sent to operator, Bill delayed | TEMP: NOT DELIVERED, NOT BILLED* |
2000 | Invalid source, the specified source number or Alpha is invalid | FINAL: NOT DELIVERED, NOT BILLED* |
2001 | Source shortnumber not supported, the source TON may not be set to shortnumber | FINAL: NOT DELIVERED, NOT BILLED* |
2002 | Source alpha not supported, the source TON may not be set to alpha | FINAL: NOT DELIVERED, NOT BILLED* |
2003 | Source MSISDN not supported, the source TON may not be set to MSISD | FINAL: NOT DELIVERED, NOT BILLED* |
2100 | Destination shortnumber not supported, the destination TON may not be set to shortnumber | FINAL: NOT DELIVERED, NOT BILLED* |
2101 | Destination alpha not supported, the destination TON may not be set to alpha | FINAL: NOT DELIVERED, NOT BILLED* |
2102 | Destination MSIDN not supported, the destination TON may not be set to MSISDN | FINAL: NOT DELIVERED, NOT BILLED* |
2103 | Operation blocked, requested operation is not supported for the specified destination | NOT DELIVERED, NOT BILLED* |
2104 | Unknown subscriber | FINAL: NOT DELIVERED, NOT BILLED* |
2105 | Destination blocked (subscriber permanently barred) | FINAL: NOT DELIVERED, NOT BILLED* |
2106 | Number error | FINAL: NOT DELIVERED, NOT BILLED* |
2107 | Destination temporarily blocked (subscriber temporarily barred) | FINAL: NOT DELIVERED, NOT BILLED* |
2200 | Charging error | FINAL: NOT DELIVERED, NOT BILLED* |
2201 | Subscriber has low balance | FINAL: NOT DELIVERED, NOT BILLED* |
2202 | Subscriber barred for overcharged (premium) messages | FINAL: NOT DELIVERED, NOT BILLED* |
2203 | Subscriber too young (for this particular content) | FINAL: NOT DELIVERED, NOT BILLED* |
2204 | Prepaid subscriber not allowed | FINAL: NOT DELIVERED, NOT BILLED* |
2205 | Service rejected by subscriber | FINAL: NOT DELIVERED, NOT BILLED* |
2206 | Subscriber not registered in payment system | FINAL: NOT DELIVERED, NOT BILLED* |
2207 | Subscriber has reached max balance | FINAL: NOT DELIVERED, NOT BILLED* |
3000 | GSM encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
3001 | UCS2 encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
3002 | Binary encoding is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
4000 | Delivery report is not supported | FINAL: NOT DELIVERED, NOT BILLED* |
4001 | Invalid message content | FINAL: NOT DELIVERED, NOT BILLED* |
4002 | Invalid tariff | FINAL: NOT DELIVERED, NOT BILLED* |
4003 | Invalid user data | FINAL: NOT DELIVERED, NOT BILLED* |
4004 | Invalid user data header | FINAL: NOT DELIVERED, NOT BILLED* |
4005 | Invalid data coding | FINAL: NOT DELIVERED, NOT BILLED* |
4006 | Invalid VAT | FINAL: NOT DELIVERED, NOT BILLED* |
4007 | Unsupported content for destination | FINAL: NOT DELIVERED, NOT BILLED* |
*BILLED, NOT BILLED & UNKNOWN BILLING Transaction state indicates the state when sending premium SMS.
...