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:

Active: {bool}

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:

TargetFilter: {string} - set to a particular Target type to filter on, e.g. 'Facebook'.

OnlyActive: {bool} - set to True to filter to active Destinations only.

NoCache: {bool} - set to True to ignore cache.

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:

Category: {string} - Optional. Filter to a specific Category value.

Key: {string} - Optional. Filter to a specific Key value.

Value: {string} - Optional. Filter to a specific Value value.

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:

Category: {string} - Required.

Key: {string} - Required.

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:

Category: {string} - Required.

Key: {string} - Required.

Response: 200 OK


DEL /media/destinationproperty/all/{destinationId}

Deletes all properties for a Destination.

Query Parameters:

Category: {string} - Optional. Filter to a specific Category value.

Key: {string} - Optional. Filter to a specific Key value.

Value: {string} - Optional. Filter to a specific Value value.

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:

TargetFilter: {string} - Optional. Refine to a particular Target name (i.e. 'Facebook').
ContentIdFilter: {string} - Optional. Search for publications containing a particular string.
QueryTarget: {bool} - Optional. Set to True to fetch data from the Target API.
NoCache: {bool} - Optional. set to True to ignore cache.

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:

ContentIdFilter: {string} - Optional. Search for publications containing a particular string.
QueryTarget: {bool} - Optional. Set to True to fetch data from the Target API.
NoCache: {bool} - Optional. set to True to ignore cache.

*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:

DestinationId: {Guid} - Required.

QueryTarget: {bool} - Optional.

NoCache: {bool?} - Optional.

Response: 200 OK and JSON containing Publication objects.


GET /media/livepublication/contentId/{contentId}

Gets a live publication by its ContentId and DestinationId.

Query Parameters:

DestinationId: {Guid}  - Required

QueryTarget: {bool} - Optional

NoCache: {bool?} - Optional

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:

DestinationId: {Guid} - Required.

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