Companywebcast API Wiki

Edit

Live Management Service 1.0

The Company Webcast Live Management Service is a REST service that can be used to Start and Stop a Live Webcast, as well as activate and de-activate resources such as topics and speakers.

Table of Contents [Hide/Show]


Live Management Service 1.0
   Methods
      hasstream
      authorize
      start
      stop
      activate
      deactivate
      annotation/activate
      annotation/deactivate
      request
   Data Types
      Credentials
      Request
      Token
   Sample code
      Javascript


Edit

Methods

Live Management Service is a REST service, meaning you interact with it through regular web requests such as GET and POST.
For each Method below, a description is given of how to craft the web request, and what the response will be.

URIs to individual Methods are assembled like this:

"https://live.companywebcast.com/api/" + Path

Please note that this REST service is currently pre-production, and that the URI to the service will change in the coming months.

Edit

hasstream

Determines whether a Webcast has an active stream.
Webcasts without an active stream cannot be started or stopped.

Request Method
GET

Path
"webcast/" + webcastId + "/hasstream"

Required Request Headers
"Accept", "application/json"

Returns
Boolean. True if the stream is available, false if it's not.

Edit

authorize

Use your API credentials to retrieve a token.
You'll need this token for further interaction with Live Management Service.

Request Method
POST

Path
"webcast/" + webcastId + "/authorize"

Required Request Headers
"Accept", "application/json"
"Content-Type", "application/json"

Post Data
Credentials. Sends your Company Webcast API account details.

Returns
Token. Contains an authorization token.

Edit

start

Start a Webcast.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/start"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

stop

Stop a Webcast.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/stop"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

activate

Activates a Resource.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/" + resourceType + "/" + resourceId + "/activate"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

deactivate

Deactivates a Resource.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/" + resourceType + "/" + resourceId + "/deactivate"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

annotation/activate

Activates an Annotation.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/annotation/activate"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Post Data
A JSON string. The text of your annotation, encapsulated in double quotes: "This is my message"

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

annotation/deactivate

Deactivates an Annotation.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/annotation/deactivate"

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of this Method request. Use it here to retrieve the Request Id.

Edit

request

Retrieves the state of a Request.
As most Methods of this service are asynchronous, this Method enables state monitoring of individual Method requests.
An authorization token, retrieved through the authorize Method, needs to be included in the request.

Request Method
POST

Path
"webcast/" + webcastId + "/request/" + requestId

Required Request Headers
"Accept", "application/json"
"Authorization", token

Returns
Request. An object that describes the state of the Method request. Use it here to retrieve state of a Method request.

Edit

Data Types

All data sent to and received from Live Management Service is in the JSON format.
These are the objects of the Live Management Service.

Edit

Credentials

Used to retrieve the token required for most Methods.

username
A string. Your Company Webcast provided API username
password
A string. Your Company Webcast provided API password

Edit

Request

Used for tracking the state of a Method request.

id
A string. The id of the Request.
intent
A string. Describes the intent of the Method request.
Is either "request.webcast.start", "request.webcast.stop" or "request.webcast.resource.activate".
state
A string. Describes the state of the Method request.
Is "created" immediately after the Method request, then either "success" or "error".
message
A string. When state equals "error", message describes the error.

Edit

Token

Used for authorization on most Methods.

token
A string. An authorization token that is required for requests to the start, stop, activate and request Methods.

Edit

Sample code

Edit

Javascript

<!DOCTYPE html>
<html>
<head>
    <title></title>
	<meta charset="utf-8" />
    < script src="fetch.js"></script>
    < script src="es6-promise.auto.js"></script>
</head>
<body>

</body>
</html>

< script type="text/javascript">

    var restUri = "https://live.companywebcast.com/api/",
        username = "XXX",
        password = "YYY";

    (function () {

        var webcastId = "00000000-a06b-421c-a453-6b44c59edc05",
            topicIds = ["00000000-593c-4f4c-af04-c02a05155a65",
                        "00000000-0e0f-4163-93e2-f9f302d3d136",
                        "00000000-08b5-40f1-a378-0b6bb7d6fc06",
                        "00000000-7bc0-41fb-96c3-b7f5efacf663",
                        "00000000-dccd-4d17-ae2c-ca0406afce92"];

        WaitForReadyToPlay(webcastId).then(function () {

            return GetToken(webcastId);

        }).then(function (token) {

            Start(webcastId, token).then(function () {

                return wait(10000);

            }).then(function () {

                return ActivateTopics(topicIds, webcastId, token);

            }).then(function () {

                return Stop(webcastId, token);

            });

        });

    })();

    function WaitForReadyToPlay(webcastId) {

        console.log("waiting for ready to play");

        var init = { method: "GET", mode: 'cors' };
        var request = new Request(restUri + "webcast/" + webcastId + "/hasstream", init)
        
        function checkstream() {
            return fetch(request).then(function (response) {
                return response.json().then(function (json) {
                    if (json) {
                        console.log("ready to play");
                        return;
                    } else {
                        return wait(1000).then(checkstream);
                    }
                });
            });
        }

        return checkstream();

    }

    function GetToken(webcastId) {

        console.log("get live manager token");

        var headers = new Headers({
            "Content-Type" : "application/json"
        });

        var init = {
            method: "POST",
            mode: 'cors',
            body: JSON.stringify({
                username: username,
                password: password
            }),
            headers: headers
        };

        var request = new Request(restUri + "webcast/" + webcastId + "/authorize", init)

        return fetch(request).then(function (response) {
            return response.json().then(function (json) {

                console.log("live manager token " + json.token);
                return json.token;

            });
        });

    }

    function Start(webcastId, token) {

        console.log("start webcast");
        var headers = new Headers({ "Authorization" : token });
        var init = { method: "POST", mode: 'cors', headers: headers };
        var request = new Request(restUri + "webcast/" + webcastId + "/start", init);
        return fetch(request).then(function (response) {
            return response.json().then(function (json) {
                return WaitForRequest(webcastId, json.id, token);
            });
        });

    }

    function Stop(webcastId, token) {

        console.log("stop webcast");
        var headers = new Headers({ "Authorization": token });
        var init = { method: "POST", mode: 'cors', headers: headers };
        var request = new Request(restUri + "webcast/" + webcastId + "/stop", init);

        return fetch(request).then(function (response) {
            return response.json().then(function (json) {
                return WaitForRequest(webcastId, json.id, token);
            });
        });

    }

    function ActivateResource(webcastId, resourceId, resourceType, token) {

        console.log("activating resource " + resourceType + " " + resourceId);

        var headers = new Headers({ "Authorization": token });
        var init = { method: "POST", mode: 'cors', headers: headers };
        var request = new Request(restUri + "webcast/" + webcastId + "/" + resourceType + "/" + resourceId + "/activate", init)

        return fetch(request).then(function (response) {
            return response.json().then(function (json) {
                return WaitForRequest(webcastId, json.id, token);
            });
        });

    }

    function WaitForRequest(webcastId, requestId, token) {

            var headers = new Headers({ "Authorization" : token });
            var init = { method: "GET", mode: 'cors', headers: headers };
            var request = new Request(restUri + "webcast/" + webcastId + "/request/" + requestId, init)

            function checkrequest() {
                return fetch(request).then(function (response) {
                    return response.json().then(function (json) {
                        switch (json.state) {
                            case "success":
                                return;
                            case "error":
                                throw new Error(json.message);
                            default:
                                return wait(1000).then(checkrequest);
                                break;
                        }
                    });
                });
            }

            return checkrequest();
    }

    function ActivateTopics(topicIds, webcastId, token) {
        return topicIds.reduce(function (promise, topicId) {
            return promise.then(function () {
                return ActivateResource(webcastId, topicId, "topic", token).then(function () {
                    console.log("topic activated");
                    return wait(10000);
                });
            });
        }, Promise.resolve());
    }

    function wait(t) {

        console.log("waiting for " + t / 1000 + " seconds");

        return new Promise(function (resolve) {
            setTimeout(resolve, t)
        });
    }

</ script>