Event Management API

Comments (0)

Overview

  • All requests must be HTTP POST requests, with content-type of "application/x-www-form-urlencoded".
  • All responses will be of content-type "application/json;charset=utf-8".

Authentication

URL

https://api.webcasts.com/api/authenticate

Rate Limits

Rate Limit N/A

Headers

Content-Type application/x-www-form-urlencoded

Body

urlencoded
username username
password password
Example Request
Get a New Token
 
 $.ajax({
  type: 'POST',
  url: 'https://api.webcasts.com/api/authenticate', 
  data: {username:"testuser",password:"testpassword"},
  dataType: 'json',
  success: function(result) {
    console.log(JSON.stringify(result));
  },
  error: function(xmlHttpRequest, status, errorThrown) {
     alert(errorThrown);
  }
});
Response Framework
Get a New Token
 
{
	"convey_api": {
		"currentTimestamp": long - time that the request was processed.
		"version": string - current version.
		"result": {
	      "authenticationData": {
	        "token_expiration": long - The timestamp when this token will become invalid,,
	        "token": string - A very long string value that will be used for authentication for the current session.
	     },		
		 "returnCode": integer - 1 indicates success, all other values indicate an error, see table for meaning of individual values.
		}
	}
}
Example Response200 OK
{
    "convey_api": {
        "result": {
            "authenticationData": {
            "token_expiration": 1545086743630,
            "token": "Token_Value"
        },
        "returnCode": 1
    },
        "current_timestamp": 1545079543638,
        "version": 3
    }
}

Event Create

URL

https://api.webcasts.com/api/event/create

Rate Limits

Rate Limit 100

Headers

Content-Type application/x-www-form-urlencoded

Body

urlencoded
token Must be a valid authentication token.
event_data JSON string containing all event parameters. See tables below.

Event Data Properties

User account permissions may impact available properties.

Required Event Data Properties

Property Type Notes
event_title String Title of the newly created event. 1000 character limit, if a longer value is sent, it will truncated.
type String Accepted values are "live" or "ondemand".
scheduled_start_time Long Timestamp representing scheduled start time of the event. Time component must be on a 15 minute mark, otherwise the value will be rounded up to the next 15 minute mark.
scheduled_duration Integer Scheduled duration in minutes. Must be a multiple of 30 between 30 and 480(8 hours). Other values will be round up to the next 30 minute mark and anything greater than 480 will be set to 480.
timezone String Timezone id of the time zone the event will be scheduled for. See table below for accepted time zones. Invalid values will set time zone to UTC.
region Integer The region the event will be scheduled for. Ignored, and not required, if type is set to "ondemand". Currently live events set to Telephony or Video Bridge acquisition types also ignore this value, though this will change in the future. See table below for options.
acquisition_type Integer Ignored, and not required, if type is set to "ondemand". See table below for options.
vcu_address String Required if VCU/Telepresence is selected as acquisition type, ignored otherwise. IP address of the VCU that will be used.
vcu_connection_type String Required if VCU/Telepresence is selected as acquisition type, ignored otherwise. Accepted values are "H.323" or "SIP".
telephony_type String Required if Telephone is selected as acquisition type, ignored otherwise. Accepted values are "directdial" or "bridge". Bridge will create primary and backup bridges for the event, direct dial will not create any bridges.
video_bridge_type String Required if Video Bridge is selected as acquisition type, ignored otherwise. Accepted values are "standard" or "advanced".
media_type String Ignored, and not required, if type is set to "live". Accepted values are "video" or "audio".
audience_capacity Integer Audience capacity of the event. Must be between 50 and 10000.
event_expiration_months Integer The number of months before the event will expire after it is archived, for live events, or first published, for OD events. Must be between 3 and 12.
event_id String Required for the Event Update request. The ID of the event to update

Optional Event Data Properties

Property Type Notes
folder_id Integer The id of the folder to create the event in. If no folder option is specified, the home folder of the api user will be used.
folder_from_event Integer The event id of an existing to event. The new event will be created in the same folder as this event. Will be ignored if folder_id is passed. If no folder option is specified, the home folder of the api user will be used.
cost_center String Optional value defining a "cost center". Has no effect on the event, but will show in our reporting tool.
guest_presenter_types String Comma separated list of integers. Each value is a bitmask representing a type of guest presenter portal to create. See table below for bitmask values.
scheduled_player_close_time Long Timestamp representing a scheduled time to close the player. Note that this will only be enforced if the set time is after the event has been archived (for Live events) or published (for On Demand events).

Timezone ID's

ID
US/Hawaii
US/Alaska
US/Pacific
US/Pacific
US/Mountain
US/Central
US/Eastern
Europe/London
CET
EET
Asia/Dubai
Asia/Karachi
Asia/Hong_Kong
Japan
Australia/Sydney
Asia/Kolkata
America/Sao_Paulo
Pacific/Auckland
Etc/UTC

Region Mapping

Region Value
North America 1
South America 2
Europe 3
Africa 4
Asia/Pacific 5

Acquisition Type Mapping

Acquisition Type Value
Webcam 0
VCU/Telepresence 1
Your Encoder 2
Telephone 3
Video Bridge 4

Guest Presenter Types bitmask

Guest Presenter Types Value
Live Studio 1
OD Studio 2
Reports 4
Content 8
Q&A Only 16
Example Request
200 OK
 
 $.ajax({
  type: 'POST',
  url: 'https://api.webcasts.com/api/event/create', 
  data: {
    token:"testtoken",
    event_data: "{\"event_title\":\"Default Event Create\",\"type\":\"live\",\"scheduled_start_time\":1541674800000,\"scheduled_duration\":30,\"timezone\":\"US/Eastern\",\"region\":0,\"acquisition_type\":3,\"audience_capacity\":1000,\"event_expiration_months\":12}"
  },
  dataType: 'json',
  success: function(result) {
      console.log(JSON.stringify(result));
  },
  error: function(xmlHttpRequest, status, errorThrown) {
      alert(errorThrown);
  }
});
Response Framework
{
	"convey_api": {
		"currentTimestamp": long - time that the request was processed.
		"version": string - current version.
		"result": {
			"returnCode": integer - 1 indicates success, all other values indicate an error, see table for meaning of individual values.
			"event_data": {
				"scheduled_duration": int - Scheduled duration in minutes.
				"scheduled_start_time": long - Timestamp representing scheduled start time of the event.
				"event_title": string - The title of the event. 
				"folder_name": string – The name of the folder the event is in.
				"audience_capacity": int - Audience capacity of the event.
				"viewer_link": string - The URL of the viewer link for the event.
				"guest_presenter_links": [{
					"guest_presenter_type": int - Bitmask representing the guest presenter types of this guest presenter portal.
					"pin": string - The pin associated with this guest presenter portal.
					"link": string - The URL of this guest presenter portal.
				}]
			}
		}
	}
}
Example Response200 OK
{
    "convey_api": {
        "result": {
            "returnCode": 1,
            "event_data": {
                "scheduled_duration": 30,
                "event_id": 0000000,
                "audience_capacity": 1000,
                "viewer_link": "https://viewer_link",
                "event_title": "Default Event Create",
                "folder_name": "Folder_Name",
                "scheduled_start_time": 1541674800000,
                "scheduled_player_close_time": 0
        }
    },
        "current_timestamp": 1545086092097,
        "version": 3
    }
}

Event Update

URL

https://api.webcasts.com/api/event/update

Rate Limits

Rate Limit 100

Headers

Content-Type application/x-www-form-urlencoded

Body

urlencoded
tokenMust be a valid authentication token.
event_dataJSON string containing event parameters. All parameters are the same as for Event Creation requests with the one additional required parameter for event ID. See event_data parameters here.
Example Request200 OK
 $.ajax({
      type: 'POST',
      url: 'https://api.webcasts.com/api/event/update', 
      data: {
        token:"testtoken",
        event_data: "{\"event_id\":\"0000000\",\"scheduled_duration\":150}"
      },
      dataType: 'json',
      success: function(result) {
        console.log(JSON.stringify(result));
      },
      error: function(xmlHttpRequest, status, errorThrown) {
        alert(errorThrown);
      }
    });
Response Framework
{
        "convey_api": {
            "currentTimestamp": long - time that the request was processed.
            "version": string - current version.
            "result": {
                "returnCode": integer - 1 indicates success, all other values indicate an error, see table for meaning of individual values.
                "event_data": {
                    "scheduled_duration": int - Scheduled duration in minutes.
                    "scheduled_start_time": long - Timestamp representing scheduled start time of the event.
                    "event_id": int - Event id.
                    "event_title": string - The title of the event. 
                    "folder_name": string – The name of the folder the event is in.
                    "audience_capacity": int - Audience capacity of the event.
                    "viewer_link": string - The URL of the viewer link for the event.
                    "guest_presenter_links": [{
                        "guest_presenter_type": int - Bitmask representing the guest presenter types of this guest presenter portal.
                        "pin": string - The pin associated with this guest presenter portal.
                        "link": string - The URL of this guest presenter portal.
                    }]
                }
            }
        }
    }
Example Response
{
      "convey_api": {
        "result": {
          "returnCode": 1,
          "event_data": {
            "scheduled_duration": 240,
            "event_id": 0000000,
            "audience_capacity": 1250,
            "viewer_link": "https://viewer_link",
            "event_title": "updated event",
            "folder_name": "APIEvents",
            "guest_presenter_links": [
              {
                "guest_presenter_type": 8,
                "pin": "LOGFE3",
                "link": "https://viewer_link"
              },
              {
                "guest_presenter_type": 31,
                "pin": "XC4T8FDE",
                "link": "https://viewer_link"
              },
              {
                "guest_presenter_type": 2,
                "pin": "PYFE3",
                "link": "https://viewer_link"
              },
              {
                "guest_presenter_type": 4,
                "pin": "456DF",
                "link": "https://viewer_link"
              }
            ],
            "scheduled_start_time": 1544113800000,
            "scheduled_player_close_time": 0
          }
        },
        "current_timestamp": 1545419969614,
        "version": 3
      }
    }

Event Status

URL

https://api.webcasts.com/api/event/status

Rate Limits

Rate Limit 500

Headers

Content-Type application/x-www-form-urlencoded

Body

urlencoded
token Must be a valid authentication token.
event_id The ID of the event to return the status of.
Example Request200 OK
 $.ajax({
  type: 'POST',
  url: 'https://api.webcasts.com/api/event/status', 
  data: {
    token:"testtoken",                                     
    event_id: "0000000" 
  }, 
  dataType: 'json',
  success: function(result) {
    console.log(JSON.stringify(result));
  },
  error: function(xmlHttpRequest, status, errorThrown) {
    alert(errorThrown);
  }
});
Response Framework
{
	"convey_api": {
		"currentTimestamp": long - time that the request was processed.
		"version": string - current version.
		"result": {
			"returnCode": integer - 1 indicates success, all other values indicate an error, see table for meaning of individual values.
			"event_data": {
                "scheduled_duration": int - Scheduled duration in minutes.
                "scheduled_player_close_time": int - Scheduled time to close player in minutes.
				"scheduled_start_time": long - Timestamp representing scheduled start time of the event.
				"event_title": string - The title of the event. 
				"folder_name": string – The name of the folder the event is in.
				"audience_capacity": int - Audience capacity of the event.
				"viewer_link": string - The URL of the viewer link for the event.
			}
		}
	}
}
Example Response
{
    "convey_api": {
        "result": {
            "returnCode": 1,
            "event_data": {
                "scheduled_duration": 60,
                "event_id": 0000000,
                "audience_capacity": 50,
                "viewer_link": "https://viewer_link",
                "event_title": "Status of Event",
                "folder_name": "Folder_Name",
                "scheduled_start_time": 1544113800000,
                "scheduled_player_close_time": 0
        }
    },
        "current_timestamp": 1545086092097,
        "version": 3
    }
}

Folder Tree

URL

https://api.webcasts.com/api/folder/tree

Rate Limits

Rate Limit 60

Headers

Content-Type application/x-www-form-urlencoded

Body

urlencoded
token Must be a valid authentication token.
folder_id The ID of the root folder of the returned folder tree. If not included, the root folder will be the home folder of the API user account.

Notes

*Note on folder tree response. The children key will not be present if a folder has no subfolders. If a folder has one direct subfolder, the value of the children key with be a JSON object containing the information for that subfolder. If a folder has multiple direct subfolders, the value of the children key will be a JSON array of JSON objects containing the information for each of those direct subfolders. The below example shows this behavior.
Example Request200 OK
 $.ajax({
  type: 'POST',
  url: 'https://api.webcasts.com/api/folder/tree', 
  data: {
    token:"testtoken"                                     
  }, 
  dataType: 'json',
  success: function(result) {
    console.log(JSON.stringify(result));
  },
  error: function(xmlHttpRequest, status, errorThrown) {
     alert(errorThrown);
   }
});
Response Framework200 OK
{
	"convey_api": {
		"currentTimestamp": long - time that the request was processed.
		"version": string - current version.
		"result": {
			"returnCode": integer - 1 indicates success, all other values indicate an error.
			"folder_tree": {
				folder_id: string - ID of the folder.
				folder_name: string - Name of the folder.
				children: JSON array - Array of JSON objects representing the direct children of this folder.
			}
		}
	}
}
Example Response200 OK
{
  "convey_api": {
    "result": {
      "returnCode": 1,
      "folder_tree": {
        "folder_name": "root_foler",
        "folder_id": "0000000",
        "children": {
          "folder_name": "subfolder",
          "folder_id": "0000000",
          "children": [
            {
              "folder_name": "folder 1",
              "folder_id": "0000000"
            },
            {
              "folder_name": "folder 2",
              "folder_id": "0000000"
            }
          ]
        }
      }
    },
    "current_timestamp": 1536330466620,
    "version": 3
  }
}

Return Codes & Error Reponse - standard for all requests

Return Code Description
0 General Error
1 Success
2 Partial Success
10 You are not authorized to run a report on this event.
11 The User ID or Session ID is invalid.
12 The Token is invalid or expired.
51 There was invalid data in the report. Please contact your support representative.
50 The report for this event is currently not available. Please contact your support representative.
60 The reporting service is not available at this time. Please contact your support representative.
61 You have reached the limit on the number of calls you can run for an event. Please try again later.
62 You have reached the maximum number of reports that can be run within one hour. Please try again later.
70 Oops!! Please remove any insecure tags from the input parameters and try again.
71 Please use a valid version number.
72 There were missing or invalid input parameters in your request.
73 Ambiguous platform.
74 Could not identify the Reporting Resource requested
Response Framework
{
      "convey_api": {
          "currentTimestamp": long - time that the request was processed.
          "version": string - current version.
          "result": {
            "returnCode": integer - 1 indicates success, all other values indicate an error, see table for meaning of individual values.
            "error": string - A message describing the error.
          }
      }
}
Error Response200 OK
{
      "convey_api": {
        "currentTimestamp": 1524839077300, 
        "version": 3,
        "result": {
          "returnCode": 12,
          "error": "The Token is invalid or expired."
        }
      }
}