Wistia

https://docs.wistia.com/
Admin
Wistia provides tools and APIs for developing with video, enabling programmatic access to accounts,...
Tokens:418,550
Snippets:3,375
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Popover Embed Setup

Source: https://docs.wistia.com/docs/player-popover-embed-api

Code examples for setting up a popover embed in HTML and React.

```APIDOC
## [HTML] Popover Embed Structure

### Description
Basic structure of a popover embed using the `player.js` script and a `<wistia-player>` web component with the `wistia-popover` option.

### Code Example
```html
<script src="https://fast.wistia.com/embed/abc123.js" async type="module"></script>
<script src="https://fast.wistia.com/player.js" async></script>

<wistia-player media-id="abc123" wistia-popover></wistia-player>
```
```

```APIDOC
## [React] Popover Embed Structure

### Description
Basic structure of a popover embed using the `WistiaPlayer` React component with the `wistiaPopover` prop.

### Code Example
```jsx
import { WistiaPlayer } from "@wistia/wistia-player-react"; 

export default function App() {
  return (
    <WistiaPlayer mediaId="abc123" wistiaPopover={true} />
  );
}
```
```

--------------------------------

### load-start event example (HTML + JavaScript)

Source: https://docs.wistia.com/docs/player-events

Listens for the load-start event on a Wistia player element and logs a message when the player starts loading. Requires the Wistia player script and a wistia-player element.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("load-start", () => {
    console.log("The player has started loading.");
  });
</script>
```

--------------------------------

### Install @wistia/wistia-player-react with npm

Source: https://docs.wistia.com/docs/player-react-component

Run this command in your project folder to install the package.

```shell
npm install @wistia/wistia-player-react

```

--------------------------------

### Install Wistia CLI via shell installer (macOS and Linux)

Source: https://docs.wistia.com/docs/wistia-cli-guide

Installs the Wistia CLI using a shell script on macOS and Linux. Downloads and runs the installer from the official repository.

```Bash
curl -fsSL https://raw.githubusercontent.com/wistia/wistia-cli/main/scripts/install.sh | bash

```

--------------------------------

### Verify Wistia CLI installation

Source: https://docs.wistia.com/docs/wistia-cli-guide

Checks that the Wistia CLI is installed correctly by displaying its version. Run this after installation.

```Bash
wistia --version

```

--------------------------------

### Install Wistia CLI via Windows PowerShell

Source: https://docs.wistia.com/docs/wistia-cli-guide

Installs the Wistia CLI on Windows using PowerShell. Downloads and runs the installer script from the official repository.

```PowerShell
iwr -useb https://raw.githubusercontent.com/wistia/wistia-cli/main/scripts/install.ps1 | iex

```

--------------------------------

### Install Wistia CLI via Homebrew (macOS and Linux)

Source: https://docs.wistia.com/docs/wistia-cli-guide

Installs the Wistia CLI using Homebrew on macOS and Linux. Run this command in a terminal after installing Homebrew.

```Bash
brew install wistia/tap/wistia-cli

```

--------------------------------

### Authorize URL Example

Source: https://docs.wistia.com/docs/authenticating-with-oauth2

Example request to the authorize URL. It redirects back to the Redirect URI with a code param on success, or error and error_description params on failure.

```text
https://app.wistia.com/oauth/authorize?client_id=mypublicconsumerkey&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp&response_type=code
```

--------------------------------

### Install @wistia/wistia-player npm package

Source: https://docs.wistia.com/docs/player-quick-start

Install the @wistia/wistia-player npm package in your project folder to use the <wistia-player> web component in your app's build pipeline.

```shell
npm install @wistia/wistia-player
```

--------------------------------

### setup()

Source: https://docs.wistia.com/docs/wistia-chooser

Displays the Chooser after initialization.

```APIDOC
## setup()

### Description
Displays the Chooser after initializing a Chooser object with all of its options.

### Method
setup()

### Parameters
None

### Request Example
```javascript
chooser.setup();
```

### Response
No return value.
```

--------------------------------

### GET /modern/channel_episodes

Source: https://docs.wistia.com/reference/get_channel-episodes

This code snippet documents the GET /modern/channel_episodes endpoint, including its query parameters, headers, request example, and response codes.

```APIDOC
## [GET] /modern/channel_episodes

### Description
Lists Channel Episodes belonging to an account. This endpoint can also be used to do a batch fetch based off of the hashed id.

### Method
GET

### Endpoint
https://api.wistia.com/modern/channel_episodes

### Parameters
#### Query Parameters
- **channel_id** (string) - Required - The hashed ID of the channel to grab channel episodes from.
- **sort_by** (string) - Optional - Ordering. Default is ID ASC. When using cursor pagination (see cursor param), only `id` and `created` are supported. All other sort_by options (`position`, `title`, `updated`, `published_at`) require offset pagination. Allowed: `position`, `title`, `created`, `updated`, `published_at`, `id`.
- **sort_direction** (integer) - Optional - Ordering Sort Direction (0 = desc, 1 = asc; default is 1). Allowed: `0`, `1`.
- **page** (integer) - Optional - The page number to retrieve. This cannot be combined with `cursor` pagination.
- **per_page** (integer) - Optional - The number of medias per page. Use this for both offset pagination and cursor pagination.
- **cursor** (object) - Optional - If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch.
- **media_id[]** (array of strings) - Optional - Filter by media id. Accepts either the numeric id or the hashed id of a media.
- **hashed_ids[]** (array of strings) - Optional - Filter by hashed id.
- **published** (boolean) - Optional - Filter by published status. Allowed: `true`, `false`.
- **title** (string) - Optional - Filter by channel episode name/title.

#### Headers
- **X-Wistia-API-Version** (string) - Required - Defaults to 2026-09.

### Request Example
```
curl --request GET \
     --url https://api.wistia.com/modern/channel_episodes \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Channel Episodes retrieval successful.

#### Error Responses
- **400** - Bad request
- **401** - Unauthorized, invalid or missing token
- **500** - Internal server error
```

--------------------------------

### GET /modern/webinars/{id}

Source: https://docs.wistia.com/reference/get_webinars-id

This snippet documents the GET endpoint for retrieving a webinar by its hashed ID. It includes the required path parameter, headers, and example request.

```APIDOC
## GET /modern/webinars/{id}

### Description
Returns the webinar associated with the hashed id.

### Method
GET

### Endpoint
https://api.wistia.com/modern/webinars/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The hashed ID of the webinar

#### Headers
- **X-Wistia-API-Version** (string) - Required - Defaults to 2026-09

### Request Example
```
curl --request GET \
     --url https://api.wistia.com/modern/webinars/id \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Successful response with the webinar details

#### Error Responses
- **401** - Unauthorized, invalid or missing token
- **403** - Webinar feature not available
- **404** - Webinar not found
- **500** - Internal server error
```

--------------------------------

### load-start event example (React)

Source: https://docs.wistia.com/docs/player-events

Uses the WistiaPlayer React component with the onLoadStart prop to handle the load-start event. Requires the @wistia/wistia-player-react package.

```jsx
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  function handleLoadStart() {
  	console.log("The player has started loading.");
  };
  
  return (
    <WistiaPlayer mediaId="abc123" onLoadStart={handleLoadStart} />
  );
}
```

--------------------------------

### GET /modern/analytics/webinars/{webinarId}/histograms

Source: https://docs.wistia.com/reference/get_analytics-webinars-webinarid-histograms

This code snippet documents the GET endpoint for retrieving webinar histograms, including its parameters, request example, and response codes.

```APIDOC
## [GET] /modern/analytics/webinars/{webinarId}/histograms

### Description
Retrieve engagement histogram data for a webinar. Returns arrays of per-time-bucket counts for attendees, chat activity, and visual focus, useful for rendering engagement visualizations.

### Method
GET

### Endpoint
https://api.wistia.com/modern/analytics/webinars/{webinarId}/histograms

### Parameters
#### Path Parameters
- **webinarId** (string) - Required - The hashed ID of the webinar.

#### Headers
- **X-Wistia-API-Version** (string) - Required - Defaults to 2026-09

### Request Example
```
curl --request GET \
     --url https://api.wistia.com/modern/analytics/webinars/webinarId/histograms \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Success response with webinar histogram data.

#### Error Responses
- **401** - Unauthorized, invalid or missing token
- **403** - Forbidden, token is valid but account does not have access to feature
- **404** - Webinar not found or does not belong to account
- **409** - The event has not yet reached a terminal state. Analytics are only available after the event has ended.
- **500** - Internal server error
- **503** - Analytics service is temporarily unavailable
```

--------------------------------

### Quick start: read-only Wistia CLI commands

Source: https://docs.wistia.com/docs/wistia-cli-guide

Shows the current account, lists media (most recent first), and lists folders. These are read-only commands to verify authentication.

```Bash
# Show the current account
wistia account get

# List media (most recent first)
wistia media list

# List folders (projects)
wistia folders list

```

--------------------------------

### Base image URL

Source: https://docs.wistia.com/docs/working-with-images

Base image URL used in the examples. It is the starting point for applying image parameters.

```Markdown
https://embed-ssl.wistia.com/deliveries/8669acc30fdfe63a25ad9d32f5a9f664.jpg
```

--------------------------------

### Listen for 'play' event (HTML+JS and React)

Source: https://docs.wistia.com/docs/player-events

Listen for the 'play' event, which fires when the media's state changes to 'playing'. The HTML+JavaScript example uses addEventListener; the React example uses the onPlay prop. Both log a message when playback starts.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("play", () => {
    console.log("The video was just played!");
  });
</script>
```

```jsx
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  function handlePlay() {
    console.log("The video was just played!");
  };
  
  return (
    <WistiaPlayer mediaId="abc123" onPlay={handlePlay} />
  );
}
```

--------------------------------

### Share plugin example (Legacy E-v1.js)

Source: https://docs.wistia.com/docs/embed-options-and-plugins

Adds a Share control to the video player using the share plugin with the legacy E-v1.js embed. Configure the plugin options in the _wq.push call and include the E-v1.js script and the wistia_embed div.

```html
<script>
window._wq = window._wq || [];
_wq.push({
  id: "5bbw8l7kl5",
  options: {
    plugin: {
      share: {
        channels: "facebook-twitter",
        tweetText: "Check out this awesome video called {video_name}!",
        overrideUrl: "false"
      }
    }
  }
});
</script>
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_5bbw8l7kl5" style="height:360px;position:relative;width:640px"></div>
```

--------------------------------

### getSubtitlesScale: Get captions scale

Source: https://docs.wistia.com/docs/javascript-player-api

Returns the multiplier scaling the size of captions. The example shows setting the scale to 1.2 and then retrieving it.

```javascript
video.plugin('captions').then(function (captions) {
  captions.setSubtitlesScale(1.2);
  captions.getSubtitlesScale(); // returns 1.2
});
```

--------------------------------

### GET /modern/review_bundles

Source: https://docs.wistia.com/reference/get_review-bundles

API documentation for the List Review Bundles endpoint, including query parameters, headers, request example, and response codes.

```APIDOC
## GET /modern/review_bundles

### Description
Lists review bundles belonging to an account. This endpoint can also be used to do a batch fetch based off of the hashed id, or to find the bundles that include a given media or any media from a folder.

### Method
GET

### Endpoint
https://api.wistia.com/modern/review_bundles

### Parameters
#### Query Parameters
- **hashed_ids[]** (array of strings) - Optional - Restrict the results to the review bundles with these hashed IDs.
- **name** (string) - Optional - Restrict the results to review bundles whose name contains this value (case-insensitive).
- **media_hashed_id** (string) - Optional - Restrict the results to review bundles that include the media with this hashed ID.
- **folder_hashed_id** (string) - Optional - Restrict the results to review bundles that include any media from the folder with this hashed ID.
- **sort_by** (string) - Optional - Field to order by. The default is id. Allowed: `id`, `name`, `created`, `updated`.
- **sort_direction** (integer) - Optional - Direction to order by. (0 = desc, 1 = asc; default is 1). Allowed: `0`, `1`.
- **page** (integer) - Optional - The page number to retrieve. This cannot be combined with `cursor` pagination.
- **per_page** (integer) - Optional - The number of medias per page. Use this for both offset pagination and cursor pagination.
- **cursor** (object) - Optional - If `cursor[enabled]` is set to 1 then cursor pagination is enabled and the first set of records are fetched up to the `per_page`. Cursor pagination will also be turned on if `cursor[before]` or `cursor[after]` are set. Records returned will have a `cursor` property set which can be used to fetch more records in the same `sort_by` ordering. The cursor value of the last record can be used to fetch records after the current result set and the cursor of the first record can be used to fetch records before the result set. NOTE: a cursor value is only valid if the `sort_by` value hasn't changed from the last fetch.

#### Headers
- **X-Wistia-API-Version** (string) - Required - Defaults to 2026-09.

### Request Example
```
curl --request GET \
     --url https://api.wistia.com/modern/review_bundles \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Review Bundles retrieval successful

#### Error Responses
- **400** - Bad request
- **401** - Unauthorized, invalid or missing token
- **403** - Forbidden, token is valid but account does not have access to feature
- **500** - Internal server error
```

--------------------------------

### Chaptering Example with Time Parameters

Source: https://docs.wistia.com/docs/embed-links

HTML example showing how to create chapter links for a single video by using the time embed option in the href. All links share the same hashed_id as the embedded video.

```HTML
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_30q7n48g4f" style="height:360px;width:640px">&nbsp;</div>
<a href="#wistia_30q7n48g4f?time=0">Make French Toast @ 0</a><br/>
<a href="#wistia_30q7n48g4f?time=10">Make French Toast @ 10</a><br/>
<a href="#wistia_30q7n48g4f?time=20">Make French Toast @ 20</a><br/>
<a href="#wistia_30q7n48g4f?time=30">Make French Toast @ 30</a><br/>
```

--------------------------------

### Start Account Trial with cURL

Source: https://docs.wistia.com/reference/account-trials

Use this cURL command to start a business-tier trial on the current account. Requires an API token with 'Read, update & delete anything' permission. The X-Wistia-API-Version header is required and defaults to 2026-09.

```shell
curl --request POST \
     --url https://api.wistia.com/modern/account/trials \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

--------------------------------

### getPlugin(name) - HTML and React examples

Source: https://docs.wistia.com/docs/player-methods

Gets a plugin from the player. The plugin is retrieved as soon as the player embed has an api. The name parameter is required.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  
  // As soon as the player embed has an api, get an existing plugin.
  player.addEventListener("api-ready", () => {
    player.getPlugin("turnstile");
  });
</script>
```

```jsx
import { useRef } from "react";
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  const player = useRef(null);
  
  // As soon as the player embed has an api, get an existing plugin.
  function handleApiReady() {
    if (player.current === null) { return; }
    player.current.getPlugin("turnstile");
  }
  
  return (
    <WistiaPlayer ref={player} mediaId="abc123" onApiReady={handleApiReady} />
  );
}
```

--------------------------------

### routeStrategy=path routing rule example for /my/blog

Source: https://docs.wistia.com/docs/channel-embeds

Example routing rule to support routeStrategy=path for a specific blog path. Path parts past /my/blog should also route to /my/blog.

```text
/my/blog/* -> /my/blog
```

--------------------------------

### height() - Get video container height

Source: https://docs.wistia.com/docs/javascript-player-api

Returns the current height of the video container in pixels. Example sets the height of a div to match the video.

```JavaScript
// e.g. set the height of <div id="next_to_video"> to match the video.
$("#next_to_video").height(video.height());
```

--------------------------------

### percentWatched() - Get percent watched

Source: https://docs.wistia.com/docs/javascript-player-api

Returns the percent of the video watched as a decimal between 0 and 1. Equivalent to secondsWatched() / Math.floor(duration()). Example uses it to prompt before navigating.

```JavaScript
$("#next_page").click(function() {
  if (video.percentWatched() > 0.9 && video.percentWatched() < 0.99) {
    if (confirm("But you're so closed to finishing the video -- there's a prize at the end! Move on anyway?")) {
      goToNextPage();
    }
  } else {
    goToNextPage();
  }
});
```

--------------------------------

### videoThumbnail plugin example (Legacy E-v1.js)

Source: https://docs.wistia.com/docs/embed-options-and-plugins

Sets up a looping video thumbnail using the videoThumbnail plugin with the legacy E-v1.js embed. Configure the plugin options in the _wq.push call and include the E-v1.js script and the wistia_embed div.

```html
<script>
  window._wq = window._wq || [];
  _wq.push({
    id: "xz77w5ts33",
    options: {
      plugin: {
        videoThumbnail: {
          on: true,
          hashedId: "xz77w5ts33",
          trimStart: 13,
          trimEnd: 18,
          async: false,
        }
      }
    }
  });
</script>
<script src="https://fast.wistia.com/assets/external/E-v1.js" async></script>
<div
  class="wistia_embed wistia_async_xz77w5ts33"
  style="height:360px;position:relative;width:640px"
></div>
```

--------------------------------

### hashedId: Get video hashed ID

Source: https://docs.wistia.com/docs/javascript-player-api

Returns the hashed ID uniquely identifying the video in Wistia. The example passes it along with the video name to a custom function.

```javascript
recordPlayedVideo(video.hashedId(), video.name());
```

--------------------------------

### ready()

Source: https://docs.wistia.com/docs/javascript-player-api

Method to check if the video is ready to be played.

```APIDOC
## ready()

### Description
Returns true if the video is ready to be played, false if it is not. A video is "ready" if it has data from the server, is embedded in the DOM, its JavaScript interface is available, metadata required to play is loaded, and it is not hidden via `display: none`.

### Method
ready()

### Parameters
None

### Returns
- **Boolean** - `true` if the video is ready to be played, `false` otherwise.
```

--------------------------------

### enter-fullscreen event example (HTML + JavaScript)

Source: https://docs.wistia.com/docs/player-events

Listens for the enter-fullscreen event on a Wistia player element and logs a message when the video enters fullscreen. Requires the Wistia player script and a wistia-player element with a media-id.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>

<script>
  const player = document.getElementById("my-player");
  player.addEventListener("enter-fullscreen", () => {
    console.log("The video is now playing in fullscreen.");
  });
</script>
```

--------------------------------

### Resolve Resource URLs with cURL

Source: https://docs.wistia.com/reference/get_resource-urls

A GET request to the resource_urls endpoint using cURL. This example specifies the resource type as 'media' and sets the required API version header.

```shell
curl --request GET \
     --url 'https://api.wistia.com/modern/resource_urls?type=media' \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

--------------------------------

### look() - Get viewer's current look direction

Source: https://docs.wistia.com/docs/javascript-player-api

For 360° video only. Returns an object with current heading, pitch, and fov in degrees. Example shows a sample return value.

```JavaScript
video.look() //=> { heading: 90, pitch: 5, fov: 120 }
```

--------------------------------

### Iframe src with simple options

Source: https://docs.wistia.com/docs/iframe-embed-options

Shows how to set multiple options on an iframe src using query params. The example sets videoFoam, autoPlay, and playerColor.

```HTML
<!-- example_iframe_src_with_options.html -->
//fast.wistia.net/embed/iframe/g5pnf59ala?videoFoam=false&autoPlay=true&playerColor=ff69b4
```

--------------------------------

### HTML: Initialize player with email

Source: https://docs.wistia.com/docs/player-attributes-and-properties

Sets the email attribute to 'test@wistia.com' on the wistia-player element.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" email="test@wistia.com"></wistia-player>
```

--------------------------------

### HTML: Initialize player with value (media-id)

Source: https://docs.wistia.com/docs/player-attributes-and-properties

Initialize a Wistia player with the `media-id` attribute to specify the media to display.

```APIDOC
## [HTML] Initialize player with value

### Description
Initialize a Wistia player with the `media-id` attribute to specify the media to display.

### Method
HTML

### Endpoint
`<wistia-player>` element

### Parameters
#### Attributes
- `media-id` (string) - Required - The unique ID of the media.

### Request Example
```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>
```
```

--------------------------------

### Get popover width with video.popover.width()

Source: https://docs.wistia.com/docs/popover-embed-customization

Retrieves the current width of the popover container (usually the thumbnail) in pixels. The example sets the width of a div with id "next_to_video" to match the video's popover width.

```JavaScript
// e.g. set the width of <div id="next_to_video"> to match the video.
$("#next_to_video").width(video.popover.width());
```

--------------------------------

### Include Wistia Uploader with dropIn and accessToken

Source: https://docs.wistia.com/docs/uploader

Drop-in Wistia Uploader setup. Replace accessToken and projectId with your own values; create the project via the Data API or the Create menu, and generate an access token with the "Upload video" permission in API Access.

```HTML
<script src="//fast.wistia.com/assets/external/api.js" async></script>
<link rel="stylesheet" href="//fast.wistia.com/assets/external/uploader.css" />
<div id="wistia_uploader" style="height:360px;width:640px;" />
<script>
window._wapiq = window._wapiq || [];
_wapiq.push(function(W) {
  window.wistiaUploader = new W.Uploader({
    accessToken: "ACCESS_TOKEN_GOES_HERE",
    dropIn: "wistia_uploader",
    projectId: "PROJECT_ID_GOES_HERE"
  });
});
</script>
```

--------------------------------

### Get popover height with video.popover.height()

Source: https://docs.wistia.com/docs/popover-embed-customization

Retrieves the current height of the popover container (usually the thumbnail) in pixels. The example sets the height of a div with id "next_to_video" to match the video's popover height.

```JavaScript
// e.g. set the height of <div id="next_to_video"> to match the video.
$("#next_to_video").height(video.popover.height());
```

--------------------------------

### GET /modern/stats/medias/{mediaId}/engagement

Source: https://docs.wistia.com/reference/get_stats-medias-mediaid-engagement

This snippet documents the Show Media Engagement endpoint, which retrieves engagement data for a specific video. It includes the HTTP method, endpoint URL, path parameters, required headers, and example request.

```APIDOC
## [GET] /modern/stats/medias/{mediaId}/engagement

### Description
Retrieve engagement data for a video. This endpoint provides engagement data for a specific video identified by its media-id.

### Method
GET

### Endpoint
https://api.wistia.com/modern/stats/medias/{mediaId}/engagement

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The hashed ID or ID of the video for which you want to retrieve engagement data.

#### Headers
- **X-Wistia-API-Version** (string) - Required - Defaults to 2026-09.

### Request Example
```
curl --request GET \
     --url https://api.wistia.com/modern/stats/medias/mediaId/engagement \
     --header 'X-Wistia-API-Version: 2026-09' \
     --header 'accept: application/json'
```

### Response
#### Success Response (200)
Success response with the engagement data of the video.

#### Error Responses
- **401** - Unauthorized, invalid or missing token
- **403** - Forbidden, token is valid but account does not have access to feature
- **404** - Media not found or does not belong to account
- **500** - Internal server error

```

--------------------------------

### captions-change event - React

Source: https://docs.wistia.com/docs/player-events

Listens for the captions-change event on a Wistia player using the React component. The event fires when a different caption setting is selected. The example reads the event.detail object to get isVisible and language properties and logs a message.

```React
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  function handleCaptionsChange(event) {
    const { isVisible, language } = event.detail;
    console.log(`The captions of this media are now ${isVisible ? "visible" : "hidden"} in ${language} language.`);

    // Example output: "The captions of this media are now visible in eng language."
  };
  
  return (
    <WistiaPlayer mediaId="abc123" onCaptionsChange={handleCaptionsChange} />
  );
}
```

--------------------------------

### Initialize player with media-id attribute

Source: https://docs.wistia.com/docs/player-attributes-and-properties

Initialize a player with the media-id attribute. The media-id is required and must be the unique ID of a media.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123"></wistia-player>
```

--------------------------------

### Embed Link Anatomy with time Option

Source: https://docs.wistia.com/docs/embed-links

Shows the anatomy of an embed link: a # prefix, the video's 10-character hashed ID, and optional embed options separated by a ?. The example uses the time=30 option to start playback at 30 seconds.

```html
<!-- embed_link_anatomy.html -->
<a href="#wistia_30q7n48g4f?time=30">Make French Toast</a>
<!-- prefix  hashed ID  embed options -->
```

--------------------------------

### Playlist Link Example with playlistLinks=auto

Source: https://docs.wistia.com/docs/embed-links

HTML example showing how to create a playlist of Wistia videos using the playlistLinks=auto embed option. The first embed link must have the same hashed_id as the embedded video. When one video ends, the next plays automatically.

```HTML
<!-- example_playlist_link.html -->
<script charset="ISO-8859-1" src="//fast.wistia.com/assets/external/E-v1.js" async></script>
<div class="wistia_embed wistia_async_30q7n48g4f playlistLinks=auto" style="height:360px;width:640px">&nbsp;</div>
<a href="#wistia_30q7n48g4f">Make French Toast</a><br/>
<a href="#wistia_342jss6yh5?time=30">Wistia Team Intro</a><br/>
```

--------------------------------

### Initialize player with popover-content="thumbnail"

Source: https://docs.wistia.com/docs/player-popover-embed-api

Initialize a Wistia popover player with popover-content set to "thumbnail" (the default). The thumbnail is rendered in the container, cropped to fit with no black bars.

```html
<script src="https://fast.wistia.com/player.js" async></script>
<wistia-player id="my-player" media-id="abc123" wistia-popover popover-content="thumbnail"></wistia-player>
```

```jsx
import { WistiaPlayer } from "@wistia/wistia-player-react";
<WistiaPlayer id="my-player" mediaId="abc123" wistiaPopover={true} popoverContent="thumbnail" />
```

--------------------------------

### conversion event - React

Source: https://docs.wistia.com/docs/player-events

Listens for the conversion event on a Wistia player using the React component. The event fires when an email is entered into a Wistia Form. The example reads the event.detail object to get type, email, firstName, and lastName properties and logs a message.

```React
import { WistiaPlayer } from "@wistia/wistia-player-react";

export default function App() {
  function handleConversion(event) {
    const { type, email, firstName, lastName } = event.detail;
    console.log(`The viewer ${firstName} ${lastName} entered their email address ${email} into the ${type} Wistia Form.`);

    // Example output: The viewer Lorem Ipsum entered their email address test@gmail.com into the post-roll-email Wistia Form.
  };
  
  return (
    <WistiaPlayer mediaId="abc123" onConversion={handleConversion} />
  );
}
```
Tokens:
Raw