Telco Messages¶
Security Considerations¶
MSISDN Hashing
In case we should carry inside xmpp message sensitive information like client’s msisdn, we should apply SHA256 and then base64 to the original string. This is an example message with a non crypted msisdn inside <thread>.
<message type="chat" to="va@onebrand" id="8F807280-C98C-4A31-A1D1-7A5DB1EC1A8C">
<body/>
<x xmlns="jabber:x:oob">
<type>chat_text</type>
<action>chat_text</action>
<payload>
{
"text": "Ciao Will",
"data": {
"paymentMethod": "Post",
"resetSession": false,
"token": "S4SH03dYinKTZKGkhh+qQ0EHP3zvBkG3KbrPbddfuDCLXlI3IEFg93klbjybj3OtCv8hbjDEsGKwcBcZK2\/yyh+XarnYflC6zq0nujOCjYA=",
"useChatDynamic": true
}
}
</payload>
</x>
<thread>3211234567</thread>
</message>
Given msisdn 3211234567, resulting SHA256 is: 3f6e634f59a6afa984cce1416b9d943a7fc946860a1a5eed3661952f1c87d2cf.
After SHA256, we finally apply a base64 to resulting value.
Given the output of: M2Y2ZTYzNGY1OWE2YWZhOTg0Y2NlMTQxNmI5ZDk0M2E3ZmM5NDY4NjBhMWE1ZWVkMzY2MTk1MmYxYzg3ZDJjZg==
This is the resulting xmpp message:
<message type="chat" to="va@onebrand" id="8F807280-C98C-4A31-A1D1-7A5DB1EC1A8C">
<body/>
<x xmlns="jabber:x:oob">
<type>chat_text</type>
<action>chat_text</action>
<payload>
{
"text": "Ciao Will",
"data": {
"paymentMethod": "Post",
"resetSession": false,
"token": "S4SH03dYinKTZKGkhh+qQ0EHP3zvBkG3KbrPbddfuDCLXlI3IEFg93klbjybj3OtCv8hbjDEsGKwcBcZK2\/yyh+XarnYflC6zq0nujOCjYA=",
"useChatDynamic": true
}
}
</payload>
</x>
<thread>M2Y2ZTYzNGY1OWE2YWZhOTg0Y2NlMTQxNmI5ZDk0M2E3ZmM5NDY4NjBhMWE1ZWVkMzY2MTk1MmYxYzg3ZDJjZg==</thread>
</message>
Common Response¶
All Telco messages have these common response params as shown below.
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_login |
Represents message server identifier |
x:payload |
json object |
Represents message content |
payload:error |
Boolean |
Error found or not |
payload:reason |
String |
Error reason |
payload:status |
Integer |
Error status |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_login</action>
<payload>
{
"error": true,
"reason": "Internal server error: wide request goes to timeout",
"status": 500
}
</payload>
</x>
</message>
Login¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_login |
Represents message server identifier |
x:payload |
json object |
Represents message content |
payload:username |
String |
Username |
payload:password |
String |
Password |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_login</action>
<payload>
{
"username": "3304578577",
"password": "mycoolpassword"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_login |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_login</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"lines": [
"329xxxxxxx",
"329yyyyyyy",
"329zzzzzzz"
]
}
</payload>
</x>
</message>
Customer¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_customer |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_customer</action>
<payload />
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_customer |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_customer</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"customerCode": "xxxxxxxxxxxxx",
"name": "FRANCESCO",
"surname": "ROMANO",
"sex": "M",
"fiscalCode": "YYYYYYYYYYYYYYYYYY",
"birth": {
"city": "NAPOLI",
"country": "ITALIA",
"cityCode": "NA",
"faxNumber": "00000000000",
"phoneNumber": "00000000000",
"date": "02/09/1978"
},
"title": "Sig.",
"email": "AAAAAAAAAAGMAIL.COM",
"vatCode": "",
"consentLaw19603": "Y",
"segment": "Consumer",
"sites": [
{
"type": "Sede Legale",
"particleSTICA": "VIA",
"address": "XXXXXXXXXXXX",
"houseNumber": "25",
"postalCode": "80129",
"place": "",
"city": "NAPOLI",
"province": "NA",
"country": "ITALIA"
}
],
"profile": "Consumer",
"contracts": [
{
"id": "numero contratto",
"expiryDate": "data cessazione",
"lines": [
"329xxxxxxx",
"329yyyyyyy",
"329zzzzzzz"
]
}
]
}
</payload>
</x>
</message>
Line Info¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_line_info |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_line_info</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_line_info |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_line_info</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"description": "line description",
"msisdn": "3495833484",
"paymentType": "payment type",
"activationDate": "date",
"expirationSimDate": "date"
"productId": "myidentifier",
"simType": "4G",
"PUK": "454458"
}
</payload>
</x>
</message>
Active Options¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_options |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_options</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_options |
Represents message server identifier |
x:payload |
json object |
Represents message content |
x:payload.title |
String |
Represents offer title |
x:payload.description |
String |
Represents offer description |
x:payload.state |
String |
Represents offer state |
x:payload.activationDate |
String object |
Represents offer date |
x:payload.bundle |
json object |
Represents Bundle object |
x:bundle.type |
String |
Represents Bundle type |
x:bundle.consumed |
Integer |
Represents consumed data |
x:bundle.total |
Integer |
Represents total data |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_options</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
},
{
"type": "mega",
"consumed": 5500,
"total": 10000
}
]
}
</payload>
</x>
</message>
Active Promotions¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_promotions |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_promotions</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_promotions |
Represents message server identifier |
x:payload |
json object |
Represents message content |
x:payload.title |
String |
Represents offer title |
x:payload.description |
String |
Represents offer description |
x:payload.state |
String |
Represents offer state |
x:payload.activationDate |
String object |
Represents offer date |
x:payload.bundle |
json object |
Represents Bundle object |
x:bundle.type |
String |
Represents Bundle type |
x:bundle.consumed |
Integer |
Represents consumed data |
x:bundle.total |
Integer |
Represents total data |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_promotions</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
}
]
}
</payload>
</x>
</message>
Active Services¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_services |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_services</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_active_services |
Represents message server identifier |
x:payload |
json object |
Represents message content |
x:payload.title |
String |
Represents offer title |
x:payload.description |
String |
Represents offer description |
x:payload.state |
String |
Represents offer state |
x:payload.activationDate |
String object |
Represents offer date |
x:payload.bundle |
json object |
Represents Bundle object |
x:bundle.type |
String |
Represents Bundle type |
x:bundle.consumed |
Integer |
Represents consumed data |
x:bundle.total |
Integer |
Represents total data |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_active_services</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
},
{
"type": "mega",
"consumed": 5500,
"total": 10000
}
]
}
</payload>
</x>
</message>
Credit¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_credit |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_credit</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_credit |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_credit</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"creditAmount": "10.00"
}
</payload>
</x>
</message>
Payment Methods¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_payment_methods |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_payment_methods</action>
<payload>
{
"customerCode": "1294941",
"contractCode": "BX19HY",
"msisdn ": "3407834889"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_payment_methods |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_payment_methods</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"paymentMethods": [
{
"cardInfo": {
"cardNumber": "4958 3483 3248 4239",
"owner": "Mario Rossi",
"expiryDate": "23/12/2024",
"securityCode": "484"
}
},
{
"cardInfo": {
"cardNumber": "4595 3483 3248 4239",
"owner": "Federico Rossi",
"expiryDate": "23/12/2022",
"securityCode": "222"
}
}
]
}
</payload>
</x>
</message>
Recharge¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_recharge |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_recharge</action>
<payload>
{
"customerCode": "1294941",
"contractCode": "BX19HY",
"msisdn ": "3407834889",
"msisdnToRecharge": "3407834889",
"amount": 30,
"label": "30 euro",
"value": 00030,
"paymentMethod": {
"type": "card|paypal|account|code",
"code": "4234829343294392",
"cardInfo": {
"cardNumber": "4958 3483 3248 4239",
"owner": "Mario Rossi",
"expiryDate": "23/12/2024",
"securityCode": "484"
}
}
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_recharge |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_recharge</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"transactionID ": "k323ejd2nxo3ic3n",
"rechargedAmount": 30,
"value": 00010,
"label": "30 euro"
}
</payload>
</x>
</message>
Auto Recharge¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_auto_recharge |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_auto_recharge</action>
<payload>
{
"customerCode": "1294941",
"contractCode": "BX19HY",
"msisdn ": "3407834889",
"label": "al rinnovo dell’offerta",
"value": 00030,
"paymentMethod": {
"type": "card|paypal|account|code",
"code": "4234829343294392",
"cardInfo": {
"cardNumber": "4958 3483 3248 4239",
"owner": "Mario Rossi",
"expiryDate": "23/12/2024",
"securityCode": "484"
}
}
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_auto_recharge |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_auto_recharge</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"error": false
}
</payload>
</x>
</message>
Last Recharges¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_last_recharges |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_last_recharges</action>
<payload>
{
"startDate": "2018-04-26T12:00:00-07:30",
"endDate": "2018-04-26T12:00:00-07:30"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_last_recharges |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_last_recharges</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"data": [
{
"type": "ok",
"msisdn": "3341234567",
"amount": "10",
"amountBonus": "",
"rechargingDate": ""
},
{
"type": "ok",
"msisdn": "3331234567",
"amount": "20",
"amountBonus": "",
"rechargingDate": ""
}
]
}
</payload>
</x>
</message>
Dashboard¶
REQUEST
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_dashboard |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message to="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_dashboard</action>
<payload>
{
"msisdn": "3404589485"
}
</payload>
</x>
</message>
RESPONSE
Message format:
Tag |
Value |
Description |
|---|---|---|
x:type |
chat_generic |
Fixed value for the message |
x:action |
cmd_dashboard |
Represents message server identifier |
x:payload |
json object |
Represents message content |
Example:
<message from="buddy_channel@domain" id="1486028547270039399072925" type="chat">
<body />
<x xmlns="jabber:x:oob">
<type>chat_generic</type>
<action>cmd_dashboard</action>
<payload>
{
"error": false,
"reason": "",
"status": 200,
"lineInfo": {
"description": "line description",
"msisdn": "3495833484",
"paymentType": "payment type",
"activationDate": "date",
"expirationSimDate": "date",
"productId": "myidentifier",
"simType": "4G",
"PUK": "454458"
},
"activeOptions": [
{
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
},
{
"type": "mega",
"consumed": 5500,
"total": 10000
}
]
}
],
"activePromotions": [
{
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
},
{
"type": "mega",
"consumed": 5500,
"total": 10000
}
]
}
],
"activeServices": [
{
"title": "xxxxxxxxxxxxx",
"description": "yyyyyyyyyyyyy",
"state": "attivo",
"activationDate": "data",
"bundle": [
{
"type": "minutes",
"consumed": 100,
"total": 200
},
{
"type": "sms",
"consumed": 2,
"total": 2000
},
{
"type": "mega",
"consumed": 5500,
"total": 10000
}
]
}
],
"credit": {
"creditAmount": "10.00"
}
}
</payload>
</x>
</message>
