SMS Integration

While it is possible to use the moTV.eu middleware as a standalone platform, we recommend that you use with in combination with JACON CSMS. The JACON CSMS system can
be used as a billing platform and it also brings features such as sending forgotten password email, downloading EPGs from various sources, storing more than just a login of the
customer (but also phone number, address, ...).

PHP SDK
We offer a PHP SDK integration kit for the SMS API - https://github.com/motveu/php-api-sdk and also available via Composer

Integration
The CSMS has it's own Documentation section which contains the list of all supported methods, here are described just the most basic ones that are usually necessary when the
operator already has own SMS/CRM system and needs just to create customers / subscribe / cancel. For other methods or more detailed API description, please check the CSMS
documentation

Each SMS API request needs to contain Authorization header that is calculcated in same way as the MW Admin API header. The content of the header is calculated as
login:timestamp:sha1(timestamp+login+secret) . For an example, if the variables were login = [email protected], timestamp = 1544785566 and secret =
bbrkxk0k5g8oan4ytyxb50xxs2umenudyrfjvvac then the token would be equal to [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87dc . Please note that each
token expires in 10 minutes and needs to be calculated again. The token has the same rights as the user. In case there is an attempt to make a call above user's rights,
approprirate error status is returned.

CSMS API Error codes

The CSMS API returns status equal to 1 when everything was successfull. However, when there was an issue, non-success status will be returned. Below are the most usual
ones:

Code Description

0 Unknown error

1 Success

3 Unauthorized

4 Unknown module

5 Unknown method

6 Missing mandatory parameter

7 Invalid JSON received

10 Invalid parameter type

20 Unknown authorization token

100 Unknown customer

104 Customer validation error

260 Unknown product

500 Unknown subscription

14000 Duplicate motv login

14001 Incorrect username or password

For the full list of error, please check the CSMS documenatation

Login
In order to validate customer's login and receive customer's information method devices/motv/apiLogin(string login, string password) is to be used.

curl -X POST \
https://sms.operator.tv/api/devices/motv/apiLogin \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"login": "[email protected]", "password":"pwd123"}}'

In case the login credentials are correct, the CSMS returns all data about the customer including all customer's profiles.

{
"response": {
"device_motv_id": 26,
"device_motv_viewers_id": 28,
"device_motv_login": "[email protected]",
"device_motv_motv_portals_id": 1,
"device_motv_motv_id": "100105",
"device_motv_profiles_id": 100106,
"customers_id": 100105,
"customers_vendors_id": 1,
"customers_login": "[email protected]",
"customers_created": "2019-02-03T18:25:57+01:00",
"customers_users_id": 1,
"customers_token": "asasasdasdasdknnuawbejabsdjibasduibas",
"customers_profiles_id": 100106,
"customers_password_changed": 0,
"customers_device_count": 10,
"customers_recording_length": 3000,
"customers_recording_used": null,
"profiles": [
{
"profiles_id": 100106,
"profiles_customers_id": 100105,
"profiles_name": "test profile",
"profiles_image": "2019/02/03/1001/profile_100106-5c572425a848d.png",
"profiles_birthday": null,
"profiles_pin": null,
"profiles_created": "2019-02-03T18:25:57+01:00",
"profiles_protect": 0,
"profiles_xroad": 1,
"image": "https://mw.operator.tv//public/profile/image/100106/asasasdasdasdknnuawbejabsdjibasduibas/profile_100106-5c572425a848d.png"
}
]
},
"status": 1
}

From the response, the operator will most likely use fields device_motv_viewers_id (internal ID of customer in the CSMS), customers_id (internal ID of customer in the
middleware), customers_token and profiles .

Create customer
The method signature is integration/createMotvCustomer(string login, string password, string pin = null, int portals_id = null, string birthday = null, string email
= null, string phone = null, string firstname = null, string lastname = null, string note = null, array macAdresses = null) . Only login and password are requierd,
the rest is optional.

curl -X POST \
https://sms.operator.tv/api/integration/createMotvCustomer \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"login":"test", "password":"pwd", "firstname":"John", "lastname":"Wayne","email":"[email protected]", "phone":"123456789", "macAdresses": ["00:0a:

The call returns:

{
"response": 4321,
"status": 1
}

Since the status is 1 (for the full list of error codes, check the CSMS documentation), the customer was successfully created and his internal ID is 4321 . This ID should be saved
by operator's CRM / SMS system and will be used for any other communication.

Update customer
The method signature is integration/updateMotvCustomer(int viewers_id, string login = null, string password = null, string pin = null, string birthday = null, string
email = null, string phone = null, string firstname = null, string lastname = null, string note = null, array macAdresses = null . Only viewers_id is requierd, the rest
is optional. As per the previous sample, viewers_id should equal to 4321 .

curl -X POST \
https://sms.operator.tv/api/integration/updateMotvCustomer \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 4321, "password":"newPassword"}}'

The call above changes the password of given customer.

Get customer
The call to retrieve all customer information is customer/getData(int viewers_id)

curl -X POST \
https://sms.operator.tv/api/customer/getData \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 58}}'

Subscribe
In order to subscribe customer, a bouquet and a product needs to be created in the CSMS. Bouquet is an equivalent of middleware package (has a name and internal ID of
middleware package) and product is bouquet with price and duration (we usually recommend to set price to 0 and duration of 20 years when the operator already has own SMS
/ CRM that takes care of the billing). The method signature is integration/subscribe(int viewers_id, int products_id) . The following example assumes that there is a CSMS
product with internal ID 1 .

curl -X POST \
https://sms.operator.tv/api/integration/subscribe \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id":4321,"products_id":1}}'

Cancel
Very similar call as for subscribe, the method signature is integration/cancel(int viewers_id, int products_id) .

curl -X POST \
https://sms.operator.tv/api/integration/cancel \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id":4321,"products_id":1}}'

Get allowed products

The subscribe and cancel methods accepts products_id . The operator can either read the internal the CSMS GUI or use the sales/getAllowedProductsForCustomer(int
viewers_id) call.

curl -X POST \
https://sms.operator.tv/api/sales/getAllowedProductsForCustomer \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 58}}'

Get subscription info

The call to retrieve the subscriptions (past, current, future) for any given customer is subscription/getCustomerSubscriptionInfo(int viewers_id, array where = []) .

curl -X POST \
https://sms.operator.tv/api/subscription/getCustomerSubscriptionInfo \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 58}}'

When going through the list of returned subscriptions, there are several fields to look for:

viewers_bouquets_active_from - date from which the subscription is active from

viewers_bouquets_active_to - date to which the subscription is active to
viewers_bouquets_cancelled - if cancelled, this field will equal to 1
viewers_bouquets_subscribed - if subscribed, this field will equal to 1
Optional parameter where can be used to limit results. It is an array of SQL-like conditions, for example following will list all non-cancelled current & future subscriptions.

curl -X POST \
https://sms.operator.tv/api/subscription/getCustomerSubscriptionInfo \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 58,"where":["viewers_bouquets_cancelled != 1","viewers_bouquets_active_to >= now()"]}}'

Get list of available portals

The middleware as well as CSMS are multi-vendor. There can be multiple portals in the CSMS created. The createMotvCustomer accepts portals_id which is an internal ID of
portal. The list of avaialble portals can be retrieved via devices/motv/getWhitelistedPortalPairs

curl -X POST \
https://sms.operator.tv/api/devices/motv/getWhitelistedPortalPairs \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{}}'

Get list of available TVODs

This call will return the internal IDs of all available TVODs:

curl -X POST \
https://sms.operator.tv/api/integration/getAvailableMotvTvods \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{}}'

Activate TVOD
Following call will activate given VOD to given customer to given amount of seconds.

curl -X POST \
https://sms.operator.tv/api/integration/activateMotvTvod \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 1, "vods_id": 1, "seconds": 86400}}'

Sending push messages

Following call will send push message to given customer with given title, subtitle, message and link.

curl -X POST \
https://sms.operator.tv/api/integration/motvPushNotification \
-H 'Authorization: [email protected]:1544785566:3297ab897809cc1265ce40fe9154b2b495bb87d' \
-d '{"data":{"viewers_id": 1, "priority": "normal", "title": "Test title", "subtitle": "Test subtitle", "message":"Test message", "link": "https://operator.tv

For sending topic (group) messages, you can use the Middleware Tools -> Push messages page.

moTV portals section

Each middleware vendor should be represented by one portal in the SMS. Located on address https://sms.operator.tv/config/motv/ . Each portal has parameters:

Name: vendor's name

Portal URL: HTTP(s) URL for the vendor's web portal, will be used in templates when sending lost password for example
Vendor: middleware's vendor
Enable self-customer registration: turns on/off the option for customer to register themselves in the applications
Enable customer account update: turns on/off the option for customer to change their own perosnal information
Registraion confirmation: What should be the way to confirm the customer's registration. Option are None - customer will be registered without any confirmation, Email -
customer will receive a registration link via email and GSM - customer will receive a code via GSM message (require GSM gateway integration)
Favicon: image that will be used as a favicon in the web portal
Portal CSS: custom CSS styles that will be applied to the portal, operator can change the portal's colors, logo etc.
Portal HTML footer: optional HTML code that will be inserted into the portal's footer
iOS app ID: apple store application ID - will be used to show the link to application when opening web portal on iOS
Android app ID: google store application ID - will be used to show the link to application when opening web portal on android
Android favicon: image that will be used when showing link to google store application
Portal users: a list of CSMS users that can handle the operations. There is usually one user per platform. These users needs to be created by moTV.eu team
SMTP server: SMTP server that will be used for sending emails.
Enabled portal parts: each part of the interface can be turned on or off. Please note that this does not apply on to web portal but also to applications

Config section
There is a config section in the CSMS system with folliwing options. It is located on address https://sms.operator.tv/config/

Use portals & dealers whitelisting: If yes, CSMS users will only be able to create customers in whitelisted portals for their dealer
Registration email template: template to be used when sending a registration email or GSM message to customer
Lost password email template:template to be used when sending a lost password email or GSM message to customer
Lost pin email template:template to be used when sending a lost pin email or GSM message to customer
Default avatar: an image that will be used for the customer's profile. Images can be uploaded at the top of the CSMS config page