MEDIA SYNDICATION INTEGRATION

The VIS provides integration with the MediaSyndication API, it currently supports Live streaming via Wowza server(s).


Target Enumeration:

Facebook = 0,
Twitter = 1,
YouTube = 2,
MPX = 3,
Custom = 4

Media Destinations

Destinations represent the access to the Target APIs, and are essentially quite similar to ‘Channels’.

Media Destination Object

{
  "id": "9cbd95c0-7c6d-4613-945c-ef82169bee27",
  "name": "Destination",
  "target": 4,
  "configJson": "{...}",
  "active": true
}

Supported Actions

POST /media/destination/

Add a Destination.

Request Body:

{
    "name": "Destination",
    "target": "Facebook",
    "destinationJson": "{...}",
    "active": true
}

Note: it is not recommended to specify Active as this is controlled by the internal workflow. However, if needed you can ‘reset’ it a Destination by passing False.

Note: target does not have to be the enumerated value, and can be a textual name of the Target such as ‘Facebook’.

Response: 200 OK and JSON containing a Media Destination object.


PUT /media/destination/{id}

Updates a given Destination.

This request behaves the same as the Add Destination


PUT /media/destination/active/{id}

Updates only the active property on the Destination.

Query Parameters:

Name Type Required Description
active bool Yes The new value for the Active property.

Note: should only be used to repair or reset a Destination’s activation workflow. See below.

Response: 200 OK


PUT /media/destination/activate/{id}

Calls the Media API to check the activation process against the Destination.

Response: 200 OK and JSON matching the below.

{
    "actionTitle": "Destination requires ...",
    "actionDescription": "Please activate by ...",
    "actionRequired": true
}

GET /media/destination/

Get multiple Destinations.

Query Parameters:

Name Type Required Description
targetFilter String No set to a particular Target type to filter on, e.g. 'Facebook'.
onlyActive bool No Whether or not to filter to only active Destinations.
noCache bool No Whether or not to bypass cache. Defaults to False.

Response: 200 OK and a JSON array containing multiple Media Destination objects.


GET media/destination/{id}

Get a specific Destination by Id.

Response: 200 OK and JSON containing a Media Destination object.


DEL /media/destination/{id}

Deletes the Destination (and all child publications) from the database.

Response: 200 OK


Media Destination Properties

A Destination can have custom properties, which are used to represent extra data not relevant to the Target integration.

Media Destination Property Object

{
  "id": "72859091-6ddb-459a-9803-c85f26919589",
  "category": "category-here",
  "key": "key-here",
  "value": "value-here",
  "client": "vualto-example",
  "destinationId": "c00d0849-0bf2-4583-ab13-5a7defd9938f"
}

Supported Actions

POST /media/destinationproperty/

Adds a new property, or updates an existing one if an Id is provided. Duplicate Category & Key values cause an update too.

Request Body:

{
    "id": "c00d0849-0bf2-4583-ab13-5a7defd9938f",
    "destinationId": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
    "category": "category-here",
    "key": "key-here",
    "value": "value-here"
}

Note: id is optional.


GET /media/destinationproperty/all/{destinationId}

Gets all properties for a Destination.

Query Parameters:

Name Type Required Description
category String No The Category value to filter to.
key String No The Key value to filter to.
value String No The Value value to filter to.

Response: 200 OK and a JSON array containing multiple Media Destination Properties.


GET /media/destinationproperty/id/{id}

Gets a specific property based on its ID.

Response: 200 OK and JSON containing the Media Destination Properties.


GET /media/destinationproperty/{destinationId}

Fetches a single property from a Destination based on the given Category & Key values. For use when the Id is not known.

Query Parameters:

Name Type Required Description
category String Yes The Category value.
key String Yes The Key value.

Response: 200 OK and JSON containing the Media Destination Properties.


DEL /media/destinationproperty/id/{id}

Deletes a given property by Id.

Response: 200 OK


DEL /media/destinationproperty/{destinationId}

Deletes a given property by its Destination Id, Category, and Key values.

Query Parameters:

Name Type Required Description
category String Yes The Category value.
key String Yes The Key value.

Response: 200 OK


DEL /media/destinationproperty/all/{destinationId}

Deletes all properties for a Destination.

Query Parameters:

Name Type Required Description
category String No The Category value to filter to.
key String No The Key value to filter to.
value String No The Value value to filter to.

Response: 200 OK


Media Live Publications

Media Live Publication Object

{
  "id": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
  "target": 0,
  "destinationId": "b237e4f1-14ff-4542-b342-67e275824d46",
  "contentId": "my-content-id-here",
  "dateCreated": "iso8601-datetime-here",
  "dateCompleted": "iso8601-datetime-here",
  "dateStarted": "iso8601-datetime-here",
  "details": {},
  "callbacks": 
    [
        {
          "id": "2834c93b-e76e-4fef-950b-bca37191585f",
          "publicationId": "1b0d7fa1-bfcf-4b46-b422-37528346d90d",
          "url": "url-here",
          "lastTriggered": "iso8601-datetime-here"
        }
    ]
}

Details vary depending on the Target, and can be empty or null if we have not been able to query it. However, there are some shared properties.

Shared Details:

{
    "ingestionDetails": [
        {
            "rtmpServerUrl": "url-here",
            "rtmpApplicationName": "rtmp-name-here",
            "rtmpStreamName": "rtmp-stream-name-here",
            "isPrimary": true
        }
    ],
    "CallbackUrls": [ "url-here" ]
}

Facebook Details:

{
    "title": "title-here",
    "description": "description-here",
    "saveVod": true,
    "plannedStartTime": "iso8601-datetime-here",
    "plannedEndTime": "iso8601-datetime-here",
    "resourceId": "154185712",
    "streamUrl": "url-here",
    "secureStreamUrl": "url-here",
    "streamName": "name-here",
    "embedCode": "embed-code-here",
    "status": "status-here",
    "contentTags": [ "tag1", "tag2" ]
}

YouTube Details:

{
    "title": "title-here",
    "description": "description-here",
    "broadcastId": "111000999245",
    "liveStreamId": "111999000256",
    "scheduledStartTime": "iso8601-datetime-here",
    "scheduledEndTime": "iso8601-datetime-here",
    "privacyStatus": "PRIVATE",
    "ingestionType": "rtmp"
}

Note: ingestionType can be dash or rtmp


Supported Action

POST /media/livepublication/

Create multiple live publications.

Request Body:

{
    "eventId": "8c5b1a96-bf66-4f11-b16b-58d168ea9754",
    "publications": [
        {
            "audioInputId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
            "destinationId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
            "publicationJson": "{...}"
        }
    ],
    "startInstantly": false
}

Each publication requires these three parts, with all of the core metadata held in the PublicationJson field.

StartInstantly is simply a flag to immediately start these publication when they are created (to save time).

Response: 200 OK


PUT /media/livepublication/recreate/

Recreates a single live publication (i.e. re-try creation against Target, discarding previous details)

Request Body:

{
    "eventId": "7f05d046-f667-42cd-89cc-3f992c1b6583",
    "publicationId": "974b644d-eff4-45b2-9256-0f488b063b72",
    "destinationId": "249b575d-24c1-4e75-bdee-05cf72f2eb5c",
    "removeOriginal": false
}

Note: removeOriginal is optional.

Response: 200 OK


PUT /media/livepublication/start/

Start a single live publication by adding StreamTargets on Wowza and calling ‘Start’ on the Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

PUT /media/livepublication/stop/

Stop a single live publication by removing the StreamTargets on Wowza and calling ‘Stop’ on the Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK

PUT /media/livepublication/start/all/

Start multiple publications by adding StreamTargets on Wowza and calling ‘Start’ on the Media API (executes concurrently).

Request Body:

{
    "eventId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99",
    "publications": [
        {
            "publicationId": "65fb2781-9447-490d-b950-91a2741bd331",
            "destinationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2"
        }
    ]
}

Response: 200 OK


PUT /media/livepublication/stop/all/

Stop multiple publications by removing StreamTargets on Wowza and calling ‘Stop’ on the Media API.

Request Body:

{
    "eventId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99",
    "publications": [
        {
            "publicationId": "65fb2781-9447-490d-b950-91a2741bd331",
            "destinationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2"
        }
    ]
}

Response: 200 OK


PUT /media/livepublication/publish/

Publish a single live publication by calling ‘Publish’ on Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK


PUT /media/livepublication/unpublish/

Un-publish a single live publication by calling ‘Un-publish’ on Media API.

Request Body:

{
    "eventId": "1c0ce4ce-8636-4da4-92dd-22c3845fbcef",
    "publicationId": "2c9ca563-4f7d-4e87-8aa4-89d4f3177de2",
    "destinationId": "82ba8636-d4cb-46de-a75c-bb2bc3199d99"
}

Response: 200 OK


GET /media/livepublication/

Get multiple live publications, filtered by parameters.

Query Parameters:

Name Type Required Description
targetFilter String No Refine to a particular Target name (i.e. 'Facebook').
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and a JSON array containing multiple Publication objects.


GET /media/livepublication/transactionId/{transactionId}

Get multiple live publications by TransactionId (i.e. those created in the same batch).

Query Parameters:

Name Type Required Description
contentIdFilter String No Search for publications containing a particular string.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

*Whilst often required to fetch all data, it is recommended not to use this on the Get multiple query and instead use this parameter on the GET individual publication call.

Response: 200 OK and a JSON array containing multiple Publication objects.


GET /media/livepublication/{id}

Get a live publication by its Id and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.


GET /media/livepublication/contentId/{contentId}

Gets a live publication by its ContentId and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.
queryTarget bool No Set to True to fetch data from the Target API.
noCache bool No Whether or not to skip cache. Defaults to False.

Response: 200 OK and JSON containing Publication objects.


GET /media/livepublication/statistics/{publicationId}

Get the statistics for a live publication by Id and DestinationId.

Query Parameters:

Name Type Required Description
destinationId String Yes Required to identify the type of Publication.

Response: 200 OK and JSON response:

{
    "target": 0,
    "details": {}
}

Note: the details section varies between target values.

Facebook Details:

{
    "liveViews": 0,
    "liveViewsMax": 5,
    "likeCount": 1,
    "loveCount": 0,
    "hahaCount": 0,
    "wowCount": 2,
    "sadCount": 0,
    "angryCount": 0
}

Note: all values can be null if unavailable.

YouTube Details:

{
    "concurrentViewers": 4,
    "viewCount": 10,
    "likeCount": 1,
    "dislikeCount": 1,
    "favouriteCount": 0,
    "commentCount": 3
}

Note: all values can be null if unavailable.

Status code: 200 OK


DEL /media/livepublication/

Delete many publications.

Request Body:

{
    "eventId": "116e590f-79a6-46d5-818c-79a64eee886c",
    "publications": [
        {
            "publicationId": "9ab0c720-d186-45d1-86e7-b4f72df72d73",
            "destinationId": "490a8064-8c11-4004-b252-b49666673d29",
            "hardDelete": false
        }
    ]
}

Response: 200 OK