channels > list | WS.WebTV API Reference | WebTV Solutions

Requesting a Channel/Page list

support, ws.webtv, api, channels, list

Professional and affordable online video solutions

Español Español
WebTV Solutions. Professional and affordable online video solutions
Tutorials, technical documents and downloads
Support
WebTV Solutions Support
«»

API: Introduction

API: Reference

API: Reference

channels > list

Rev. Jul. 4, 2018

Description

Requesting a Channel/Page list

Required Credential Permission

GET [Signed + Unsigned Requests]

NOTE: Unsigned requests will only return active and approved Channels/Pages.
Print Print

IMPORTANT!
When using signed requests (and no status filter has been specified) the API will return Channels/Pages with any status and ignore any access restriction. Use the appropriate filtering according to your intentions.

Building the Request


Request URL and GET vars

GET vars specific to this request:

Var Value Description
go channels The API section
do list The API action

Resulting Request URL:
The resulting request URL would be similar to this (don't forget to append the required info: key, timestamp, salt and signature):
https://....../api.php?go=channels&do=list&{required information}

POST vars

The following list filters are available by using POST vars.
TIP: You can use several filters at the same time.

Var Value Description
fields (string) "field1,field2,..." Specify the fields to be included in the result.
"*" = all fields (default).
"field1, field2, field2" = subset of the fields [Recommended] - separated by comma.
Available fields:
id, id_user, status, status_moderation, type, privacy, privacy_access_level, title, title_url, description, description_seo, tags, img_poster, img_social, img_thumbnail, img_icon, date, views_page, views_embed, display_info, menu_position, menu_group, menu_inclusion, socialize, template, allow_comments, banner_top, banner_player, banner_sidebar, banner_mobile, page_head_code, page_endbody_code, img_bkg_use, img_bkg, img_bkg_color, img_bkg_position_x, img_bkg_position_y, img_bkg_repeat, img_bkg_attachment, id_import, date_lastmod, store_on_sale

Embed code generation:		    
generateEmbedCode (int) 1 [Channels only] Generate the embed code for each Channel
embedWidth (int) width Width for the embed code (in pixels)
embedHeight (int) height Height for the embed code (in pixels)
embedURLVars (string) "&var1=value1..." Video Player URL vars for the Embed code (check the possible URL vars here)

Paging options:		    
resultsPerPageFilter (int) n Number of results per page
current_page (int) n The number of the current page
paging (int) 0/1 To enable/disable paging
limit (int) n Results limit (only if resultsPerPageFilter is not specified and paging=0)

Frequently used filters:		    
idUserFilter (int) author ID List Channels/Pages from the specified User
statusFilter (mixed) status List Channels/Pages that match the specified status. Available options:
0 (inactive), 1 (active), 2 (pending moderation), "any", "onsale", "pending" (moderation), "disapproved", "activeAndApproved", "onsaleActiveAndApproved", "upcomingInactiveAndApproved"
NOTE: Unsigned requests will only return active and approved Channels/Pages.
sortByFilter (string) "option" Sort the list. Available options:
"menu_position" (default), "date" (latest first), "date2" (reverse date), "title", "views_page", "id", "random", "randomSeed"
typeFilter (mixed) type List Channels/Pages of the specified type. Available options:
"any", 0 (Video), 1 (Page), 2 (Portal)
excludeTypeFilter (string) "type1,type2..." List Channels/Pages whose type if different than the specified ones (separated by comma). Available options:
0 (Video), 1 (Page), 2 (Portal)
tagsFilter (string) "tag1,tag2,..." List Channels/Pages according to tags (separated by comma).
idFilter (string) "ID1,ID2,..." List Channels/Pages whose ID matches the specified ones (separated by comma).
idImportFilter (string) "ID1,ID2,..." List Channels/Pages whose Import ID matches the specified ones (separated by comma).
menuInclusionFilter (string) "menu" List Channels/Pages according to the menu inclusion setting. Available options:
"included", "main", "footer", "none"

Date filters:		    
dateFilter (int) timestamp List Channels/Pages whose date matches the day of the timestamp (from 00:00:00 to 23:59:59).
dateStartFilter (int) timestamp List Channels/Pages whose date is equal or later respect the day of the timestamp (from 00:00:00)
dateEndFilter (int) timestamp List Channels/Pages whose date is equal or earlier respect the day of the timestamp (up to 23:59:59)

Category filters:		    
categoriesFilter (int) n List Channels/Pages associated to the Category.
Specify a Category ID or -1 for "orphaned" Channels/Pages (Channels/Pages not associated to a Category)
categoriesFilterStrict (int) 0/1 (Depends on the previous option) List Channels/Pages directly associated with the specified Category (ignoring any Category inheritance).

Search filters:		    
search (string) "term" Term to search
searchMode (string) "mode" The way the system searches for the supplied term. Available options:
Standard modes (faster): Look for exact matches.
"std1" = search on title + tags.
"std2" = search on title + tags + short description.
"std3" (default) = search on title + tags + full description.
Words modes (slower, find more matches): Search by breaking the term into words and looking for all posible combinations of them.
"words1" = search on title + tags.
"words2" = search on title + tags + short description.
"words3" = search on title + tags + full description.

Forbidden content exclusion filters:
(Since WS.WebTV 3.0.2pf1)		    
excludeForbiddenContent (int) 0/1 Whether to exclude "forbidden" Channels from the list. "Forbidden" means that the user is not allowed to access.
Note that you must also past the "cvr" variable (see a bit below).
excludeForbiddenOnSaleContent (int) 0/1 (Only if excludeForbiddenContent = 1) Whether to also exclude "forbidden" On Sale Channels from the list.
cvr (string) "ID1,ID2,..." CVR = Content View Restriction.
This is a list of comma separated Channel IDs that the current User is not allowed to access. All Channels matching these IDs will be excluded from the list when excludeForbiddenContent = 1. If cvr is blank then no Channel will be excluded from the list regardless of the value of excludeForbiddenContent.


Response Examples

If the request was successful, you'll receive a response containing:
• list_total_found: The total amount of items found in the WebTV which matched the criteria (for paging purpose).
• list_total: The number of items in the returned list. This will normally match the limit or resultsPerPageFilter values.
• list: The item list.
Example:

?
{
    "list_total_found": "42",
    "list_total": 5,
    "list": [{
        "description": "",
        "id": "42",
        "img_poster": "http:\/\/......\/public\/common\/images\/_default_channel_portal_poster.gif",
        "title": "Portal",
        "type": "2",
        "type_name": "portal",
        "user_alias": "WebTV"
    }, {
        "description": "<p>Channel 1 description</p>",
        "id": "1",
        "img_poster": "http:\/\/......\/uploads\/images\/channel_1_1348912530_poster.jpg",
        "title": "Video Channel 1",
        "type": "0",
        "type_name": "video",
        "user_alias": "WebTV"
    }, {
        "description": "<p>Channel 6 description</p>",
        "id": "6",
        "img_poster": "http:\/\/......\/public\/common\/images\/_default_channel_poster.gif",
        "title": "Channel 6",
        "type": "0",
        "type_name": "video",
        "user_alias": "WebTV"
    }, {
        "description": "<p>Channel 9 description</p>",
        "id": "9",
        "img_poster": "http:\/\/......\/public\/common\/images\/_default_channel_poster.gif",
        "title": "Channel 9",
        "type": "0",
        "type_name": "video",
        "user_alias": "WebTV"
    }, {
        "description": "<p>Channel 5 description</p>",
        "id": "5",
        "img_poster": "http:\/\/......\/public\/common\/images\/_default_channel_poster.gif",
        "title": "Another Channel",
        "type": "0",
        "type_name": "video",
        "user_alias": "John"
    }]
}

If the request failed (for example, if the Credential does not have permission to GET), you'll receive a response like the following:

?
{
    "error"      : "REQUEST_ERROR",
    "error_long" : "Permission error: GET"
}

Possible Error Messages
Besides the general errors, this request can return the following errors:

• REQUEST_ERROR | No Channels/Pages were found





PHP Example Code

Preparing GET and POST data.

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// The GET vars
$GET_VARS = array(
                    "go"        => "channels",
                    "do"        => "list"
                    );
 
// The POST vars
$POST_VARS = array(
                    "fields"                => "id,title,description,img_poster",    // Include only id, title, description and img_poster
                    "paging"                => 1,            // Allow paging
                    "resultsPerPageFilter"  => 5,            // Return 5 results per page
                    "current_page"          => 1,            // Return the page No. 1
                    "statusFilter"          => "any"     // Include Channels/Pages with any status
                    );

Generating the salt, timestamp, signature and sending the request
*** The following code block is common to all signed requests ***

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// Collect the API Base URL and Credential info
$API_URL = "https://www.mywebtvdomain.tv/api.php";
$API_KEY_ID = "1b323a1cb879fd4e66530fbad07a32ee";
$API_SHARED_SECRET = "MWIzMjNhMWNiODc5ZmQ0ZTY2NTMwZmJhZDA3YTMyZWViOTQ3MDJiOGM2ZTU2NjE3"; // keep this safe!!!
 
// Generating salt and timestamp
$salt = md5(mt_rand());
$timestamp = time();
$signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true));
 
// Generating the validation signature
// - Default method: using base64_encode(hash_hmac(...))
$signature = base64_encode(hash_hmac('sha256', $salt.$timestamp, $API_SHARED_SECRET, true)); // comment this line if using the next method
// - Simplified method - available since v60: using md5().
//   This method requires the variable $API_SIGNATURE_GENERATION_MODE = 1; in the config/Config.inc.php file.
// $signature = md5($salt."-".$timestamp."-".$API_SHARED_SECRET); // you must "uncomment" this line when using the simplified method
 
// Append the timestamp, salt, key and signature to the GET vars
$GET_VARS["timestamp"] = $timestamp;    // UTC timestamp
$GET_VARS["salt"] = $salt;
$GET_VARS["key"] = $API_KEY_ID ;      // The API Key ID: This is public and is used by the API to identify the application;
$GET_VARS["signature"] = $signature;
 
// Create the request URL. Please note that if you do not use PHP buit in function
// to create the HTTP query then don't forget to URL encode the values
$REQUEST_URL = $API_URL."?".http_build_query($GET_VARS);
// The previous will build an URL like .../api.php?go=api_subject&do=api_action&etc...
 
// Create a new cURL resource and set the appropriate options
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $REQUEST_URL);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, false);
curl_setopt($ch, CURLOPT_POSTFIELDS, $POST_VARS);
// If your PHP host does not have a valid  SSL certificate, you will need to turn off SSL
// Certificate Verification. This is dangerous (!), and should only be done temporarily
// until a valid certificate has been installed
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); // Turns off verification of the SSL certificate.
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); // Turns off verification of the SSL certificate.
 
// Sending the request to the API
$response = curl_exec($ch);
 
// Processing the response
if (!$response) {
    echo 'API call failed';
}
else
{
    print_r(json_decode($response,true));
}


WebTV Solutions
Copyright © 2012 - 2025. WebTV Solutions. All rights reserved.