CPA System REST API Specification

cpa-support

Version 3.5.7
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
API changes and restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3. Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1. Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1.1. Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.1.2. Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Indirect interaction with subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Charging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2. Transaction messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.1. Mobile terminated message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Processing flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2.2. Mobile originated message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Processing flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.2.3. Delivery report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Successful DLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Unsuccessful DLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Methods/ways for DLR transmitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Methods usage and restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Processing flow for transmitting DLR on a regular basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Processing flow for transmitting DLR by request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4. Syntax notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.1. Send MT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.2. Receive MO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.3. Receive DLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.4. Get DLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5. Headers definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1. Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1.1. Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Exceptions processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.1.2. Content-Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Exceptions processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.2. Header examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.2.1. MT message headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Acceptance response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.2.2. GET DLR request headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Acceptance response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
 5.2.3. MO/DLR messages headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6. Parameters definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1. Mandatory parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1.1. date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1.2. destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.1.3. content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.1.4. mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.5. source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.1.6. status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.2. Optional parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.2.1. bearerType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.2.2. callbackNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.2.3. contentExtended . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
caption & action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.2.4. contentType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.2.5. errorId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.2.6. errorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.2.7. params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.2.8. rid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.2.9. serviceType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.2.10. ttl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7. Message types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.1. SMS message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.1.1. SMS/plain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.1.2. SMS/silent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.1.3. SMS/binary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.2. USSD message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2.1. USSD/push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.2.2. USSD/menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.3. Viber message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
7.3.1. Viber/text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Promo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.3.2. Viber/media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Text-image-button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
8. General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
 8.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
8.1.1. Encoding for text/plain content type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
DLR, MO messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
MT message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
8.1.2. Encoding for smpp/binary content type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
MO message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
MT message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.1.3. Data encoding scheme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.2. HTTP verbs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8.3. HTTP status codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8.4. Connection properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.5. Integration FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.6. Error information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.6.1. Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.6.2. Degenerate case for transmitting error 196867 via DLR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
8.6.3. Validations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
8.7. Emoji . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
8.7.1. Emoji in sms-traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Emoji length for sms-traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
8.7.2. Emoji & text formatting in viber-traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Emoji . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Text formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Emoji and markdowns length for viber-traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
8.8. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Appendix A: Multi-channeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
A.1. Service overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
A.1.1. Multi-mt message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Processing flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
A.1.2. Multi-dlr message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Quantity of delivery reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Methods/ways for multi-dlr transmitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Methods usage and restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Transmitting multi-dlr on a regular basis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Transmitting multi-dlr by request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
A.2. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
A.2.1. Send multi-mt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
A.2.2. Receive multi-dlr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
A.2.3. Get multi-dlr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
A.3. Headers definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
A.4. Parameters definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
A.4.1. Common parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
rid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
errorId . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
errorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
A.4.2. Multi-mt parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
bearerType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
contentType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
serviceType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
callbackNum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
img . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
caption & action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
ttl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
A.4.3. Multi-dlr parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
mid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
A.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
A.5.1. sms (text/plain) + viber (text/plain) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
A.5.2. sms (text/plain) + viber (text/template) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
A.5.3. sms (text/plain) + viber (image/plain) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
A.5.4. sms (text/plain) + viber (text/img/button) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
A.6. Error dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
A.7. Release notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Revision history

Issue Description Author

V. 3.1.0 1. Specification creation. Tetyana Tiunova /

16.08.2018 The Basic set of chapters and sections: Softengi
1. Introduction
2. Overview
2.1. Header description
3. Transactions
3.1. Interaction general description
3.2. Mobile terminated message
3.3. Delivery report
4. General
4.1. HTTP verbs
4.2. HTTP status codes
4.3. Error information
4.4. Glossary

V. 3.2.0 1. Amended Chapter 'Introduction': Tetyana Tiunova /

13.11.2018 - added paragraph 'Support and development' Softengi
2. Amended Chapter 'Transactions':
added section 'Mobile originated message'
3. Added Chapter 'Parameters definition'
4. Added Chapter 'Message types'
5. Amended Chapter 'General':
- added section 'Data encoding scheme'
6. Amended Chapter 'Overview':
- added POST method example to Mobile originated message
7. Section 'Header parameters' moved to Chapter 'Parameters
definition'
8. Amended section 'Mobile terminated message':
- added new parameters descriptions: rid, eos
- refactored tables structure
9. Amended section 'Delivery report': refactored tables structure
10. Amended section 'JSON error types':
- added new error types: 1007, 1056, 1057, 1058, 1059, 1060, 1901
- removed deprecated error types:
1044, 1046, 1047, 1048, 1049, 1050, 1052, 1055
11. Amended section 'XML error types':
- added new error type: 101
12. Amended section 'Glossary': added new key terms
13. Changed chapters and sections numbering

1
Issue Description Author

V. 3.3.0 1. Amended Chapter 'Transactions': Tetyana Tiunova /

31.12.2018 - added section 'REST API' Softengi
- added section 'Transaction messages'
- section 'Interaction parties' renamed to 'Assumptions'
2. Added Chapter 'Syntax notation'
3. Amended Chapter 'Parameters definition':
- updated the following parameter description: content
- added a new parameter description: callbackNum
4. Amended Chapter 'Introduction':
- updated paragraph 'Purpose and Scope'
5. Amended Chapter 'Overview':
- added note that syntax examples are provided for REST API only
- removed header parameters form Data parameters short
description
6. Changed resources for MO, MT, and DLR via REST API
7. Renamed transaction to receive DLR
8. Amended Chapter 'Message types':
- added note that syntax examples are provided for REST API only
9. Amended section 'JSON error types':
- added new error types: 1014, 1062, 1063, 1064
10. Amended section 'Glossary': added new key terms
11. Changed chapters and sections numbering

V. 3.3.1 1. Amended section 'JSON error types': Tetyana Tiunova /

03.05.2019 - added new error type: 1065 Softengi

V. 3.4.0 Specification reduced to REST API description for JSON format Tetyana Tiunova /
24.05.2019 1. Amended Chapter 'Introduction': Softengi
- extended paragraph 'Support and development'
2. Amended Chapter 'Overview': excluded XML format examples
3. Amended Chapter 'Transactions':
- 'REST API' section reduced to JSON format
- excluded XML-related descriptions
4. Amended Chapter 'Syntax notation': excluded 'XML' section
5. Amended Chapter 'Parameters definition':
- excluded XML-related parameters
6. Amended Chapter 'Message types':
- excluded XML-related descriptions and examples
7. Amended section 'Error information':
- excluded subsection 'XML error types'
- added new error type: 1066
8. Amended section 'Glossary': excluded XML-related descriptions
9. Section 'Message encoding' renamed to 'Encoding'

V. 3.4.1 1. Amended section 'Receive MO': Tetyana Tiunova /

19.07.2019 - extended MO HTTP request body example Softengi
2. Amended section 'Optional parameters':
- added a new parameter description: params
3. Amended section 'Error information':
- added new error types: 1061, 1067, 1068
- removed a deprecated error type: 1062

2
Issue Description Author

V. 3.4.2 1. Amended section 'Send MT': Tetyana Tiunova /

01.10.2019 - extended MT HTTP request body example Softengi
- extended MT HTTP request parameters description
2. Amended Chapter 'Parameters definition':
- added recommended max length for the following parameters:
bearerType, callbackNum, content, contentType,
destination, rid, serviceType, source
3. Amended section 'Optional parameters':
- added a new parameter description: ttl
4. Amended section 'Error information':
- added new error types: 1069, 1070
- removed a deprecated error type: 1041

V. 3.4.3 1. Amended section 'Optional parameters': Tetyana Tiunova /

10.02.2020 - added a new parameter description: contentExtended Softengi
- updated the following parameters descriptions:
bearerType, callbackNum, contentType, ttl
2. Amended Chapter 'Message types':
- added section 'Viber message'

V. 3.4.4 1. Amended Chapter 'Parameters definition': Tetyana Tiunova /

28.02.2020 - updated the following parameters descriptions: Softengi
callbackNum, ttl, source
2. Amended section 'Text-image-button':
- added a Viber media message example on a subscriber’s device

V. 3.4.5 1. Amended Chapter 'Parameters definition': Tetyana Tiunova /

26.03.2020 - updated the following parameters descriptions: Softengi
contentExtended, label, tag, txt,
2. Amended section 'Viber message':
- updated section 'Viber/text'
- updated section 'Viber/media' and related subsections
3. Amended section 'Error information':
- added new error types: 1071, 1073, 1074, 1075, 1600
4. Amended Chapter 'General': added section 'Emoji '

V. 3.4.6 1. Amended Chapter 'Overview': Tetyana Tiunova /

27.08.2020 - updated description of MO message Softengi
2. Amended section 'Transaction messages':
- updated section 'Delivery report'
3. Amended Chapter 'Syntax notation':
- updated sections 'Receive DLR', 'Get DLR'
4. Amended Chapter 'Parameters definition':
- updated the following parameters descriptions:
content, serviceType, status
5. Amended Chapter 'General':
- added section 'Connection properties'
- updated section 'Encoding for text/plain content type'
- updated section 'Error information'
- updated section 'Emoji '

3
Issue Description Author

V. 3.4.7 1. Amended Chapter 'General': added section 'Integration FAQ' Tetyana Tiunova /
25.11.2020 Softengi

V. 3.4.8 1. Amended Chapter 'Parameters definition': Tetyana Tiunova /

05.01.2021 - updated the following parameters descriptions: Softengi
content, contentType, label, status, txt,
2. Amended section 'Viber message':
- updated section 'Viber/text'
- added subsection 'Template'
- added subsection 'Promo'

V. 3.4.9 1. Amended Chapter 'Parameters definition': Tetyana Tiunova /

23.02.2021 - updated the following parameter description: callbackNum Softengi
2. Amended section 'Error information':
- added a new error type: 1000

V. 3.4.10 1. Amended section 'Emoji ': Tetyana Tiunova /

12.05.2021 - subsection 'Emoji in viber-traffic' renamed to Softengi
'Emoji & text formatting in viber-traffic'
- added subsection 'Text formatting'
- added subsection 'Emoji and markdowns length for viber-traffic'
2. Amended Chapter 'Parameters definition':
- updated the following parameter description: ttl

V. 3.4.11 1. Added section 'API changes and restrictions' Tetyana Tiunova /

01.06.2021 2. Amended section 'Transaction messages': Softengi
- refactored subsection 'Mobile terminated message'
- refactored subsection 'Mobile originated message'
- refactored subsection 'Delivery report'
3. Amended Chapter 'Syntax notation':
- added restriction to the section 'Get DLR'
4. Amended Chapter 'Parameters definition':
- updated the following parameters descriptions: ttl, status
5. Amended section 'Error information':
- added a new error type: 196867
- added subsection 'Degenerate case for transmitting error 196867
via DLR'

V. 3.5.0 1. Added Appendix A: Multi-channeling Tetyana Tiunova /

15.07.2021 Set of Appendix subsections: Softengi
A.1. Service overview
A.2. Syntax
A.3. Parameters definition
A.4. Examples
A.5. Error dictionary
A.6. Release notes

V. 3.5.1 1. Amended Chapter 'Parameters definition': Tetyana Tiunova /

29.07.2021 - updated the following parameter description: status Softengi
2. Amended section 'API changes and restrictions':
- postponed replacing error 196867 with a new delivery status

4
Issue Description Author

V. 3.5.2 1. Amended section 'API changes and restrictions': Tetyana Tiunova /

02.08.2021 - added info that access restriction toward Get DLR method Softengi
was applied on production
2. Amended subsection 'Methods usage and restrictions'
(in the section 'Delivery report'):
- added example for a new error type 1041
3. Amended subsection 'Processing flow for transmitting DLR by
request' (in the section 'Delivery report'):
- added info on access restriction toward Get DLR method
4. Amended section 'Get DLR':
- added example for a new error type 1041
5. Amended section 'Error information':
- added a new error type: 1041

V. 3.5.3 1. Amended section 'Multi-channeling: Service overview': Tetyana Tiunova /

20.09.2021 - updated sequence diagram and processing flow description Softengi
in the subsection 'Multi-mt message'
- added subsection 'Multi-dlr message'
2. Amended section 'Multi-channeling: Syntax':
- added subsection 'Receive multi-dlr'
- added subsection 'Get multi-dlr'
3. Refactored section 'Multi-channeling: Parameters definition':
- added subsection 'Common parameters'
- added subsection 'Multi-mt parameters'
- added subsection 'Multi-dlr parameters'
4. Amended section 'Multi-channeling: Error dictionary':
- added all available errors
5. Amended section 'Multi-channeling: Release notes':
- added new available functionality (GET multi-dlr)

V. 3.5.4 1. Added Chapter 'Headers definition' Tetyana Tiunova /

22.10.2021 2. Refactored section 'Header parameters': Softengi
- section 'Header parameters' renamed to 'Headers'
- moved from the Chapter 'Parameters definition'
to the new Chapter 'Headers definition'
3. Added section 'Header examples'
4. Amended section 'API changes and restrictions':
- postponed replacing error 196867 with a new delivery status

5
Issue Description Author

V. 3.5.5 1. Amended section 'Multi-channeling: Service overview': Tetyana Tiunova /

18.11.2021 - subsection 'Processing flow for transmitting multi-dlr on a Softengi
regular basis' renamed to
'Transmitting multi-dlr on a regular basis'
- subsection 'Processing flow for transmitting multi-dlr by request'
renamed to 'Transmitting multi-dlr by request'
2. Amended section 'Multi-channeling: Syntax':
- updated resource in the subsection 'Send multi-mt'
- added a new optional parameter tag to the multi-mt request
example, and to the table Enclosed message parameters
description in the subsection 'Send multi-mt'
3. Added section 'Multi-channeling: Headers definition'
4. Updated section 'Multi-channeling: Parameters definition'
- subsection 'Header parameters' renamed and moved to the
section 'Headers definition'
- added a new optional parameter description: tag
- updated the following parameters descriptions: callbackNum, ttl
5. Updated section 'Error dictionary'
6. Updated section 'Release notes'

V. 3.5.6 1. Amended section 'API changes and restrictions': Tetyana Tiunova /

23.11.2021 - added info that error 196867 was replaced Softengi
with a new delivery status on production
2. Amended Chapter 'Parameters definition':
- updated the following parameter description: status
3. Amended section 'Degenerate case for transmitting
error 196867 via DLR':
- added info that error 196867 was replaced
with a new delivery status on production

V. 3.5.7 1. Amended 'Revision history': Tetyana Tiunova /

20.05.2022 - corrected grammatical errors Softengi
- removed outdated links
2. Amended Chapter 'Introduction':
- removed outdated information

6
API changes and restrictions

Current section briefly describes following:

• functionalities determined as deprecated and planned for change or decommissioning

• functionalities planned to obtain a controlled access

The current section designed for the attention of all Content Providers to consider
 indicated functionalities and plan necessary updates, development for your
systems if required

Table 1. List of functionalities to be changed

Functionality Change brief description Planned change date

Get DLR method Access to GET DLR method restricted since 01.08.2021 01.08.2021 /
for those Content Providers that did not implement implemented
the feature to accept DLRs from CPA System on a
regular basis.
A detailed description of change provided in a section
Methods usage and restrictions

Transmitting error Error 196867 removed from the DLR structure, and 19.11.2021 /
196867 via DLR replaced with a new delivery status to indicate implemented
subscriber’s low balance since 19.11.2021.
A detailed description of change provided in a section
Degenerate case for transmitting error 196867 via DLR

7
Chapter 1. Introduction
Purpose and Scope
This document describes CPA System REST API for JSON data-interchange format.

The following is included:

• basic system description

• REST API description for JSON data-interchange format

• supported message types

• syntax

Support and development

CPA System is designed to provide high performance and low latency of message exchange. CPA
System implements the following APIs to enable interaction with Content Providers software:

• REST API for JSON and XML data-interchange formats

However, the development team recommends taking into account the following regarding the
implementation of interfaces for integration:

• REST API for JSON format is considered preferable and strongly recommended for
implementation since all new features are being developed for this particular format.

• REST API for XML format is implemented to allow legacy compatibility with Content Providers
software, which had been integrated with the previous version of the CPA System.
Support of XML format is considered an unpromising direction and has expired since 01.04.2019.

Related documentation
XML: Addition to CPA System API
The document specifies CPA System REST API for XML data-interchange format. The latest
document version can be downloaded via the link, or requested from KS responsible manager or
support team.

Confidentiality Statement
The information in this document is designated as 'commercial confidentiality'. Therefore, the
document or the information in it should not be provided to any party other than Kyivstar JSC (KS)
partners.

8
Chapter 2. Overview
The Content Provider Access System (CPA System) is a system that enables interaction between
subscriber and Content Provider. By Content Provider should be basically meant a system that
provides any informational services to subscriber. By subscriber should be basically meant a
person that employs the services provided by a telecommunication system or information
processing systems which transfers information.

Interaction between the subscriber and Content Provider derives from the following main needs:

1. Subscriber wants to order defined informational services.

2. Content Provider wants to provide informational services to subscriber.

Detailing above mentioned interaction next examples may be considered.

Example 1. Mobile originated message

Subscriber wants to order access to movie via short message.

A schematic representation of Example 1 is depicted in the following sketch.

Figure 1. Mobile originated message

As depicted in the Figure 1 subscriber sends a short message containing a defined token to a short
number dedicated for movie ordering. External content delivery system (SMS Centre) receives a
short message, performs required processing with billing system and forwards a short message to
CPA System. CPA System receives subscriber’s short message, processes this message, transforms it
into request and forwards it to Content Provider. Content Provider receives request and provides
access to movie for subscriber.

Mentioned example defines that subscriber himself requests an informational service. In a current
document is used a term ‘Mobile originated message’ (MO) to define a message with request for
informational service from subscriber to Content Provider.

If subscriber sends request for the information service to invalid short number,
 then CPA System provides a general auto reply to inform that a requested
number is out of use.

9
For deeper detailing of Example 1 is provided POST method example of CPA System REST API,
which CPA System uses in order to send message to Content Provider.

JSON request

POST http://{environment}/api/requests

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"rid": "d8549def-5d93-4e52-8b63-b282ccefa971",
"date": "1513296000000",
"source": "380672240001",
"destination": "101999",
"bearerType": "sms",
"contentType": "text/plain",
"content": "Hello Provider!"
}

Data parameters short description

rid - subscriber’s request identifier
date - date when CPA System received subscriber’s request
source - subscribers MSISDN (phone number)
destination - service number
bearerType - message type
contentType - type of content that is being sent to Provider
content - content that is being sent to Provider

Example 2. Mobile terminated message

Content Provider wants to provide an advertisement short message to subscriber.

A schematic representation of Example 2 is depicted in the following sketch.

Figure 2. Mobile terminated message

10
As depicted in the Figure 2 Content Provider sends request to CPA System using CPA System API.
CPA System in its turn processes this request, transforms it into message and forwards it to External
content delivery system (SMS Centre). SMS Centre receives message, performs required processing
with billing system, and forwards a short message to subscriber.

Mentioned example defines that Content Provider sends an advertisement short message without
prior subscriber’s request. In current document is used term ‘Mobile terminated message’ (MT) to
define message with informational service from Content Provider to subscriber.

For deeper detailing of Example 2 is provided POST method example of CPA System REST API,
which Content Provider uses in order to send short message to subscriber.

JSON request

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"source": "101999",
"destination": "380670000001",
"serviceType": "true"
"bearerType": "sms"
"contentType": "text/plain"
"content": "Hello World!"
}

Data parameters short description

source - service number
destination - subscribers MSISDN (phone number)
serviceType - type of payment for the message
bearerType - message type
contentType - type of content that is being sent to subscriber
content - content that is being sent to subscriber

11
Chapter 3. Transactions
The Content Provider Access System REST API is designed as a messaging protocol for interaction
between CPA System and Content Provider and implements following methods:

POST

• to accept content from Content Provider and forward it to subscriber (Mobile terminated
message)

• to forward subscriber’s request for content to Content Provider (Mobile originated message)

• to send Delivery report to Content Provider (Delivery report)

GET
• to accept request from Content Provider to retrieve Delivery report (Delivery report)

3.1. Interaction
3.1.1. Description

Interaction means an act of sending one message. The party which is sending the message is called
the sender and the party which receives the message is called the receiver. To complete the
interaction, sender and receiver perform following steps:

1. The sender generates a request.

2. The sender initiates an HTTP connection to the URL corresponding to the receiver. (How the
sender learned which URL to use, is outside the scope of this document – one could safely
assume that these URLs are exchanged before, as a part of CPA System and Content Provider
initial setup.)

3. The sender sets appropriate authorization information in a request, according to used

authorization scheme.

4. The sender submits a request, transmitting the message in the body of a request.

5. The receiver validates message (performs internal required checks).

1. If message passes validation, the receiver generates HTTP response, which has HTTP status
code of 202 and contains message identifier (mid).

2. If message does not pass validation, the receiver generates HTTP response, which contains
HTTP status and error message.

6. The receiver sends HTTP response to the sender.

Invalid message is not proceed further.

12
3.1.2. Assumptions

Indirect interaction with subscriber

CPA System APIs enable interaction between CPA System and Content Provider in order to either
transport subscriber’s order for content to Content Provider or provide content to subscriber.
However neither CPA System nor Content Provider does not interact with subscriber directly.

Mobile originated content request from subscriber is sent through defined communication channel
to External content delivery system, which in it’s turn delivers it to CPA System and than CPA
System forwards it to Content Provider. The same way Mobile terminated content response from
Content Provider is sent to CPA System, than forwarded to External content delivery system, which
in it’s turn delivers it to subscriber through defined communication channel.

For the purpose of current document can be used phrases like ‘deliver/send to subscriber’,
‘receive/accept from subscriber’ in order to facilitate understanding of general business logic. Upon
further thought it is necessary to understand that 'deliver/send' to- or ‘receive/accept' from
subscriber means indirect interaction through External content delivery system.

Charging

Content provided to subscriber can require subscriber’s charging. However CPA System does not
charge subscriber by itself. In case if charges for content are required, CPA System can only initiate
pre-check whether subscriber’s core balance is enough to be charged. Mentioned pre-check
operation is performed by external system.

For the purpose of current document can be used phrases like 'to initiate subscriber’s core balance
pre-check', ‘to initiate subscriber’s charging’ or common in order to facilitate understanding of
general business logic. Upon further thought it is necessary to understand that any actions for
subscriber’s charging are performed by external system.

13
3.2. Transaction messages
3.2.1. Mobile terminated message

Description

MT message - a message generated by Content Provider and sent to CPA System to provide
informational services (content) to the subscriber.

Processing flow

MT message processing flow is depicted by the following sequence diagram.

Figure 3. Sequence diagram for MT processing

Sequence diagram description

To transmit content from Content Provider to the subscriber, the below-mentioned interactions are
performed.

1. Content Provider sends MT message to CPA System (detailed syntax for MT message provided in
a section Send MT)

2. CPA System:

• accepts MT message from Content Provider

• performs MT message required validations (some details on validations are provided in a

section Validations)

14
 • matches MT message to Content Providers configurations to define an applicable rule

• checks that Content Provider does not exceed the limit of allowed MT messages per day

• requests a necessary subscriber’s information (from an external system) if required by a

matched rule (e.g. subscriber’s operator, payment type (prepaid/postpaid), state)

• requests a necessary subscriber’s billing information (from an external system) if required

by a matched rule (e.g. subscriber’s balance)

• validates a received subscriber’s information according to the matched rule

• whether subscriber belongs to Kyivstar operator

• whether subscriber’s core balance is enough to be charged

• converts MT message to a proper format according to the External content delivery system
API (SMS Center/Viber)

• provides an acceptance response to Content Provider

• sends MT message to the External content delivery system (SMS Center/Viber)

3. External content delivery system (SMS Center/Viber):

• accepts MT message from CPA System

• performs MT message validations

• provides an acceptance response to CPA System

• transmits content to the subscriber

4. CPA System:

• accepts response from the External content delivery system (SMS Center/Viber)

• stores MT message to the database

In case if at least one validation passed unsuccessfully and MT message cannot be transmitted
further, CPA System fails MT message processing, and responses to Content Provider with an error
message (detailed list of possible errors provided in a section Error information).

Sequence diagram assumptions

The mentioned diagram overviews interactions between CPA System and all engaged systems
(subscriber profile system, billing system) to perform business logic and route MT message from a
high-level perspective. Not every MT message passes all mentioned validation steps. Validation
steps can include mentioned ones, but are not limited by them.

15
3.2.2. Mobile originated message

Description

MO message - a message from subscriber to Content Provider to order informational services.

Processing flow

MO message processing flow is depicted by the following sequence diagram.

Figure 4. Sequence diagram for MO processing

Sequence diagram description

To transmit a content request from the subscriber to Content Provider, the below-mentioned
interactions are performed.

1. Subscriber sends a content request (sms message) to the Content Provider’s short number

2. SMS Center accepts a content request from the subscriber and transmits it to CPA System

3. CPA System:

• accepts a content request from SMS Center

• provides an acceptance response to SMS Center

• converts a content request to a proper format prescribed by the current Specification

(detailed syntax for MO message provided in a section Receive MO)

• generates request identifier (rid)

• sends MO message to Content Provider

16
4. Content Provider:

• accepts MO message

• provides response with HTTP code 204 (No content) to CPA System as a response to the
accepted MO message

5. CPA System:

• accepts response from Content Provider

• stores MO message to the database

17
3.2.3. Delivery report

Description

Delivery report (DLR) - a message generated by CPA System and sent to Content Provider in order to
inform on result of sending content to the subscriber. Initially, sending of Delivery report is
performed by CPA System automatically on a regular basis, but it also can be retrieved by Content
Provider manually.

DLR is generated for successfully processed MT only

Delivery report is generated only for the MT message which passed the whole processing flow
on CPA System side successfully and was sent out to the External content delivery system.
Processing flow includes message general validation and internal business logic. Delivery report
is not generated for the MT message failed due to validation or business logic errors, and was
not sent out to External content delivery system. In other words, DLR is never generated for MT,
when the acceptance response for this MT contains any errors.

Time point when CPA System generates DLR

CPA System generates DLR, when a delivery report from External content delivery system is
received. There is a time lag between successful acceptance of a message on the External content
delivery system side and actual delivery to the subscriber. Generally, the message is being sent
to subscriber straightaway, but if delivery failed due to network problems or subscriber
unavailability, then attempts to redeliver message are taken during a predefined period of time.
This period is configurable and depends on a delivery channel:

• for sms-traffic it can last up to 1 day

• for viber-traffic it can last up to 14 days

In case if Content Provider requests DLR for the message, which is still in a process of sending to
the subscriber, then DLR for such MT cannot be found, and CPA System responses with HTTP code
404 (Not Found) and error message "Resource not found".

Content Provider can request DLR only for his own MT

CPA System checks whether the requested DLR really relates to the Content Provider. In case if
Content Provider requests DLR, and MT (for which requested DLR was generated) was not sent
by this particular Content Provider, then CPA System responses with HTTP code 404 (Not Found)
and error message "Resource not found".

Successful DLR

Scenario for a successful DLR considers that MT message passed the whole processing flow on CPA
System side, and was forwarded to the External content delivery system successfully. Further
External content delivery system informs CPA System that content was sent to the subscriber. Based
on this information CPA System generates and sends DLR to Content Provider.

18
Unsuccessful DLR

Scenario for an unsuccessful DLR considers that MT message passed the whole processing flow on
CPA System side, but forwarding it to the External content delivery system passed unsuccessfully, or
MT message was rejected by External content delivery system. In such case CPA System generates
and sends to Content Provider DLR with the status which indicates unsuccessful delivery.

Methods/ways for DLR transmitting

CPA System provides 2 ways for transmitting DLR to Content Provider

• regular transmitting - a basic/regular way when CPA System sends DLR to Content Provider as
soon as DLR is received from the External content delivery system; CPA System uses POST
method to send DLR to Content Provider

• transmitting by request - an additional/optional way when Content Provider requests DLR

from CPA System; Content Provider uses GET method to request DLR from CPA System

Detailed syntax for both methods provided in the following sections:

• Receive DLR

• Get DLR

Methods usage and restrictions

DLR transmitting mechanisms are designed as follows

Content Provider implements an endpoint to receive DLRs from CPA System on a regular basis
(detailed syntax provided in a section Receive DLR), and if necessary,
Content Provider may implement an additional/optional method - GET - to request distinct DLRs,
in case if they seem to be missed or lost (detailed syntax provided in a section Get DLR)

GET DLR method cannot be assumed as the basic and single way to obtain delivery reports if
they are needed.

Access to GET DLR restricted for those Content Providers that did not implement
 the feature to accept DLRs from CPA System on a regular basis

If Content Provider requests DLR, and it is restricted on CPA System side, then the following error
response is provided

Status code: 403

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"errorId": 1041,
"errorMsg": "Get DLR request is not allowed"
}

19
Processing flow for transmitting DLR on a regular basis

A standard flow for transmitting DLR to Content Provider as soon as it was received from the
External content delivery system is depicted by the following sequence diagram.

Figure 5. Sequence diagram for transmitting DLR to Content Provider on a regular basis

Sequence diagram description

To transmit DLR from CPA System to Content Provider, the below-mentioned interactions are
performed.

1. External content delivery system (SMS Center/Viber) sends content to the subscriber

2. Subscriber (subscriber’s mobile station, or Viber application):

• accepts content

• provides a delivery report to the External content delivery system (SMS Center/Viber)

3. External content delivery system (SMS Center/Viber):

• accepts a delivery report

• provides a delivery report to CPA System

20
4. CPA System:

• accepts a delivery report from the External content delivery system

• provides an acceptance response to External content delivery system

• matches a delivery report to MT message

• converts a delivery report to a proper format prescribed by the current Specification

(detailed syntax for DLR provided in a section Receive DLR)

• sends a delivery report to Content Provider

5. Content Provider:

• accepts a delivery report

• provides response with HTTP code 204 (No content) to CPA System as a response to the
accepted delivery report

6. CPA System:

• accepts response from Content Provider

• stores delivery report to the database

Redelivery
In case if Content Provider is unavailable, and cannot accept DLR, then CPA System tries to
redeliver DLR twice according to the following schedule:

• first redelivery attempt is performed in 5 min after unsuccessful delivery

• second redelivery attempt is performed in 15 min after the first unsuccessful redelivery attempt

The redelivery mechanism is configurable and may be changed.

21
Processing flow for transmitting DLR by request

An additional/optional flow for transmitting DLR to Content Provider initiated by Content

Provider’s request is depicted by the following sequence diagram.

Figure 6. Sequence diagram for transmitting DLR to Content Provider by request

Sequence diagram description

To request DLR from CPA System, the below-mentioned interactions are performed.

1. Content Provider sends a request to CPA System

2. CPA System:

• retrieves DLR from database

• responses with HTTP code 200 (OK) and body containing a delivery report

3. Content Provider accepts a delivery report

In case if DLR is not found in the database, then CPA System responds to Content Provider with
HTTP code 404 (Not Found) and the error message 'Resource not found'.

In case if access to Get DLR method is restricted, then CPA System responds to Content Provider
with HTTP code 403 (Forbidden) and the error message 'Get DLR request is not allowed'.

22
Chapter 4. Syntax notation
In current section are provided detailed syntax notation and examples of CPA System REST API.

4.1. Send MT
Resource

http://{environment}/api/contents

Method

POST

MT HTTP request body minimal required set example

{
"source": "101999",
"destination": "380670000001",
"content": "Hello World!"
}

MT HTTP request body max set example

{
"rid": "d8549def-5d93-4e52-8b63-b282ccefa971",
"source": "101999",
"destination": "380670000001",
"serviceType": "true",
"bearerType": "sms",
"contentType": "text/plain",
"callbackNum": "69",
"ttl": 7200,
"content": "Hello World!"
}

MT HTTP request body data parameters short description

rid - subscriber’s request identifier
source - service number
destination - subscribers MSISDN (phone number)
serviceType - type of payment for the message
bearerType - message type
contentType - type of content that is being sent to subscriber
callbackNum - Content Provider’s callback number
ttl - message time to live in CPA System
content - content that is being sent to subscriber

23
Success HTTP response example

Status code: 202

{
"mid": "904705f0-3c5e-4556-81b7fd2e3d83"
}

Error HTTP response example

Status code: 400

{
"mid": "904705f0-3c5e-4556-81b7fd2e3d83",
"errorId": 1019,
"errorMsg": "Invalid destination address"
}

MT HTTP response body data parameters short description

mid - message identifier
errorId - error identifier
errorMsg - error message

Table 2. MT HTTP request body data parameters detailed description

# Name Type Required Description Ref

1 rid string no subscriber’s request identifier rid

(UUID)

2 source string yes service number source

3 destination string yes subscribers MSISDN (phone destination

number) or hashed value

4 serviceType string no type of payment for the message serviceType

5 bearerType string no message type bearerType

6 contentType string no type of content in field 'content' contentType

that is being sent to subscriber

7 callbackNum string no Content Provider’s callback callbackNum

number

8 ttl int no message time to live in CPA ttl

System

9 content string yes content that is being sent to content

subscriber

24
Table 3. MT HTTP response body data parameters detailed description

# Name Type Required Description Ref

1 mid string yes message identifier (UUID) mid

2 errorId integer no error identifier errorId

3 errorMsg string no error message errorMsg

25
4.2. Receive MO
Resource example

http://{environment}/api/requests

Method

POST

MO HTTP request body example

{
"rid": "d8549def-5d93-4e52-8b63-b282ccefa971",
"date": "1513296000000",
"source": "380672240001",
"destination": "101999",
"params": {"514":"1", "515":"1"},
"bearerType": "sms",
"contentType": "text/plain",
"content": "Hello Provider!"
}

MO HTTP request body data parameters short description

rid - subscriber’s request identifier
date - date when CPA System received subscriber’s request
source - subscribers MSISDN (phone number)
destination - service number
params - nested json object with optional parameters
bearerType - message type
contentType - type of content that is being sent to Provider
content - content that is being sent to Provider

Success HTTP response example

Status code: 204

26
Table 4. MO HTTP request body data parameters detailed description

# Name Type Required Description Ref

1 rid string yes subscriber’s request identifier rid

(UUID)

2 date integer yes date when CPA System received date

subscriber’s request

3 source string yes subscribers MSISDN (phone source

number) or hashed value

4 destination string yes service number destination

5 params object no object with optional parameters params

6 bearerType string no message type bearerType

7 contentType string no type of content in field 'content' contentType

that is being sent to Content
Provider

8 content string yes content that is being sent to content

Content Provider

27
4.3. Receive DLR
Resource example

http://{environment}/api/reports

Method

POST

DLR HTTP request body example (content delivered successfully)

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"date": "1513296000000",
"status": "delivered"
}

DLR HTTP request body example (message expired)

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"date": "1513296000000",
"status": "expired"
}

DLR HTTP request body data parameters short description

mid - message identifier
date - date when CPA System received delivery report from External content delivery system
status - content delivery status

Expected HTTP response example

Status code: 204

Table 5. DLR HTTP request body data parameters detailed description

# Name Type Required Description Ref

1 mid string yes message identifier (UUID) mid

2 date integer no date when CPA System received date

delivery report from External
content delivery system

2 status string yes content delivery status status

28
4.4. Get DLR
GET DLR method cannot be assumed as the basic and single way to obtain
delivery reports if they are needed. Access to GET DLR method restricted since
 01.08.2021 for those Content Providers that do not implement the feature to
accept DLRs from CPA System on a regular basis.
Detailed syntax on how to receive DLRs provided in a section Receive DLR

Resource

http://{environment}/api/reports/{mid}

Method

GET

GET DLR HTTP request example

http://{environment}/api/reports/d8549def-5d93-4e52-8b63-b282ccefa971

GET DLR HTTP request uri parameters short description

{mid} - message identifier

Success HTTP response example | DLR

Status code: 200

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"date": "1513296000000",
"status": "delivered"
}

Error HTTP response example | DLR not found

Status code: 404

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"errorId": 1040,
"errorMsg": "Resource not found"
}

29
Error HTTP response example | Request DLR not allowed

Status code: 403

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"errorId": 1041,
"errorMsg": "Get DLR request is not allowed"
}

DLR HTTP response body data parameters short description

mid - message identifier
date - date when CPA System received delivery report from External content delivery system
status - content delivery status
errorId - error identifier
errorMsg - error message

Table 6. GET DLR HTTP request uri parameters detailed description

# Name Type Required Description Ref

1 mid string yes message identifier (UUID) mid

Table 7. DLR HTTP response body data parameters detailed description

# Name Type Required Description Ref

1 mid string yes message identifier (UUID) mid

2 date integer yes date when CPA System received date

delivery report from External
content delivery system

3 status string yes content delivery status status

4 errorId integer no error identifier errorId

5 errorMsg string no error message errorMsg

30
Chapter 5. Headers definition
5.1. Headers
5.1.1. Authorization

Client Authentication is handled by the server using HTTP Basic Authentication.

Content Provider should set its login and password concatenated in the form
<username>:<password>, encoded using base64, into the Authorization header, as follows:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Exceptions processing

Unknown ip
If Content Provider sends the request from the unknown ip address, then CPA System rejects the
request with the following data:

HTTP status 403 Forbidden

Content-Type: text/plain; charset=UTF-8
ip not allowed: {ip}

Invalid login/password
If Content Provider sends the request with the invalid login or password, then CPA System rejects
the request with the following data:

HTTP status 401 Unauthorized

Content-Type: text/plain; charset=UTF-8

5.1.2. Content-Type

The Content-Type entity is used to indicate the media type of the resource.

Content Provider should set its request data type into the Content-Type header, as follows:

Content-Type: application/json

Exceptions processing

Invalid Content-Type
If Content Provider sets the value that differs from the prescribed one by the current Specification,
then CPA System rejects the request with the following data:

HTTP status 415 Unsupported Media Type

Content-Type: text/plain; charset=UTF-8
invalid media type

31
5.2. Header examples
5.2.1. MT message headers

The MT message has to contain 2 mandatory headers:

• Authorization

• Content-Type

CPA System expects that Content Provider sends the MT message with the following headers:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

Acceptance response

If the MT message is accepted successfully, then CPA System provides to the Content Provider an
acceptance response with the following headers:

X-Correlation-ID: 80a53918-fa97-4650-89a8-e65cd610cf38
Content-Type: application/json

X-Correlation-ID
the unique identifier of the object into which the received MT message and its Delivery report
are aggregated; is used for service purposes by the support team of the CPA System, and can be
ignored by Content Providers.

5.2.2. GET DLR request headers

The GET DLR request:

• has to contain 1 mandatory header - Authorization

• may contain 1 optional header - Content-Type

Content Provider can send GET DLR request with the following headers:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

Content Provider can send GET DLR request with the following header:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Both variants are processed the same way.

32
Acceptance response

If the GET DLR request is accepted successfully, then CPA System provides to the Content Provider
an acceptance response with the following header:

Content-Type: application/json

5.2.3. MO/DLR messages headers

CPA System provides to the Content Provider the MO message, and the Delivery report with the
following headers:

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

33
Chapter 6. Parameters definition
6.1. Mandatory parameters
6.1.1. date

Definition
Parameter definition depends on request type:

• for MO date defines time and date when CPA System received subscriber’s request from
External content delivery System;

• for DLR date defines time and date when CPA System received DLR from External content
delivery System.

Format
Parameter format should be set as TIMESTAMP (UTC) in milliseconds.

Example

Time and date: Wednesday, January 31, 2018 12:45:15 PM

TIMESTAMP (UTC) in ms: 1517402715000

Features
1. Parameter has no default value.

6.1.2. destination

Definition
Parameter defines message destination number.
Destination number where the message is sent to depends on request type:

• for MO destination defines Content Provider’s service number;

• for MT destination defines subscriber’s msisdn (phone number).

Features
1. Parameter has no default value.

2. Parameter max length is 32 symbols (for MT).

34
6.1.3. content

Definition
Parameter defines content that is being sent; cannot be empty string.

Features
1. Parameter has no default value.

2. Parameter max length is 1000 symbols.

3. The receiver of content depends on request type:

• for MO content is being sent to Content Provider;

• for MT content is being sent to subscriber.

4. Parameter’s length recommendations for sms/plain message

"bearerType": "sms"
"contentType": "text/plain"

Content on CPA System side and on SMS Centre side is proceed in a bit different ways.

CPA System does not split content into single parts, but it validates content according to max
recommended length, and encodes it according to provided characters:

• if content contains characters which belong only to the basic set of '7-bit default alphabet'
(SMSCDefaultAlphabet), then message is encoded to '7-bit default alphabet';
for this encoding recommended length is <= 1000 characters

• if content contains at least one character out of '7-bit default alphabet', then message is encoded
to UCS2(ISO/IEC-10646);
for this encoding recommended length is <= 499 characters

SMS Centre splits content into single message parts (for transport purposes), which are
concatenated into a one sms message on subscriber’s device side. A single message part length
depends on encoding:

• using '7-bit default alphabet' (SMSCDefaultAlphabet) encoding, it is possible to send up to 160

characters in a single message part

• using UCS2(ISO/IEC-10646) encoding, it is possible to send up to 70 characters in a single sms

message part

Hence, content is divided into single parts when it is longer than:

• 160 symbols for '7-bit default alphabet' encoding, or

• 70 symbols for UCS2 encoding, until it is not larger than max length.

35
5. Parameter’s length recommendations for ussd message

ussd/push ussd/menu

"bearerType": "ussd" "bearerType": "ussd"

"contentType": "text/ussn" "contentType": "text/ussr"

• recommended length is <= 255 bytes

The following can be taken into consideration:

 - 1 latin character equals to 1 byte
- 1 cyrillic character equals to 2 bytes

6. Parameter’s length recommendations for viber/text message

Parameter’s recommended length is applicable to any encoding but depends on a content type
(contentType)

content type recommended length

"contentType": "text/plain" <= 1000 characters

"contentType": "text/template" <= 950 characters

6.1.4. mid

Definition
Message identifier - a string used to identify a particular Mobile terminated content response.
Parameters mid are used by CPA System and Content Provider in all messages concerning a
particular Mobile terminated content response.

Format
UUID.

Features
1. Parameter has no default value.

2. Parameter is generated by CPA System and sent back to Content Provider in acceptance
response.

6.1.5. source

Definition
Parameter defines number of message origin.
Source number where the message is received from depends on request type:

• for MO source defines subscriber’s MSISDN (phone number);

• for MT source defines Content Provider’s service number.

36
Features
1. Parameter has no default value.

2. Parameter max length is 12 symbols (for MT).

3. Parameter value to be set, has some limitations for viber-traffic (for mt messages with
"bearerType": "viber"). Value to be set in a request should be equal to an identifier issued by
Viber, and should be provided by a manager.

6.1.6. status

Definition
Parameter defines result of sending content to subscriber (delivery status of MT message to
subscriber).

Features
1. Parameter is used only for request type DLR.

2. Parameter has no default value.

3. Parameter’s values vary depending on External content delivery system via which MT is being
delivered to subscriber (SMS Centre, Viber).

sms-traffic
For sms-traffic status is being set as closely as possible to Short Message Peer to Peer Protocol
Specification v3.4. CPA System does not implement statuses of SMPP Protocol strictly, but tries to
adhere as closely as possible. Some below mentioned statuses may be not used in a practice. Main
and definitely in-use values are: delivered, expired and undeliverable.

Parameter can take one of the following values:

main statuses:

• delivered - message is delivered to the destination successfully

• expired - message is not delivered to the destination due to the time to live expiration

• undeliverable - message has encountered a delivery error and is deemed permanently

undeliverable; no further delivery attempts will be made; certain network or SMS Centre
internal errors result in the permanent non-delivery of a message; examples of such errors can
be: an unknown subscriber, or network error that indicates that the given destination mobile
could not support SMS, or service of receiving SMS is disabled

37
additional statuses:

• accepted - message has been accepted on SMS Centre side and delivery attempts will be made

• deleted - message has been cancelled or deleted on SMS Centre side (most likely deleted
manually by SMS Centre administrator)

• enroute - message is in the process of being sent to the destination

• rejected - message was rejected on SMS Centre side due to internal business logic; no delivery
attempts were made

• rejected_subscriber_billing_error - message was rejected on SMS Centre side due to billing

system error, most commonly due to subscriber’s low balance; no delivery attempts were made
available since 19.11.2021

• rejected_spam - message was rejected on SMS Centre side as provided content is recognized as
spam; no delivery attempts were made

• unknown - most likely, SMS Centre failure, or message has already passed to the final status and
has been deleted from the SMS Centre, i.e. no longer exists on SMS Centre side

viber-traffic
For viber-traffic setting of status does not refer to domain standards, but is implemented in a way
to inherit sms-traffic statuses as close as possible.

Parameter can take one of the following values:

• accepted_unmatched - message has been accepted on Viber side and delivery attempts will be
made, but sent template message did not match any Content Provider’s available templates;
additional intermediate status applicable only to template messages;
(as soon as message delivered to the destination successfully, accepted_unmatched status is being
updated to delivered)

• blacklist - message was rejected on Viber side due to subscriber reason, more specifically,
because subscriber unsubscribed from the specific sender or from receiving viber business
messages completely

• declined - message was rejected on Viber side due to subscriber reason, more specifically,
because subscriber is not registered on viber; has no viber application

• delivered - message is delivered to the destination successfully

(as soon as subscriber opens a message, delivered status is being updated to seen; but if
subscriber never opened a message, and message time to live expired, then delivered status is
being updated to expired)

• expired - message is not delivered to the destination due to the time to live expiration

• rejected - message was rejected on Viber side due to internal business logic, e.g. invalid request
syntax, invalid client configuration, billing errors, timeout; no delivery attempts were made

• seen - subscriber opened Viber application and entered the conversation with the specific
message

38
6.2. Optional parameters
Each request type has a set of mandatory and optional parameters. Must be taken
 into account the following: if optional parameter is included to request body, than
it has to contain value, otherwise request is not being processed by CPA System.

6.2.1. bearerType

Definition
Parameter defines message type.

Features
1. Parameter max length is 10 symbols.

2. Parameter can take one of the following values:

• sms

• ussd

• viber

3. Parameter has default value.

"bearerType": "sms"

If parameter is not set in request, then CPA System sets default value.

6.2.2. callbackNum

Definition
Parameter defines Content Provider’s additional callback number or identifier used for billing,
charging purposes. Most commonly, parameter defines Content Provider’s billing identifier.
Parameter can be used only by preliminary agreement.

Features
1. Parameter is used only for request type MT.

2. Parameter has no default value.

3. Parameter max length is 32 symbols.

4. Parameter is allowed to be used only by preliminary agreement with Kyivstar JSC.

5. Parameter value to be set, has some limitations for viber-traffic (for mt messages with
"bearerType": "viber"). Value to be set in a request should be equal to an identifier issued by
Kyivstar, and should be provided by a manager.

39
6.2.3. contentExtended

Definition
Parameter defines a complex media content that is being sent.

Features
1. Parameter is represented as an object with nested parameters to place additional content.

2. Parameter is used only for request type MT.

3. Parameter can be used only for the viber message types.

4. Object can contain following nested parameters:

• label
• tag
• txt
• img
• caption
• action

label

Definition
Parameter defines type of content in a viber message to indicate whether viber message contains a
service plain text or promotion plain text, or media. Can be used for reports, analytics etc. on
Content Provider’s side.

Features
1. Parameter should be included in the object contentExtended.

2. Parameter is used only for request type MT.

3. Parameter can be used only for the viber message types.

4. Parameter can take one of the following values:

• transaction

• promotion

Definite value depends on a content type (contentType):

content type required label

"contentType": "text/template" "label": "transaction"

"contentType": "text/plain" "label": "promotion"

"contentType": "image/plain"
"contentType": "text/img/button"

40
5. If parameter is not set in request, then CPA System sets a proper value according to provided
contentType.

tag

Definition
Parameter defines a specific mark to indicate any kind of valuable for Content Provider
information. Can be used for reports, analytics etc. on Content Provider’s side.

Features
1. Parameter should be included in the object contentExtended.

2. Parameter’s recommended length is <= 100 characters for any encoding.

3. Parameter is used only for request type MT.

4. Parameter can be used only for the viber message types.

txt

Definition
Parameter defines content represented as a text, that is being sent within a complex viber media
message or within a viber text message in a conjunction with additional information.

Features
1. Parameter should be included in the object contentExtended.

2. Parameter’s recommended length is applicable to any encoding but depends on a content type
(contentType):

• for "contentType": "text/plain" recommended length is <= 1000 characters

• for "contentType": "text/template" recommended length is <= 950 characters

3. Parameter is used only for request type MT, and can be used for the following viber message
types:

• "contentType": "text/plain";

• "contentType": "text/template";

• "contentType": "text/img/button".

4. Parameter should not be used for any other viber message types.

img

Definition
Parameter defines a web based link to the image.

Features
1. Parameter should be included in the object contentExtended.

2. Parameter’s recommended resolution is not less than 400x400 pixels.

41
3. Parameter is used only for request type MT, and can be used for the following viber media
message types:

• "contentType": "text/img/button";

• "contentType": "image/plain".

4. Parameter should not be used for any other viber message types.

caption & action

Definition
Parameters caption and action must be used together as they both represent the button:

• caption - textual writing on the button;

• action - a link to a necessary resource, redirection to which is executed within button pressing.

Features
1. Parameters should be included in the object contentExtended.

2. caption recommended length is <= 30 characters.

3. Parameters are used only for request type MT, and can be used for the following viber media
message type:

• "contentType": "text/img/button".

4. Parameter should not be used for any other viber message types.

6.2.4. contentType

Definition
Parameter defines type of content in parameter 'content' that is being sent.

Features
1. Parameter max length is 20 symbols.

2. Parameter can take one of the following values:

• text/plain

• text/zero

• smpp/binary

• text/ussn

• text/ussr

• text/template

• image/plain

• text/img/button

Definite value depends on message type (bearerType):

42
 a. for "bearerType": "sms", contentType can be set to:

• text/plain

• text/zero

• smpp/binary

b. for "bearerType": "ussd", contentType can be set to:

• text/ussn

• text/ussr

c. for "bearerType": "viber", contentType can be set to:

• text/plain

• text/template

• image/plain

• text/img/button

3. Parameter has default value.

Default value depends on message type.

for "bearerType": "sms" default value: "contentType": "text/plain"

for "bearerType": "ussd" default value: "contentType": "text/ussn"

If parameter is not set in request, then CPA System sets default value.

6.2.5. errorId

Definition
Parameter defines error identifier.

Features
1. Parameter has no default value.

2. Parameter values are provided in Error information

6.2.6. errorMsg

Definition
Parameter defines error message.

Features
1. Parameter has no default value.

2. Parameter values are provided in Error information

43
6.2.7. params

Definition
Object that contains a set of any optional parameters (TLV) according to 'Short Message Peer to Peer
Protocol Specification v3.4' needed for Content Provider.

Format
Object.

Features
1. Object is used only for request type MO.

2. Object can contain a set of optional parameters represented as pair: "key":"value". Quantity of
pairs can vary from 1 to n. Pairs are separated by commas.

3. Object is allowed to be used only by preliminary agreement with Kyivstar JSC.

6.2.8. rid

Definition
Request identifier - a string used to identify a particular Mobile originated content request.
Parameters rid are used by CPA System and Content Provider in all messages concerning a
particular Mobile originated content request and requested Mobile terminated content response.

Format
UUID.

Features
1. Parameter has no default value.

2. Parameter max length is 40 symbols.

3. Parameter is generated by CPA System and forwarded to Content Provider.

4. Parameter requiredness depends on request type:

• for MO rid is mandatory;

• for MT rid is optional. Content Provider must set rid only in requested MT, sent as response
to a particular MO.

6.2.9. serviceType

Definition
Parameter defines type of payment for the message. Also, parameter can be used to prioritize time-
sensitive traffic (e.g. one time passwords).

Features
1. Parameter is used only for request type MT.

2. Parameter max length is 5 symbols.

44
3. Parameter can take one of the following values:

• 'false', '0'' - message is free;

• 'true', '1000' - message is paid by subscriber;

• '2xxx' - message is paid by Content Provider.

4. Parameter has default value.

"serviceType": "false"

If parameter is not set in request, then CPA System sets default value.

6.2.10. ttl

Definition
Parameter defines time to live of MT message in CPA System in case if MT is not delivered to
External content delivery system from the first time. Parameter is also passed to External content
delivery system (SMS Centre, Viber), where it defines message time to live in case if it is not
delivered to subscriber from the first time.

Features
1. Parameter is used only for request type MT.

2. Parameter value should be set in seconds.

3. Parameter has a single default value for sms and viber messages.

"ttl": "86400"

If parameter is not set in a request, then CPA System sets a default value.

4. Parameter has allowed range of values limited by min and max values, that depend on a
message type (bearerType):

• for "bearerType": "sms" parameter value should be set in a range: 30 to 86400 seconds
(from 30 sec to 1 day)

• for "bearerType": "viber" parameter value should be set in a range: 30 to 1209600 seconds
(from 30 sec to 14 days)

If Content Provider sets value out of allowed range, then processing of provided MT is failed
with error 1071 'Invalid parameter value: %parameter%'.

45
Chapter 7. Message types
CPA System provides an opportunity to transfer different informational services from Content
provider to subscriber and vice verse by using different message and content types. One message
type can support several content types.

Message type is defined by parameter: bearerType

Content type is defined by parameter: contentType

Detailed description, syntax and examples of different message types with relevant content types
are provided in next sections.

7.1. SMS message

SMS message (short message) - a brief message sent to/from subscriber through the Short Message
Service (SMS).

Within interaction between CPA System and Content Provider SMS message can be defined by
using following parameter:

"bearerType": "sms"

CPA System provides an opportunity to use following SMS message types:

1. plain

2. binary

3. silent

Detailed description is provided in next sections.

7.1.1. SMS/plain

SMS/plain (plain short message; plain SMS message) - readable short message, represented by
standard ASCII characters, including numbers, symbols, and spaces.

Within interaction between CPA System and Content Provider SMS/plain can be defined by using
following parameters:

"bearerType": "sms"
"contentType": "text/plain"

However, it is not necessary to set above-mentioned parameters, as CPA System sets "bearerType":
"sms" and "contentType": "text/plain" by default if they are absent in request.

46
Content Provider can send SMS/plain as provided in following example.

MT SMS/plain HTTP request body example

{
"source": "101999",
"destination": "380670000001",
"content": "Hello World!"
}

MT HTTP request body data parameters detailed descriptions is provided in section Send MT.

7.1.2. SMS/silent

SMS/silent (silent short message; silent SMS message; short message type 0; SMS0) - a special type
of short message that is indicated neither on the display nor by an acoustic signal. SMS/silent is not
saved in phones memory and does not contain any content. Is frequently used to allow SMSC
perform subscriber’s core balance charging.

Within interaction between CPA System and Content Provider SMS/silent can be defined by using
following parameters:

"bearerType": "sms"
"contentType": "text/zero"

However, it is not necessary to set one above-mentioned parameter - bearerType, as CPA System sets
"bearerType": "sms" by default if it is absent in request.

Content Provider can send SMS/silent as provided in following example.

MT SMS/silent HTTP request body example

{
"source": "101999",
"destination": "380670000001",
"contentType": "text/zero"
}

MT HTTP request body data parameters detailed descriptions is provided in section Send MT.

47
7.1.3. SMS/binary

SMS/binary (binary short message; binary SMS message) - a binary short message; commonly not
viewable by phone as text messages and used for data (e.g. images and ringing tones) or installation
messages.

Within interaction between CPA System and Content Provider SMS/binary can be defined by using
following parameters:

"bearerType": "sms"
"contentType": "smpp/binary"

However, it is not necessary to set one above-mentioned parameter - bearerType, as CPA System sets
"bearerType": "sms" by default if it is absent in request.

Content Provider can send SMS/binary as provided in following example.

MT SMS/binary HTTP request body example

{
"source": "101999",
"destination": "380670000001",
"contentType": "smpp/binary"
"content": "SSBrbm93IHdoYXQgeW91IGdvb2dsZSBsYXN0IG5pZ2h0IEhBSEE="
}

MT HTTP request body data parameters detailed descriptions is provided in section Send MT.

48
7.2. USSD message
USSD (Unstructured Supplementary Service Data) - a communication protocol used by GSM cellular
telephones to communicate with the mobile network operator’s computers.

USSD message
USSD message (from subscriber’s viewpoint) - a code that consist of digits and special signs. A
typical USSD message starts with an asterisk *, followed by digits that comprise commands or
data. Groups of digits may be separated by additional asterisks. The message is terminated with
a sign #.

USSD message format: *XXX*YYY#, where:

XXX – USSD code
YYY – USSD command; may contain digits and asterisks

CPA System provides an opportunity to use following USSD operations:

1. USSD/push.

2. USSD/menu.

7.2.1. USSD/push

USSD/push operation intends mono-directional message sending. Content Provider can send
message which requires no subscriber’s response. In current document is used term ‘Unstructured
Supplementary Services Notification’ (USSD notification, USSN message, USSN) to define
USSD/push message with informational service which requires no response.

Within interaction between CPA System and Content Provider USSN message can be defined by
using following parameters:

"bearerType": "ussd"
"contentType": "text/ussn"

However, it is not necessary to set one above-mentioned parameter - contentType, as CPA System
sets "contentType": "text/ussn" by default if it is absent in request.

Content Provider can send USSN message as provided in following example.

MT USSN HTTP request body example

{
"source": "101999",
"destination": "380670000001",
"bearerType": "ussd",
"content": "World enddate is tomorrow!"
}

MT HTTP request body data parameters detailed descriptions is provided in section Send MT.

49
7.2.2. USSD/menu

USSD/menu operation intends bidirectional interactive interaction between subscriber and

Content Provider in the mode of sending messages. Subscriber can initiate USSD/menu operation by
sending USSD message, which requires response, to Content Provider in order to receive
informational service. Content Provider responses to such message. If necessary, several message
exchange can be performed. In current document is used term 'Unstructured Supplementary
Services Request' (USSD request, USSR message, USSR) to define message which requires
response. Within USSD/menu interaction, final message indicates interaction termination and
requires no response. Other words, final message is expected to be a USSN message.

USSD/menu interaction flow description

Generally USSD/menu interaction is initiated by subscriber in order to receive informational
service. Although it is also possible that USSD/menu interaction may be initiated by Content
Provider.

USSD/menu interaction initiated by subscriber is performed as follows:

1. Subscriber sends USSR message.

2. Content Provider responses. Within responding 2 scenarios can be performed:

a. Content Provider’s message requires subscriber’s response (USSR message) in order to

continue interaction. (If necessary, several message exchange can be performed.)

b. Content Provider’s message is final, terminates interaction, and requires no subscriber’s

response (USSN message).

For deeper detailing of USSD/menu operation initiated by subscriber following examples flow may
be considered.

USSD/menu interaction flow example

USSR message can be defined by using following parameters:

"bearerType": "ussd"
"contentType": "text/ussr"

1. Subscriber sends USSR message

MO USSR HTTP request body example

{
"rid": "d8549def-5d93-4e52-8b63-b282ccefa971",
"date": "1513296000000",
"source": "380670000001",
"destination": "101999",
"bearerType": "ussd",
"contentType": "text/ussr",
"content": "666"
}

50
2. Content Provider responses

2.a. Content Provider’s message requires subscriber’s response in order to continue interaction.

MT USSR HTTP request body example

{
"rid": "d8549def-5d93-4e52-8b63-b282ccefa971",
"source": "101999",
"destination": "380670000001",
"bearerType": "ussd",
"contentType": "text/ussr",
"content": "To know World enddate enter *13666#"
}

2.b. Content Provider’s message is final, terminates interaction, and requires no subscriber’s
response.

Final message requires no response and indicates interaction termination. Other words, final
message is expected to be a USSN message. Subscriber cannot answer on USSN message. Detailed
description of USSN message is provided in section USSD/push.

MT/MO HTTP request body data parameters detailed descriptions are provided in sections:

• Send MT

• Receive MO

51
7.3. Viber message
Viber message - an instant text or media message sent to subscriber via Viber software.

CPA System enables Content Providers to provide informational services to subscribers via Viber
applications.

The ability to provide informational services to subscribers via Viber is implemented as a standard
flow for MT message processing. This means that Content Provider sends MT message with a
specific set of parameters, which determine that the message should be sent via Viber. General MT
message processing flow remains the same and is detailed in the section Mobile terminated
message. The changes relate only to the parameters of the MT message. Detailed information on
viber message types with corresponding syntax are provided in next sections.

CPA System provides an opportunity to send following viber message types:

• text:

• template

• promotion

• media:

• image

• text + image + button

Moreover, CPA System provides an opportunity to transfer within a viber message a special
additional information, that can be used on Content Provider’s side for any internal business logic,
for instance reports, statistics etc.

Following additional information can be transferred:

• a specific label - to indicate whether viber message contains a service text or promotion
information (either advertising text, or media)

• a specific mark - to indicate any kind of valuable for Content Provider information.

In order to provide media content and additional information should be used a parameter
contentExtended, represented as an object, to place following nested parameters:

• label - type of content in a viber message;

• tag - a specific mark to indicate any kind of valuable for Content Provider information;

• txt - text;

• img - a web based link to the image;

• caption - a textual writing on the button;

• action - link to a necessary resource, redirection to which is executed within button pressing.

52
Object example

{
...// other request parameters
"contentExtended":
{
"label": "promotion",
"tag": "bb8",
"txt": "Hello World!",
"img": "https://i.redd.it/o7brzj18bcs21.jpg",
"caption": "Click to follow Star Wars",
"action": "https://www.starwars.com"
},
...// other request parameters
}

Table 8. Object with nested parameters detailed description

# Object Parameter Type Description Ref

1 contentExtended - object object with optional contentExtended

parameters for viber
message

2 label string type of content in a label

viber message

3 tag string a specific mark to tag

indicate a valuable for
Content Provider
information

4 txt string text txt

5 img string a web based link to the img

image

6 caption string a textual writing on the caption & action

button

7 action string link to a necessary caption & action

resource

Detailed description of viber message types with corresponding syntax is provided in next sections.

53
7.3.1. Viber/text

Viber text message - a text message, represented by standard ASCII characters, including numbers,
symbols, and spaces.

CPA System provides an opportunity to use following text message types:

1. template

2. promotion

Detailed description is provided in next sections.

Template

Template text message - a service text message, represented by standard ASCII characters,
including numbers, symbols, and spaces, with a predefined text structure which strictly
adheres a template.

Templates usage requires preliminary manual interaction between Content

Provider and a manager responsible for providing and supporting service from
KS side, to upload/approve templates. Templates upload/approval processes are
 outside the scope of this document. More detailed description and explanation on
templates may be requested from a responsible manager. A current document
provides only high-level template overview and is focused on REST API syntax
description.

 Template text message imposes restrictions on sent content.

Content restrictions
Templates may be used for following service messaging:

• order/delivery conformation

• order/delivery status

• registration conformation

• booking status

• reminder of upcoming visit

Templates cannot be used for following messaging:

• advertisement/promotion

• any additional information that promotes a provided service (info on new arrivals, discounts,
special offers)

• offer to make a purchase, order a service

• holidays congratulations

• offer to rate a provided service

54
Template example
Template - a text with parameters, which are specified through regular expressions (RegEx).

Hello \S+ Your order number is \S+

\S+ - one or more non-whitespace characters

Content example

{
"content": "Hello Darth! Your order number is 999666"
}

Template mismatch
In case if sent template message did not match any available Content Providers templates, CPA
System does not reject the message, but proceeds it as promotion.

Intermediate delivery status

In case if sent template message did not match any available Content Providers templates, CPA
System informs Content Provider on mismatch by sending additional intermediate Delivery report
with status accepted_unmatched. As soon as message delivered to the destination successfully,
accepted_unmatched status is being updated to delivered, and CPA System informs Content Provider
by sending Delivery report with status delivered.

Syntax notation
Within interaction between CPA System and Content Provider template text message can be sent
in two ways:

• message without additional information; no need to use contentExtended

• message with additional information; required to use contentExtended

Message without additional information can be defined by using following parameters:

"bearerType": "viber"
"contentType": "text/template"

• content represented as text should be placed to a parameter content

55
Message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "text/template",
"content": "Hello Darth! Your order number is 999666",
"callbackNum": "KS_123456"
}

Message with additional information can be defined by using following parameters:

• general parameters to indicate that MT message should be sent as a template text message

"bearerType": "viber"
"contentType": "text/template"

• parameter contentExtended, represented as an object, to set following nested parameters:

• label - to set type of content in a viber message;

• tag - to set a specific mark;

• txt - to set content represented as text

"contentExtended": {
"label": "transaction",
"tag": "tag",
"txt": "Hello Darth! Your order number is 999666"
}

Message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "text/template",
"contentExtended":
{
"label": "transaction",
"tag": "tag",
"txt": "Hello Darth! Your order number is 999666"
},
"callbackNum": "KS_123456",
"ttl": 7200
}

56
Promo

Promo text message - a text message, represented by standard ASCII characters, including
numbers, symbols, and spaces, which contains promotion content.

A promotion text message is opposite to a template message, and is used to provide any
information that directly or indirectly promotes or advertises service/business. Promotion text
messages requires no preliminary manual interactions and are available out of the box.

 Promo text message imposes no restrictions on sent content.

Syntax notation
Within interaction between CPA System and Content Provider promo text message can be sent in
two ways:

• message without additional information; no need to use contentExtended

• message with additional information; required to use contentExtended

Message without additional information can be defined by using following parameters:

"bearerType": "viber"
"contentType": "text/plain"

• content represented as text should be placed to a parameter content

Message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "text/plain",
"content": "Hello World!",
"callbackNum": "KS_123456"
}

57
Message with additional information can be defined by using following parameters:

• general parameters to indicate that MT message should be sent as a promo text message

"bearerType": "viber"
"contentType": "text/plain"

• parameter contentExtended, represented as an object, to set following nested parameters:

• label - to set type of content in a viber message;

• tag - to set a specific mark;

• txt - to set content represented as text

"contentExtended": {
"label": "promotion",
"tag": "tag",
"txt": "Hello World!"
}

Message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "text/plain",
"contentExtended":
{
"label": "promotion",
"tag": "tag",
"txt": "Hello World!"
},
"callbackNum": "KS_123456",
"ttl": 7200
}

58
7.3.2. Viber/media

Viber media message - a complex media message, that can contain one of the following set of
content: either a single image or text combined with image and button.

Media content special aspects

Button
By button should be meant an item with a caption and with a link to a necessary resource,
redirection to which is executed within button pressing.

Image
By image should be meant a web based link to the image, but not an uploaded image itself. Other
words viber media message represented by an image on a subscriber’s device, is transmitted as
a web based link to the image from Content Provider’s side.

 Content Providers are expected not to share images that are offensive in any way.

Content Provider should take into consideration that Viber presents image as a
thumbnail in the resolution of 400x400 pixels. Therefore, if an image has lower
 resolution, then it is going to be stretched, and can loose quality on subscriber’s
device.

Media content and additional information should be set to a parameter contentExtended.

59
Image

Current section provides syntax for a viber media message that contains image.
Viber image message - a media message, transmitted as a web based link to the image from
Content Provider’s side, but represented by an image on a subscriber’s device.

Within interaction between CPA System and Content Provider viber image message can be defined
by using following parameters:

• general parameters to indicate that MT message should be sent as a viber image message

"bearerType": "viber"
"contentType": "image/plain"

• parameter contentExtended, represented as an object, to set following nested parameters:

• label - to set type of content in a viber message;

• tag - to set a specific mark;

• img - to set a web based link to the image

"contentExtended": {
"label": "promotion",
"tag": "tag",
"img": "https://i.redd.it/o7brzj18bcs21.jpg"
}

Content Provider can send viber image message as provided in a following example.

Viber image message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "image/plain",
"contentExtended":
{
"label": "promotion",
"tag": "bb8",
"img": "https://i.redd.it/o7brzj18bcs21.jpg"
},
"callbackNum": "KS_123456",
"ttl": 7200
}

60
Text-image-button

Current section provides syntax for a complex viber media message that contains text, image and
button.

Within interaction between CPA System and Content Provider viber media message can be
defined by using following parameters:

• general parameters to indicate that MT message should be sent as a viber media message

"bearerType": "viber"
"contentType": "text/img/button"

• parameter contentExtended, represented as an object, to set following nested parameters:

• label - to set type of content in a viber message;

• tag - to set a specific mark;

• txt - to set content represented as text;

• img - to set a web based link to the image;

• caption - to set a textual writing on the button;

• action - to set link to a necessary resource, redirection to which is executed within button
pressing.

"contentExtended": {
"label": "promotion",
"tag": "tag",
"txt": "Hello World!",
"img": "https://i.redd.it/o7brzj18bcs21.jpg",
"caption": "Click to follow Star Wars",
"action": "https://www.starwars.com"
}

Content Provider can send viber media message as provided in a following example.

61
Viber media message example

{
"source": "16034",
"destination": "380670000001",
"bearerType": "viber",
"contentType": "text/img/button",
"contentExtended":
{
"label": "promotion",
"tag": "bb8",
"txt": "Hello World!",
"img": "https://i.redd.it/o7brzj18bcs21.jpg",
"caption": "Click to follow Star Wars",
"action": "https://www.starwars.com"
},
"callbackNum": "KS_123456",
"ttl": 7200
}

Viber media message example on a subscriber’s device

Above-mentioned request example takes a provided representation on a subscriber’s device.

62
Chapter 8. General
8.1. Encoding
CPA System processes different character encoding types for content that is being transferred from
subscriber to Content Provider and vice verse. Encoding type depends on message type and
provided content, and is detailed in following sections. Definite parameters' values that define data
encoding scheme are provided in section Data encoding scheme.

8.1.1. Encoding for text/plain content type

DLR, MO messages

CPA System accepts from External content delivery system DLR and MO messages encoded to:

• '7-bit default alphabet' (SMSCDefaultAlphabet);

• UCS2(ISO/IEC-10646).

CPA System sends to Content Provider DLR and MO messages encoded to:

• UTF-8.

MT message

CPA System encodes MT message, depending on characters proceed in parameter content:

• if content contains characters which belong only to the basic set of '7-bit default alphabet'
(SMSCDefaultAlphabet), then message is encoded to 7-bit default alphabet; using this encoding,
it is possible to send up to 160 characters in one sms message;
generally, indicated encoding is applied to plain text message in latin without emoji;

• if content contains at least one character out of '7-bit default alphabet', then message is encoded
to UCS2(ISO/IEC-10646); using this encoding, it is possible to send up to 70 characters in one sms
message;
generally, indicated encoding is applied to plain text message in cyrillic, or with emoji.

Basic character set for '7-bit default alphabet' can be found on Wikipedia.

8.1.2. Encoding for smpp/binary content type

MO message

CPA System accepts from External content delivery system MO message encoded to:

• Octet unspecified (8-bit binary);

• Octet unspecified (8-bit binary) ALL TECHNOLOGIES;

• Class 0 (Flash message);

• Class 1 (ME-specific);

63
 • Class 2 (SIM/USIM-specific);

• Class 3 (TE-specific);

• Class 0 (Flash message); bit 3 is reserved;

• Class 1 (ME-specific); bit 3 is reserved;

• Class 2 (SIM/USIM-specific); bit 3 is reserved;

• Class 3 (TE-specific); bit 3 is reserved.

CPA System forwards to Content Provider MO message encoded using base64.

MT message

CPA System accepts from Content Provider MT message encoded using base64.

8.1.3. Data encoding scheme

Current section provides definite parameters values of data encoding scheme in accordance with:

• Short Message Peer to Peer Protocol Specification v3.4;

• 3GPP TS 23.038 version 15.0.0.

Bits [76543210] Hexadecimal value Meaning

text/plain

00000000 0x00 SMSCDefaultAlphabet

00001000 0x08 UCS2(ISO/IEC-10646)

smpp/binary

00000010 0x02 Octet unspecified (8-bit binary)

00000100 0x04 Octet unspecified (8-bit binary) ALL

TECHNOLOGIES

11110100 0xf4 Class 0 (Flash message)

11110101 0xf5 Class 1 (ME-specific)

11110110 0xf6 Class 2 (SIM/USIM-specific)

11110111 0xf7 Class 3 (TE-specific)

11111100 0xfc Class 0 (Flash message); bit 3 is reserved

11111101 0xfd Class 1 (ME-specific); bit 3 is reserved

11111110 0xfe Class 2 (SIM/USIM-specific); bit 3 is reserved

11111111 0xff Class 3 (TE-specific); bit 3 is reserved

64
8.2. HTTP verbs
Content Provider Access System tries to adhere as closely as possible to standard HTTP and REST
conventions in its use of HTTP verbs.

Verb Usage

GET Used to retrieve data from a specified resource. The data requested from
the server with GET can be in JSON format

POST POST is used to send data to a server to create a resource. The data sent to
the server with POST can be in JSON or XML formats

8.3. HTTP status codes

Content Provider Access System tries to adhere as closely as possible to standard HTTP and REST
conventions in its use of HTTP status codes.

Status code Usage

200 OK Standard response for successful HTTP requests. The actual response will
depend on the request method used. In a GET request, the response will
contain an entity corresponding to the requested resource. In a POST
request, the response will contain an entity describing or containing the
result of the action.

202 Accepted The request has been accepted for processing, but the processing has not
been completed. The request might or might not be eventually acted
upon, and may be disallowed when processing occurs.

400 Bad Request The server cannot or will not process the request due to something that is
perceived to be a client error (e.g., malformed request syntax, invalid
request message framing, or deceptive request routing).

401 Unauthorized Is used when authentication is required and has failed or has not yet
been provided.

403 Forbidden The request was valid, but the server is refusing action. The user might
not have the necessary permissions for a resource, or may need an
account of some sort.

404 Not Found The requested resource could not be found but may be available again in
the future. Subsequent requests by the client are permissible.

500 Internal Error The server encountered an unexpected condition which prevented it
from fulfilling the request.

502 Bad Gateway The server was acting as a gateway or proxy and received an invalid
response from the upstream server.

65
8.4. Connection properties
It is recommended to consider following characteristics for interaction with CPA System:

simultaneous http connections

recommended max quantity of simultaneous http connections from one Content Provider = 50

wait time for acceptance response

expected wait time for acceptance response from Content Provider for MO/DLR (sent from CPA
System to Content Provider) = 1 sec

8.5. Integration FAQ

time lag between MO and requested MT
it is recommended to Content Providers, which send requested MT, to adhere a time delay
between accepting MO and sending a requested MT as a response for this particular MO

recommended time delay = 40 ms

time delay is recommended due to the operation aspects of distributed service networking; in
case, if Content Provider receives http status 400 as a response for a requested MT, it is
recommended to redeliver a requested MT

8.6. Error information

8.6.1. Dictionary

Error dictionary contains description of all errors. Can be developed and supplemented.

ID Text Description

1000 Configuration error. Contact system Configuration error. Contact system support
support and/or manager from Kyivstar side

1007 Request not found Request not found

1014 Invalid protocol Invalid protocol

1016 Unknown bearer type Content Provider’s message contains unknown

bearerType

1018 Invalid source address Content Provider’s message contains invalid

source

1019 Invalid destination address Content Provider’s message contains invalid

destination (subscriber’s phone number)

1040 Resource not found Provided resource is invalid

66
ID Text Description

1041 Get DLR request is not allowed Get DLR request is not allowed by CPA3 System
configuration. If you need Get DLR method,
contact system support and/or manager from
Kyivstar side

1042 Destination must contain only digits Provided destination contains illegal characters

1043 Content is absent Content Provider’s message contains no content

1045 Messages not allowed from source: Provided source is restricted to send messages
source value

1051 Content have illegal characters: XXX Provided content contains illegal characters

1053 The subscriber does not have enough Subscriber’s balance is lower than tariff for the
money message that requires charging

1054 It is not Kyivstar subscriber Subscriber is not a customer of Kyivstar

1056 Message is not allowed with provided Content Provider’s message contains parameter
parameters that is not allowed with provided value

1057 Message expired Message defined by rid has already expired

1058 Unknown content type Content Provider’s message contains unknown

contentType

1059 All allowed free messages sent Request defined by rid has run out number of
free messages

1060 All allowed paid messages sent Request defined by rid has run out number of
paid messages

1061 Set callback number is not allowed It is not allowed to set callbackNum in MT
message for Content Provider

1063 Hashed destination is not allowed Provided hashed destination is not allowed

1064 Msisdn destination is not allowed Provided unhashed destination is not allowed

1065 NDC not supported Content Provider’s message contains

unsupported destination (subscriber’s phone
number)

1066 Subscriber not found Subscriber not found

1067 Provided callback number is out of Content Provider’s message contains callbackNum
allowed range that has value out of allowed range

1068 Invalid request identifier (rid) format. Content Provider’s message contains rid that
Expected uuid has invalid format. Expected uuid

1069 Invalid parameter length: parameter Content Provider’s message contains parameter
name that has value out of max allowed range

1070 Message to idle subscriber is not Message to idle subscriber is not allowed
allowed

67
ID Text Description

1071 Invalid parameter value: parameter Content Provider’s message contains parameter
name that has invalid value according to current
Specification

1073 Service type is not supported Content Provider’s message contains serviceType
that does not match to allowed values
prescribed by current Specification

1074 Content type is not supported Content Provider’s message contains contentType
that does not match to allowed values
prescribed by current Specification

1075 All allowed messages sent Limit of allowed messages is exceeded

1100 Internal CPA error Internal CPA System error

1200 Internal CPA error Internal CPA System error

1300 Internal CPA error Internal CPA System error

1400 Internal CPA error Internal CPA System error

1500 Internal CPA error Internal CPA System error

1600 Internal CPA error Internal CPA System error

1700 Internal CPA error Internal CPA System error

1901 Internal CPA error Internal CPA System error

196867 - Subscriber’s balance is lower than tariff for the

message that requires charging

68
8.6.2. Degenerate case for transmitting error 196867 via DLR

ErrorId 196867 removed from the DLR structure, and replaced with a new status
 since 19.11.2021.

CPA System has a defined structure for the Delivery report that prescribes 3 parameters:

• mid

• date

• status

However, there is a special case when CPA System transmits in the Delivery report an additional
parameter - errorId.

Example of DLR containing errorId

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"date": "1513296000000",
"status": "rejected",
"errorId": 196867
}

Provided DLR with errorId 196867 informs that MT message cannot be delivered to the subscriber
due to billing system error, most commonly due to subscriber’s low balance.

Decided to refactor mentioned case by:

• removing errorId from the DLR body

• replacing status rejected to status rejected_subscriber_billing_error

A new status - rejected_subscriber_billing_error will indicate the same as errorId 196867, that is -
content cannot be delivered to the subscriber due to billing system error, most commonly due to
subscriber’s low balance.

Example of DLR containing a new status

{
"mid": "904705f0-3c5e-4556-8339-81b7fd2e3d83",
"date": "1513296000000",
"status": "rejected_subscriber_billing_error"
}

69
8.6.3. Validations

CPA System applies 2-level validation to inbound MT message processing.

First-level validation
On first-level validation CPA System processes following:

1. parameters validations applicable to all message types (bearerTypes/contentTypes)

following parameters are checked:

• source
• allowed lengths for parameters: serviceType, rid, source, bearerType, contentType

• destination
• hashed destination encoding

• ttl

All indicated checks are performed in a parallel, what leads to the following: if MT message
contains more than one invalid parameter among above-indicated, then error provided in response
can relate to any of them.

Example
MT message contains 3 invalid parameters:

• source - empty string

• destination - invalid value length

• serviceType - invalid value length

{
"source": "",
"destination": "38067233076",
"serviceType": "falseeeeeeeeeeee",
"content": "test"
}

Processing of provided MT can be failed either with error 1018 'Invalid source address', or with
error 1069 'Invalid parameter length: %parameter%' for destination or serviceType.

2. target validation of bearerType

CPA System checks that provided bearerType belongs to the allowed values, predefined by this
Specification.

Second-level validation
On second-level validation CPA System processes all necessary checks for each contentType within a
valid bearerType.

70
8.7. Emoji
CPA System provides an opportunity to transfer content that contains emoji.

Emoji - ideograms and smileys used in messages. Emoji exist in various genres, including facial
expressions, common objects, types of weather, animals, etc. They are much like emoticons, but
emoji are actual pictures instead of typographics.

Content Provider should take into consideration that display of emoji is impacted
by operating system and its version. Emoji are displayed in a different way on the
 different OS, and the newer is OS version, the greater is percentage of correctly
displayed emoji.

8.7.1. Emoji in sms-traffic

In order to set an emoji to the sms/plain, it should be encoded to utf-16 escape sequence prepended
with \u in a big endian byte order, and should be placed to the content within other text.

Table 9. Emoji examples

# Emoji Name Escaped unicode

1 grinning \ud83d\ude00

2 laughing \ud83d\ude06

3 joy \ud83d\ude02

4 wink \ud83d\ude09

5 kissing heart \ud83d\ude18

6 vomiting \ud83e\udd2e

7 sneezing \ud83e\udd27

8 fear \ud83d\ude31

9 unicorn \ud83e\udd84

10 deciduous tree \ud83c\udf33

11 mushroom \ud83c\udf44

12 tumbler glass \ud83e\udd43

13 flag of Ukraine \ud83c\uddfa\ud83c\udde6

Full list of encoded emoji can be found on GitHub .

71
Emoji length for sms-traffic

If Content Provider sets (\ud83d\ude00) in a content, then emoji is encoded as a pair of 16-bit
characters in utf-16, and thus is counted as 2 16-bit characters toward a string length.

Example
"content": "Hello \ud83d\ude00"

Quantity of characters provided in a string equals 8.

8.7.2. Emoji & text formatting in viber-traffic

Emoji

In order to set an emoji to the viber message, it can be encoded in 2 ways:

• utf-16 escape sequence prepended with \u in a big endian byte order (the same as for sms/plain)

• viber original emoji encoding

Table 10. Viber original emoji examples

# Emoji Name Syntax

1 smiley (smiley)

2 laugh (laugh)

3 happy (happy)

4 wink (wink)

5 inlove (inlove)

6 sick (sick)

7 angry (angry)

8 dead (dead)

9 spiderman (spiderman)

10 snowman (snowman)

11 cupcake (cupcake)

12 wine (wine)

13 rocket (rocket)

Full list of viber original emoji can be found on GitHub .

72
Text formatting

CPA System provides an opportunity to use text formatting for content transferred via Viber.

Text formatting can be applied by adding specific markdowns to any text string using the following
markdown guidelines.

Table 11. Markdown guidelines

# Format Markdown description Markdown example Display of formatted

string in a message

1 bold One asterisk at each end of *This text will be bold* This text will be bold
the formatted string: *

2 italics One underscore at each end _This text will be in This text will be in
of the formatted string: _ italics_ italics

3 monospace Three backticks at each end ```This text will be in This text will be in
of the formatted string: ``` monospace``` monospace

4 strikethrough One tilde at each end of the ~This text will have a This text will have a
formatted string: ~ strikethrough~ strikethrough

Text formatting for viber messsage on a subscriber’s device

73
Notes on markdown proper usage
use space after the last markdown symbol and before the next word
there must be a space after the last markdown symbol and before the next word for the
formatting to work

*hello*world will be displayed as *hello*world

*hello* world will be displayed as hello world

_hello_world will be displayed as _hello_world

_hello_ world will be displayed as hello world

no space after first markdown symbol or before last markdown symbol

there must be no space after first markdown symbol or before last markdown symbol for the
formatting to work

* hello world* will be displayed as * hello world*

*hello world * will be displayed as *hello world *

*hello world* will be displayed as hello world

Compatibility
Only subscribers with Viber applications version 14.6 and above are able to see formatting in
messages; subscribers with older versions see the markdowns symbols instead.

Limitations
Formatted text is not available to use in templates. Requests for templates with markdowns will not
be approved.

Emoji and markdowns length for viber-traffic

If Content Provider sets (smiley) or uses any markdown symbols in a content, then each emoji
symbol and each markdown symbol is counted as a separate character toward a string length.

Example
"content": "Hello *world* (rocket)"

Quantity of characters provided in a string equals 22.

The overall character count of viber promo message should be 1000 characters,
 or less, including emoji codes and markdowns symbols

74
8.8. Glossary
A glossary defines key terms and abbreviations relevant to Content Provider Access System for the
purpose of current document.

Content Provider Access System (CPA System; CPA)

a system that enables interaction between subscriber and Content Provider for informational
services transferring.

Content Provider (Provider, CP)

a system that provides informational services to subscriber.

Delivery Report (DLR)

message to Content Provider to inform whether content was delivered to subscriber.

External Content Delivery System

an external system that directly sends/receives informational services to/from subscriber (e.g.,
Short Message Service Centre)

External Short Message Entity (ESME)

an external system that connects to a Short Message Service Center (SMSC) to engage in the
sending and/or receiving of short messages.

Informational Services (content)

a specific sort of information provided by Content Provider.

Short Message (SMS message; SM)

a brief text message sent to/from subscriber through the Short Message Service (SMS).

Short Message Service (SMS)

a text messaging service that uses standardized communication protocols to enable mobile
devices to exchange short text messages via a Short Message Service Centre.

Short Message Service Centre (SMS Centre; SMSC)

a system that provides relaying and store-and-forwarding of a short message.

Unstructured Supplementary Service Data (USSD)

a communication protocol used by GSM cellular telephones to communicate with the mobile
network operator’s computers.

Unstructured Supplementary Service Data Message (USSD message)

a code that consist of digits and special signs sent to/from subscriber through the Unstructured
Supplementary Service Data protocol.

75
Message Identifier (mid)
a string used to identify a particular Mobile terminated content response.
Message identifiers are used by CPA System and Content Provider in all messages concerning a
particular Mobile terminated content response.

Mobile Originated Content Request (MO request; MO message; MO; content request)
message from subscriber to order informational services from Content Provider.

Mobile Terminated Content Response (MT response; MT message; MT; content response)
a message from Content Provider sent to CPA System to provide informational services (content)
to the subscriber.

Request Identifier (subscriber’s request identifier, rid)

a string used to identify a particular Mobile originated content request.
Request identifiers are used by CPA System and Content Provider in all messages concerning a
particular Mobile originated content request and requested Mobile terminated content
response.

Requested Mobile Terminated Content Response (requested MT response; requested MT

message; requested MT)
message from Content Provider in order to provide informational services to subscriber that
were preliminary ordered.

76
Appendix A: Multi-channeling
Purpose and Scope
The current appendix describes a new service provided by CPA System - multi-channeling.

The following is included:

• service description

• new message types descriptions

• processing flows

• syntax with examples

Support and development

The service is currently being actively developed and iteratively deployed to the stage environment.
Consequently, a deployed service has limited functions until the moment of full launch.

A full-featured service launch is scheduled for the end of this year (December of 2021).

77
A.1. Service overview
Multi-channeling - a service that enables Content Providers to send a generalized mt message
(multi-mt) with the included set of desired delivery channels and channels priority, in order to
deliver content to the subscriber via the most priority channel, and redeliver content via the next
channel if the first one is unavailable or expired.

Multi-channeling allows using the following delivery channels:

• sms

• viber

Above-mentioned delivery channels completely correspond to the message types (bearerTypes)

which can be sent via CPA System REST API.

78
A.1.1. Multi-mt message

Description

Multi-mt message - a message with an extended structure, that allows enclosing 2 messages for
different delivery channels and channels priority; multi-mt message is designed to be split into 2
different regular MT messages.

Multi-mt message allows including the following message types (bearerTypes) with their
corresponding content types (contentTypes):

• sms

• text/plain

• viber

• text/plain

• text/template

• image/plain

• text/img/button

The multi-mt message has the following features:

• encloses messages designed for the following delivery channels: sms, viber

• enclosed messages must have different types: one - sms, another - viber

• encloses priority

Based on the above mentioned features, multi-mt can enclose the following message combinations:

• sms (text/plain) + viber (text/plain) proceed to example

• sms (text/plain) + viber (text/template) proceed to example

• sms (text/plain) + viber (image/plain) proceed to example

• sms (text/plain) + viber (text/img/button) proceed to example

79
Processing flow

Multi-mt message processing flow is depicted by the following sequence diagram.

Figure 7. Sequence diagram for multi-mt processing

Sequence diagram assumptions

For the sequence diagram, the following is assumed:

• multi-mt message priority set as follows: the first delivery channel - sms, the second one - viber

• delivery via the sms-channel failed due to ttl expiration, delivery via the viber-channel succeed

• message storing process omitted to avoid the diagram overhead

80
Sequence diagram description
To transmit content from Content Provider to the subscriber, the below-mentioned interactions are
performed.

1. Content Provider sends multi-mt message to CPA System

2. CPA System:

• accepts multi-mt message from Content Provider

• performs multi-mt message required validations

• matches multi-mt message to Content Providers configurations to define an applicable rule

• splits multi-mt message into 2 regular MT messages

• defines the first delivery channel

• converts message for the first delivery channel to a proper format according to the SMS
Center API

• provides an acceptance response to Content Provider

• sends MT message to the SMS Center

3. SMS Center:

• accepts MT message from CPA System

• performs MT message validations

• provides an acceptance response to CPA System

• tries to transmit content to the subscriber during the predefined ttl

4. CPA System:

• accepts an acceptance response from SMS Center

• observes message until its ttl expiration

5. SMS Center:

• defines that ttl expired

• provides a delivery report with status 'expired' to CPA System

6. CPA System:

• accepts a delivery report with the status 'expired'

• defines the next delivery channel

• converts message for the next delivery channel to a proper format according to the Viber
API

• sends MT message to the Viber

81
 7. Viber:

• accepts MT message from CPA System

• performs MT message validations

• provides an acceptance response to CPA System

• tries to transmit content to the subscriber during the predefined ttl

8. CPA System:

• accepts an acceptance response from the Viber

• observes message until its ttl expiration

9. Viber:

• defines that content delivered

• provides a delivery report with status 'delivered' to CPA System

10. CPA System:

• accepts a delivery report with the status 'delivered'

• generates multi-dlr and sends it to Content Provider

11. Content Provider:

• accepts multi-dlr from CPA System

• responds with HTTP code 204 (No content) to CPA System to inform on multi-dlr message
acceptance

82
A.1.2. Multi-dlr message

Description

Multi-dlr message - a complex delivery report with an extended structure that encloses:

• messages delivery reports to the External content delivery systems (or the result of
processing if sending postponed due to priority, or skipped as delivery via the first channel was
successful and redelivery via the next channel is not needed)

• messages delivery reports to the subscriber (or the result of processing if sending skipped as
delivery via the first channel was successful and redelivery via the next channel is not needed)

Quantity of delivery reports

The CPA System extracts 2 messages designed for the different delivery channels from the multi-mt
message, and tries to deliver the message via the most priority channel:

• if delivery succeeds, then CPA System skips delivery via the next channel

• if delivery failed/expired, then CPA System tries to redeliver the next message via the next
delivery channel.

As the result, there are several delivery results (or processing results if sending skipped).

The delivery results are aggregated as follows:

1. for sms delivery channel are generated:

• 1 delivery report to the SMS Center, or the result of processing if skipped

• 1 delivery report to the subscriber, or the result of processing if skipped

2. for viber delivery channel are generated:

• 1 delivery report to the Viber, or the result of processing if skipped

• several delivery reports to the subscriber, or the result of processing if skipped

Details
Multi-dlr message can contain from 1 to N delivery reports to the subscriber for viber-
traffic due to the following reasons:

• Viber provides the delivery report for every subscriber’s device (if the message was
delivered to the mobile application and the desktop application, that will result in 2
delivery reports with the status delivered)

• Viber can provide several delivery reports for one subscriber’s device: delivered as
the first one and seen as the next one

• CPA System generates an intermediate delivery report if the template message did not
match any Content Provider’s available templates (more details about template
messages are provided in the section Template)

83
Summarizing the above, the multi-dlr message contains:

1. for delivery results to the External content delivery systems

• 1 delivery report to the SMS Center

• 1 delivery report to the Viber

2. for delivery results to the subscriber

• 1 delivery report to the subscriber for sms-traffic

• from 1 to several delivery reports to the subscriber for viber-traffic

The number of delivery reports to the subscriber for viber-traffic, enclosed to

multi-dlr, is configurable on CPA System side.
If Content Provider is ready to receive all delivery reports to the subscriber
including additional ones for every device or intermediate one, then CPA System
 can apply an extended configuration.
If Content Provider is not ready to receive all delivery reports to the subscriber,
then CPA System can apply a regular configuration that enables including to
multi-dlr only one - final delivery report to the subscriber.

How to match delivery report to the External content delivery systems with the delivery
report to the subscriber for one message
The delivery report to the External content delivery system, and the delivery report to the
subscriber for the same message can be identified by the same mid parameter value.

84
Methods/ways for multi-dlr transmitting

The ways for transmitting multi-dlr are designed very close to the ways for
 transmitting a regular delivery report.

CPA System provides 2 ways for transmitting multi-dlr to Content Provider

• regular transmitting - a basic/regular way when CPA System sends multi-dlr to Content
Provider as soon as delivery via all channels completed; CPA System uses POST method to send
multi-dlr to Content Provider

• transmitting by request - an additional/optional way when Content Provider requests multi-dlr

from CPA System; Content Provider uses GET method to request multi-dlr from CPA System

The detailed syntax for both methods is provided in the following sections:

• Receive multi-dlr

• Get multi-dlr

Methods usage and restrictions

The methods usage and restrictions for multi-dlr are designed the same way as
 for a regular delivery report. More details are provided in the section Methods
usage and restrictions

85
Transmitting multi-dlr on a regular basis

A standard flow for transmitting multi-dlr to Content Provider as soon as delivery via all channels
completed is depicted by the following sequence diagram.

Figure 8. Sequence diagram for transmitting multi-dlr to Content Provider on a regular basis

Sequence diagram assumptions

For the sequence diagram, the following is assumed:

• multi-mt message priority set as follows: the first delivery channel - sms, the second one - viber

• delivery via the sms-channel failed due to ttl expiration, delivery via the viber-channel succeed

• process for transmitting MT message to SMS Center omitted to avoid the diagram overhead

86
Sequence diagram description
To transmit multi-dlr from CPA System to Content Provider, the below-mentioned interactions are
performed.

1. SMS Center:

• tries to transmit content to the subscriber during the predefined ttl

• defines that ttl expired

• provides a delivery report with status 'expired' to CPA System

2. CPA System:

• accepts a delivery report with the status 'expired'

• matches the received delivery report to the MT message

• defines the next delivery channel

• sends MT message to the Viber

3. Viber:

• accepts MT message from CPA System

• provides an acceptance response to CPA System

• tries to transmit content to the subscriber during the predefined ttl

• defines that content delivered

• provides a delivery report with status 'delivered' to CPA System

4. CPA System:

• accepts a delivery report with the status 'delivered'

• matches the received delivery report to the MT message

• generates multi-dlr

• sends multi-dlr to Content Provider

5. Content Provider:

• accepts multi-dlr from CPA System

• responds with HTTP code 204 (No content) to CPA System to inform on multi-dlr message
acceptance

6. CPA System:

• accepts HTTP status

• stores multi-dlr to the database

87
Transmitting multi-dlr by request

An additional/optional flow for transmitting multi-dlr to Content Provider initiated by Content

Provider’s request is depicted by the following sequence diagram.

Figure 9. Sequence diagram for transmitting multi-dlr to Content Provider by request

Sequence diagram description

To request multi-dlr from CPA System, the below-mentioned interactions are performed.

1. Content Provider sends a request to CPA System

2. CPA System:

• retrieves multi-dlr from database

• responds with HTTP code 200 (OK) and body containing a multi-dlr message

3. Content Provider accepts a multi-dlr message

In case if multi-dlr is not found in the database, then CPA System responds to Content Provider with
HTTP code 404 (Not Found) and the error message 'Resource not found'.

In case if access to GET DLR method is restricted, then CPA System responds to Content Provider
with HTTP code 403 (Forbidden) and the error message 'Get DLR request is not allowed'.

88
A.2. Syntax
A.2.1. Send multi-mt

Resource

http://{environment}/api/contents

Method

POST

MULTI-MT HTTP request example for the message combination:

sms (text/plain) + viber (text/img/button)

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json
{
"destination": "380670000001",
"priority" : ["sms","viber"],
"content":[
{
"source": "Kyivstar",
"bearerType": "sms",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000001",
"text": "sms text message",
"ttl": 30
},
{
"source": "16034",
"bearerType": "viber",
"contentType": "text/img/button",
"serviceType": "false",
"callbackNum": "KS_000002",
"tag": "any info",
"text": "viber text message",
"img": "http://img.png",
"caption": "caption text",
"action": "http://google.com",
"ttl": 30
}
]
}

89
Success HTTP response example

Status code: 202

{
"rid": "904705f0-3c5e-4556-81b7fd2e3d83"
}

Error HTTP response example

Status code: 400

{
"rid": "904705f0-3c5e-4556-81b7fd2e3d83",
"errorId": 2000,
"errorMsg": "Parameter not provided: `destination`"
}

 Additional multi-mt examples are provided in the section Examples.

Table 12. MULTI-MT request parameters description

# Name Type Required Description Ref

1 destination string yes subscribers MSISDN (phone destination

number)

2 priority array of strings yes channels priority priority

3 content array of objects yes enclosed messages content

Table 13. Enclosed message parameters description

# Name Type Required Description Ref

1 source string yes provider’s short number, or source

alpha name

2 bearerType string yes message type bearerType

3 contentType string yes type of content that is being sent contentType

4 serviceType string yes type of payment for the message serviceType

5 callbackNum string yes identifier used for callbackNum

billing/charging purposes

6 tag string no any valuable for provider tag

information

7 text string no content being sent, represented text

as a text

90
# Name Type Required Description Ref

8 img string no content being sent, represented img

as a web-based link to the image

9 caption string no content being sent, represented caption &

as textual writing on the button action

10 action string no content being sent, represented caption &

as a link to the necessary action
resource

11 ttl integer yes message time to live ttl

Table 14. Response parameters description

# Name Type Required Description Ref

1 rid string yes message identifier (UUID) rid

2 errorId integer no error identifier errorId

3 errorMsg string no error message errorMsg

91
A.2.2. Receive multi-dlr

Resource example

http://{environment}/api/reports

Method

POST

MULTI-DLR HTTP request example

{
"contents": [
{
"date": 1628179532080,
"mid": "6badca00-2e05-42df-b7f1-4a5642e38af8",
"state": "ACCEPTED"
},
{
"date": 1628179562228,
"mid": "d7c33333-749f-4027-a7bc-9ee66f48cad7",
"state": "ACCEPTED"
}
],
"reports": [
{
"date": 1628179562238,
"mid": "6badca00-2e05-42df-b7f1-4a5642e38af8",
"state": "EXPIRED"
},
{
"date": 1628180196644,
"mid": "d7c33333-749f-4027-a7bc-9ee66f48cad7",
"state": "DELIVERED"
}
],
"rid": "35dd7a57-75c6-4020-97a7-99beba3d9b1c"
}

Expected HTTP response example

Status code: 204

92
Table 15. MULTI-DLR parameters description

# Name Type Required Description Ref

1 contents array of objects yes array of delivery reports to the contents

External content delivery systems
(or the result of processing if
sending postponed/skipped)

2 reports array of objects yes array of delivery reports to the reports

subscriber
(or the result of processing, if
sending skipped)

3 rid string yes multi-mt message identifier rid

(UUID)

Table 16. Contents parameters description

# Name Type Required Description Ref

1 date string yes date when message sent to the date

External content delivery system

2 mid string yes identifier of the message mid

(extracted from the multi-mt
message) (UUID)

3 state string yes result of delivery to the External state

content delivery system

Table 17. Reports parameters description

# Name Type Required Description Ref

1 date string yes date when received the delivery date

report from External content
delivery system

2 mid string yes identifier of the message mid

(extracted from the multi-mt
message) (UUID)

3 state string yes result of delivery to the state

subscriber

93
A.2.3. Get multi-dlr

Resource

http://{environment}/api/reports/{rid}

Method

GET

GET MULTI-DLR HTTP request example

http://{environment}/api/reports/35dd7a57-75c6-4020-97a7-99beba3d9b1c

Success HTTP response example

Status code: 200

{
"contents": [
{
"date": 1628179532080,
"mid": "6badca00-2e05-42df-b7f1-4a5642e38af8",
"state": "ACCEPTED"
},
{
"date": 1628179562228,
"mid": "d7c33333-749f-4027-a7bc-9ee66f48cad7",
"state": "ACCEPTED"
}
],
"reports": [
{
"date": 1628179562238,
"mid": "6badca00-2e05-42df-b7f1-4a5642e38af8",
"state": "EXPIRED"
},
{
"date": 1628180196644,
"mid": "d7c33333-749f-4027-a7bc-9ee66f48cad7",
"state": "DELIVERED"
}
],
"rid": "35dd7a57-75c6-4020-97a7-99beba3d9b1c"
}

94
Error HTTP response example | MULTI-DLR not found

Status code: 404

{
"errorId": 1040,
"errorMsg": "Resource not found",
"rid": "35dd7a57-75c6-4020-97a7-99beba3d9b1c"
}

Table 18. GET MULTI-DLR HTTP request parameters description

# Name Type Required Description Ref

1 rid string yes multi-mt message identifier rid

(UUID)

Table 19. MULTI-DLR HTTP response parameters description

# Name Type Required Description Ref

1 contents array of objects yes array of delivery reports to the contents

External content delivery systems
(or the result of processing if
sending postponed/skipped)

2 reports array of objects yes array of delivery reports to the reports

subscriber
(or the result of processing, if
sending skipped)

3 rid string yes multi-mt message identifier rid

(UUID)

Table 20. Contents parameters description

# Name Type Required Description Ref

1 date string yes date when message sent to the date

External content delivery system

2 mid string yes identifier of the message mid

(extracted from the multi-mt
message) (UUID)

3 state string yes result of delivery to the External state

content delivery system

95
Table 21. Reports parameters description

# Name Type Required Description Ref

1 date string yes date when received the delivery date

report from External content
delivery system

2 mid string yes identifier of the message mid

(extracted from the multi-mt
message) (UUID)

3 state string yes result of delivery to the state

subscriber

96
A.3. Headers definition
The headers of multi-mt and multi-dlr messages repeat the headers of regular MT
 messages and Delivery reports. The detailed syntax for headers is provided in the
section Headers definition.

A.4. Parameters definition

In the current section all parameters are divided into 3 subsections:

1. common parameters - parameters used mostly for all message types (multi-mt and multi-dlr),
they include:

• parameters provided in the error responses

• multi-mt identifier - rid - used to identify multi-mt and related multi-dlr

2. multi-mt parameters - parameters used for multi-mt message

3. multi-dlr parameters - parameters used for multi-dlr message

97
A.4.1. Common parameters

rid

Definition
Multi-mt message identifier - a string used to identify a particular multi-mt message.

Features
1. Parameter format is UUID.

2. Parameter has no default value.

3. Parameter is generated by CPA System and sent back to Content Provider in the acceptance
response.

errorId

Definition
Parameter defines error identifier.

Features
1. Parameter has no default value.

2. Parameter values are provided in Error dictionary

errorMsg

Definition
Parameter defines error message.

Features
1. Parameter has no default value.

2. Parameter values are provided in Error dictionary

98
A.4.2. Multi-mt parameters

The parameters of multi-mt message are designed very close to the parameters of a regular MT
message and in most cases repeat them completely.

destination

Definition
Parameter defines subscriber’s msisdn (phone number)

Features
1. Parameter has no default value.

2. Parameter has an allowed length limited by the following range: 12-15 digits.

priority

Definition
Parameter defines channels priority - which channel should be used as the first one, and which one
as the next.

Features
1. Parameter type is array of strings

2. Strings to be set to the array can take the following values: sms, viber

3. Order of strings in the array defines the order of delivery channels

example description

"priority": ["sms","viber"] the first delivery attempt will be made via sms-channel, if it
failed, the next delivery attempt will be made via viber-channel

"priority": ["viber","sms"] the first delivery attempt will be made via viber-channel, if it
failed, the next delivery attempt will be made via sms-channel

99
content

Definition
Parameter defines an array that encloses two objects. Each object represents a stand-alone message
designed for the definite channel.

Features
1. Parameter type is array of objects

2. Enclosed object is designed very close to a regular MT message (MT message syntax provided in
section Send MT)

3. Object can contain the following nested parameters:

• source
• bearerType
• contentType
• serviceType
• callbackNum
• tag
• text
• img
• caption
• action

source

Definition
Parameter defines Content Provider’s short number, or alpha name.

Features
1. Parameter has no default value.

2. Parameter has a max allowed value length: 12 symbols.

3. Parameter value to be set has some limitations for viber-traffic. Value to be set should be equal
to an identifier issued by Viber, and should be provided by a manager.

bearerType

Definition
Parameter defines message type.

Features
1. Parameter has no default value.

2. Parameter can take one of the following values:

• sms
• viber

100
contentType

Definition
Parameter defines the type of content that is being sent.

Features
1. Parameter has no default value.

2. Parameter can take one of the following values:

• text/plain
• text/template
• image/plain
• text/img/button

A definite value depends on a message type (bearerType):

a. for bearerType: sms, contentType can be set to text/plain

b. for bearerType: viber, contentType can be set to:

• text/plain
• text/template
• image/plain
• text/img/button

serviceType

Definition
Parameter defines the type of payment for the message.

Features
1. Parameter has no default value.

callbackNum

Definition
Parameter defines Content Provider’s additional callback number or identifier used for billing,
charging purposes. Most commonly, the parameter defines Content Provider’s billing identifier.
Parameter can be used only by preliminary agreement.

Features
1. Parameter has no default value.

2. Parameter has a max allowed value length: 15 symbols.

3. Parameter is allowed to be used only by preliminary agreement with Kyivstar JSC.

4. Parameter value to be set has some limitations for viber-traffic. Value to be set should be equal
to an identifier issued by Kyivstar, and should be provided by a manager.

101
tag

Definition
Parameter defines a specific mark to indicate any kind of valuable for Content Provider
information. Can be used for reports, analytics etc. on Content Provider’s side.

Features
1. Parameter has a max allowed value length: 100 symbols.

2. Parameter can be used only for the viber message type.

3. Parameter should not be used for the sms message type.

text

Definition
Parameter defines content represented as a text.

Features
1. Parameter has no default value.

2. Parameter can be used for the following content types:

• "contentType": "text/plain"
• "contentType": "text/template"
• "contentType": "text/img/button"

3. Parameter should not be used for any other content types.

4. Parameter has a max allowed value length that depends on bearerType, contentType and
encoding.

Parameter’s length recommendations for sms message

Content on CPA System side and on SMS Center side is processed in a bit different ways.

CPA System does not split text into single parts, but it validates text according to the max
recommended length, and encodes it according to the provided characters:

• if text contains characters that belong only to the basic set of '7-bit default alphabet'
(SMSCDefaultAlphabet), then the message is encoded to '7-bit default alphabet';
for this encoding recommended length is <= 1000 characters

• if text contains at least one character out of '7-bit default alphabet', then the message is encoded
to UCS2(ISO/IEC-10646);
for this encoding recommended length is <= 499 characters

102
SMS Centre splits text into single message parts (for transport purposes), which are concatenated
into one sms message on the subscriber’s device side. A single message part length depends on
encoding:

• using '7-bit default alphabet' (SMSCDefaultAlphabet) encoding, it is possible to send up to 160

characters in a single message part

• using UCS2(ISO/IEC-10646) encoding, it is possible to send up to 70 characters in a single sms

message part

Hence, text is divided into single parts when it’s longer than 160 symbols for '7-bit default alphabet'
encoding, or longer than 70 symbols for UCS2 encoding until it is not larger than the max length.

Parameter’s length recommendations for viber message types

Parameter’s recommended length is applicable to any encoding but depends on a contentType:

• for "contentType": "text/plain" recommended length is <= 1000 characters

• for "contentType": "text/template" recommended length is <= 950 characters

img

Definition
Parameter defines a web based link to the image.

Features
1. Image recommended resolution is not less than 400x400 pixels.

2. Parameter can be used for the following viber message types:

• "contentType": "text/img/button"
• "contentType": "image/plain"

3. Parameter should not be used for any other viber message types.

caption & action

Definition
Parameters caption and action must be used together as they both represent the button:

• caption - textual writing on the button

• action - a link to a necessary resource, redirection to which is executed within button pressing

Features
1. caption max allowed value length: 30 symbols.

2. Parameters can be used for the following viber message type:

• "contentType": "text/img/button"

3. Parameter should not be used for any other viber message types.

103
ttl

Definition
The parameter defines message time to live during which CPA System performs delivery via the
related delivery channel.

If the result of the delivery attempt is unknown (CPA System did not receive a successful delivery
status from the External content delivery systems - SMS Center or Viber during the ttl), then the
message is assumed as expired and CPA System proceeds to the next delivery channel.

Parameter is also passed to the External content delivery system, where it defines message time to
live in case if it is not delivered to the subscriber from the first time.

Features
1. Parameter value should be set in seconds.

2. Parameter has an allowed range limited by the following min-max values: 30-600 seconds.

104
A.4.3. Multi-dlr parameters

contents

Definition
The parameter defines an array that encloses 2 objects.

Each object represents either a message delivery report to the External content delivery system,
or the result of processing if sending is postponed due to priority or skipped as delivery via the first
channel was successful and redelivery via the next channel is not needed.
Under message is meant a separate MT message extracted from the multi-mt message.

Features
1. Parameter type is array of objects

2. Enclosed object is designed very close to a regular delivery report (DLR message syntax
provided in section Receive DLR)

3. Object contains the following nested parameters:

• date
• mid
• state

date

Definition
The parameter defines either time and date when the message was sent to the External content
delivery system, or defines time and date, when the message processing was completed without
sending to the External content delivery system (skipped) as delivery via the first channel was
successful and redelivery via the next channel is not needed.

Format
Parameter format is set as TIMESTAMP (UTC) in milliseconds.

Example

Time and date: Wednesday, January 31, 2018 12:45:15 PM

TIMESTAMP (UTC) in ms: 1517402715000

Features
1. Parameter has no default value.

105
mid

Definition
Message identifier - a string used to identify a separate message extracted from the multi-mt
message.

Format
UUID.

Features
1. Parameter has no default value.

2. Parameter mid enclosed to contents always equals to the mid enclosed to reports for the same
message to identify delivery status to the External content delivery system and delivery
status to the subscriber for the message.

state

Definition
The parameter defines either the result of delivery the message to the External content delivery
system or defines the result of processing if the message was skipped as delivery via the first
channel was successful and redelivery via the next channel is not needed.

Features
1. Parameter has no default value.

2. Parameter can take one of the following values:

• ACCEPTED - the message was accepted on the External content delivery system side; delivery
attempts to the subscriber will be made

• SKIP_PROCESS - the message processing was skipped as delivery via another channel was
performed successfully and redelivery is not needed

• WAIT - intermediate status - the message processing is not started yet as delivery via another
channel is being performed and the result from another channel is not received yet
(message awaits processing)

• REJECTED - the message was rejected on the External content delivery system side due to an
internal business logic; no delivery attempts to the subscriber will be made

• UNDELIVERABLE - the message was not sent to the External content delivery system due to an
internal system error; no delivery attempts to the subscriber will be made

106
reports

Definition
The parameter defines an array that encloses several objects.

Each object represents either a message delivery report to the subscriber, or the result of
processing if sending skipped as delivery via the first channel was successful and redelivery via the
next channel is not needed. Under message is meant a separate MT message extracted from the
multi-mt message.

Features
1. Parameter type is array of objects

2. Enclosed object is designed very close to a regular delivery report (DLR message syntax
provided in section Receive DLR)

3. Object contains the following nested parameters:

• date
• mid
• state

date

Definition
The parameter defines either time and date when the message was sent to the subscriber, or
defines time and date, when the message processing was completed without sending (skipped) as
delivery via the first channel was successful and redelivery via the next channel is not needed.

Format
Parameter format is set as TIMESTAMP (UTC) in milliseconds.

Example

Time and date: Wednesday, January 31, 2018 12:45:15 PM

TIMESTAMP (UTC) in ms: 1517402715000

Features
1. Parameter has no default value.

107
mid

Definition
Message identifier - a string used to identify a separate message extracted from the multi-mt
message.

Format
UUID.

Features
1. Parameter has no default value.

2. Parameter mid enclosed to reports always equals to the mid enclosed to contents for the same
message to identify delivery status to the External content delivery system and delivery
status to the subscriber for the message.

state

Definition
The parameter defines either the result of delivery the message to the subscriber or defines the
result of processing if the message was skipped as delivery via the first channel was successful and
redelivery via the next channel is not needed.

Features
1. Parameter has no default value.

2. Parameter’s values vary depending on the External content delivery system (channel) via which
the message is being delivered to the subscriber (SMS Centre, Viber).

3. Parameter can take one of the following values:

for all channels

• SKIP_PROCESS
• the delivery process was skipped as delivery via another channel was performed
successfully and redelivery is not needed

• the delivery process was skipped as the message sending process failed (the External
content delivery system rejected the message)

sms-traffic
• DELIVERED - message is delivered to the destination successfully

• EXPIRED - message is not delivered to the destination due to the time to live expiration

• REJECTED - message was rejected on SMS Centre side due to internal business logic; no delivery
attempts were made

• REJECTED_SPAM - message was rejected on SMS Centre side as provided content is recognized as
spam; no delivery attempts were made

108
 • UNDELIVERABLE - message has encountered a delivery error and is deemed permanently
undeliverable; no further delivery attempts will be made; certain network or SMS Centre
internal errors result in the permanent non-delivery of a message; examples of such errors can
be: an unknown subscriber, or network error that indicates that the given destination mobile
could not support SMS, or service of receiving SMS is disabled

viber-traffic
• ACCEPTED_UNMATCHED - message has been accepted on Viber side and delivery attempts will be
made, but sent template message did not match any Content Provider’s available templates;
additional intermediate status applicable only to template messages
(as soon as the message is delivered to the destination successfully, accepted_unmatched status is
being updated to delivered)

• BLACKLIST - message was rejected on Viber side due to subscriber reason, more specifically,
because the subscriber unsubscribed from the specific sender or from receiving viber business
messages completely

• DECLINED - message was rejected on Viber side due to subscriber reason, more specifically,
because the subscriber is not registered on viber; has no viber application

• DELIVERED - message is delivered to the destination successfully

(as soon as subscriber opens a message, DELIVERED status is being updated to SEEN; but if the
subscriber never opened a message, and the message time to live expired, then DELIVERED status
is being updated to EXPIRED)

• EXPIRED - message is not delivered to the destination due to the time to live expiration

• REJECTED - message was rejected on Viber side due to internal business logic, e.g. invalid request
syntax, invalid client configuration, billing errors, timeout; no delivery attempts were made

• SEEN - subscriber opened Viber application and entered the conversation with the specific
message

109
A.5. Examples
A.5.1. sms (text/plain) + viber (text/plain)

MULTI-MT example for the message combination: sms (text/plain) + viber (text/plain)

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"destination": "380672330769",
"priority" : ["sms","viber"],
"content":[
{
"source": "Kyivstar",
"bearerType": "sms",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "sms text message",
"ttl": 30
},
{
"source": "16034",
"bearerType": "viber",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "viber text message",
"ttl": 30
}
]
}

110
A.5.2. sms (text/plain) + viber (text/template)

MULTI-MT example for the message combination: sms (text/plain) + viber (text/template)

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"destination": "380672330769",
"priority" : ["sms","viber"],
"content":[
{
"source": "Kyivstar",
"bearerType": "sms",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "sms text message",
"ttl": 30
},
{
"source": "16034",
"bearerType": "viber",
"contentType": "text/template",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "viber template message",
"ttl": 30
}
]
}

111
A.5.3. sms (text/plain) + viber (image/plain)

MULTI-MT example for the message combination: sms (text/plain) + viber (image/plain)

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"destination": "380672330769",
"priority" : ["sms","viber"],
"content":[
{
"source": "Kyivstar",
"bearerType": "sms",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "sms text message",
"ttl": 30
},
{
"source": "16034",
"bearerType": "viber",
"contentType": "image/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"img": "http://img.png",
"ttl": 30
}
]
}

112
A.5.4. sms (text/plain) + viber (text/img/button)

MULTI-MT example for the message combination: sms (text/plain) + viber (text/img/button)

POST http://{environment}/api/contents

Authorization: Basic dm9yZGVsOnZvcmRlbA==

Content-Type: application/json

{
"destination": "380672330769",
"priority" : ["sms","viber"],
"content":[
{
"source": "Kyivstar",
"bearerType": "sms",
"contentType": "text/plain",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "sms text message",
"ttl": 30
},
{
"source": "16034",
"bearerType": "viber",
"contentType": "itext/img/button",
"serviceType": "false",
"callbackNum": "KS_000000",
"text": "viber text message",
"img": "http://img.png",
"caption": "caption text",
"action": "http://google.com",
"ttl": 30
}
]
}

113
A.6. Error dictionary
Error dictionary contains description of all errors. Can be developed and supplemented.

ID Text Description

1040 Resource not found Requested multi-dlr message not found

2000 Parameter not provided: parameter Content Provider’s multi-mt message is missing a
name mandatory parameter

2001 Invalid parameter length: parameter Content Provider’s multi-mt message contains a
name parameter that has value length out of the allowed
range

2002 Invalid parameter value: parameter Content Provider’s multi-mt message contains a
name parameter that has an invalid value according to
the prescribed possible values

2003 parameter name: parameter is not Content Provider’s multi-mt message contains a
allowed for provided message type parameter that is not allowed according to
(bearerType and contentType) provided message type and content type

2004 Invalid value for parameter Content Provider’s multi-mt message contains a
'destination': provided value parameter destination with a plain value, but the
provided value contains symbols except for digits.
Or, Content Provider’s multi-mt message contains
a parameter destination with a hashed value, but
the provided value contains additional symbols
except for allowed ones: 0-9a-fA-F

2005 Missing value for parameter 'source' Content Provider’s multi-mt message contains no
for priority: value mandatory parameter source or source is empty

2006 Wrong priority count: only 2 message Content Provider’s multi-mt message contains a
priorities supported parameter priority that has an unsupported
number of values

2007 Unsupported value for parameter Content Provider’s multi-mt message contains a
'priority': value parameter priority that has an invalid value
according to the prescribed possible values

2008 Wrong priority order: 'sms, viber' or Content Provider’s multi-mt message contains a
'viber, sms' are supported parameter priority that has an invalid order of
values

2009 Unknown bearer type: provided value Content Provider’s multi-mt message contains a
parameter bearerType but the provided value is
not allowed according to the prescribed possible
values

2010 Missing or unsupported value for Content Provider’s multi-mt message contains no
parameter 'bearerType' for priority: mandatory parameter bearerType, or bearerType is
value empty, or the provided value is not allowed
according to the prescribed possible values

114
ID Text Description

2012 Unsupported value for parameter Content Provider’s multi-mt message contains a
'serviceType': provided value parameter serviceType but the provided value is
not allowed according to the prescribed possible
values

2013 Missing value for parameter Content Provider’s multi-mt message contains no
'contentType' for priority: value mandatory parameter contentType

2014 Unsupported value for parameter Content Provider’s multi-mt message contains a
'contentType': provided value parameter contentType but the provided value is
empty, or not allowed according to the prescribed
possible values

2015 parameter name: parameter is Content Provider’s multi-mt message contains no

required for provided message type parameter that is required according to provided
(bearerType and contentType) message type and content type

2020 Configuration error. Contact system Configuration error. Contact system support
support and/or manager from Kyivstar side

2021 Set callback number is not allowed for Content Provider’s multi-mt message contains a
provided viber/sms message type parameter callbackNum that is not allowed
according to the provider’s configuration

2022 Provided callback number: \"provided Content Provider’s multi-mt message contains a
value\" - is out of allowed range for parameter callbackNum but the provided value is
provided viber/sms message type not allowed according to the provider’s
configuration

2100 Message is not allowed with provided Content Provider’s multi-mt message contains a
parameters parameter that is not allowed with the provided
value

2150 Provider messages pool limit reached, Content Provider’s message pool limit reached
request rejected, pool size: value

2200 Internal system error Internal CPA System error

2300 Channel returns error id: errorId, msg: Internal CPA System error
\"errorMsg\" - message rejected

115
A.7. Release notes
Available Functionality:
The full-service functionality is available.

116