Docs

Embed LIVE

Introduction

The TikTok Embed LIVE Player lets you embed a TikTok LIVE room in an iframe. It supports URL-based player customization and an optional postMessage interface for host pages that need to control playback.

Access is application-based. Embedding is currently allowed only on approved domains. See Apply for Access below.

Get Started

Use the LIVE creator's TikTok username in the iframe URL:

<iframe
  width="720"
  height="405"
  src="https://www.tiktok.com/embed/live/@creatoracademy?autoplay=1&muted=1&controls=1&embed_domain=developers.tiktok.com"
  allow="autoplay; fullscreen"
  allowfullscreen
  loading="lazy"
  title="TikTok LIVE"
></iframe>

Set embed_domain to your host page domain. It is required, and the domain must be approved (see Apply for Access); otherwise the player renders a Blocked placeholder. Use loading="lazy" on the iframe so the player loads when it enters the viewport, rather than on initial page load.

The URL format is: https://www.tiktok.com/embed/live/@{username}. The leading @ is optional in the path. For example, both /embed/live/@creatoracademy and /embed/live/creatoracademy resolve to the same creator.

Customize the Player

You can customize the embedded LIVE player by appending query parameters to the iframe URL.

Name	Description	Default
autoplay	1: start playback automatically. 0: initialize the player and show the first frame without autoplay.	1
muted	1: start muted. 0: start unmuted when browser policy allows it. When autoplay=1, the player starts muted to satisfy browser autoplay policies.	1
controls	1: show the LIVE header and control bar. 0: hide player controls.	1
embed_domain	The host page domain. Required, and the domain must be approved for embedding (see Apply for Access).	empty

Example:

<iframe
  width="720"
  height="405"
  src="https://www.tiktok.com/embed/live/@creatoracademy?autoplay=0&muted=1&controls=1&embed_domain=developers.tiktok.com"
  allow="autoplay; fullscreen"
  allowfullscreen
  loading="lazy"
  title="TikTok LIVE"
></iframe>

Message the Player

The host page can control the iframe using Window.postMessage. Message payloads follow the same shape as the TikTok Embed Player protocol:

interface EmbeddedPlayerMessage<T = unknown> {
  'x-tiktok-player': true;
  type: string;
  value?: T;
}

Send messages to the iframe's contentWindow:

const iframe = document.querySelector('iframe');

iframe.contentWindow.postMessage(
  {
    type: 'play',
    'x-tiktok-player': true,
  },
  '*',
);

Host to Player Messages

Type	Value	Description
play	none	Starts or resumes LIVE playback.
pause	none	Pauses LIVE playback.
mute	none	Mutes the player and sets volume to 0.
unMute	none	Unmutes the player and restores volume when possible.

Listen to Player Events

The iframe posts playback events to the host page using the same x-tiktok-player marker.

window.addEventListener('message', (event) => {
  const message = event.data;
  if (!message || message['x-tiktok-player'] !== true) {
    return;
  }

  switch (message.type) {
    case 'onPlayerReady':
      console.log('LIVE player is ready');
      break;
    case 'onStateChange':
      console.log('LIVE player state:', message.value);
      break;
    case 'onMute':
      console.log('Muted:', message.value);
      break;
    case 'onVolumeChange':
      console.log('Volume:', message.value);
      break;
    case 'onPlayerError':
      console.error('LIVE player error:', message.value);
      break;
    default:
      break;
  }
});

Player to Host Messages

Type	Value	Description
onPlayerReady	none	The player instance is ready to receive commands.
onStateChange	number	Playback state. -1: init, 1: playing, 2: paused, 3: buffering.
onMute	boolean	Whether the player is muted.
onVolumeChange	number	Volume percentage from 0 to 100.
onPlayerError	{ errorCode: number; errorType: string }	Player error details.

Complete Example

<!DOCTYPE html>
<html lang="en">
  <body>
    <iframe
      id="tiktok-live-player"
      width="720"
      height="405"
      src="https://www.tiktok.com/embed/live/@creatoracademy?autoplay=0&muted=1&controls=1&embed_domain=yoursite.com"
      allow="autoplay; fullscreen"
      allowfullscreen
      loading="lazy"
      title="TikTok LIVE"
    ></iframe>

    <button onclick="sendPlayerMessage('play')">Play</button>
    <button onclick="sendPlayerMessage('pause')">Pause</button>
    <button onclick="sendPlayerMessage('mute')">Mute</button>
    <button onclick="sendPlayerMessage('unMute')">Unmute</button>

    <script>
      const iframe = document.getElementById('tiktok-live-player');

      function sendPlayerMessage(type, value) {
        const message = { type, 'x-tiktok-player': true };
        if (value !== undefined) {
          message.value = value;
        }
        iframe.contentWindow.postMessage(message, '*');
      }

      window.addEventListener('message', (event) => {
        const message = event.data;
        if (!message || message['x-tiktok-player'] !== true) {
          return;
        }
        console.log('TikTok LIVE event:', message.type, message.value);
      });
    </script>
  </body>
</html>

Apply for Access

Access to the LIVE Embed Player is application-based. Embedding is only allowed on approved domains. If your domain is not approved, the iframe renders a Blocked placeholder instead of the player.

To request access:

Submit a request through TikTok Developer Support with the following information:

Company / product name
Integration scenario and where the player will appear
The list of host domains you intend to embed on (multiple are supported)
Estimated PV / UV
Compliance and technical contacts

Your request is reviewed (typically within 5 business days).
Once approved, the requested domains are added to the allowlist. Integration confirmation follows (typically within 1 business day).

Notes on the allowlist:

Always send embed_domain set to your host page domain, and serve the embed over https://.
Exact domains (for example news.yoursite.com) and wildcard subdomains (for example *.yoursite.com) are supported. Top-level wildcards (for example *.com), IP addresses, and localhost are not.

Best Practices

Set an explicit iframe width and height. The player defaults to a 16:9 aspect ratio (for example 720 x 405), which suits both landscape and most placements.
Use loading="lazy" on the iframe so the player loads when it enters the viewport, rather than on initial page load.
Always pass embed_domain and make sure the host domain is on the allowlist (see Apply for Access).
Include allow="autoplay; fullscreen" so browser permissions match the player features.
Use autoplay=1&muted=1 when you want automatic playback.
Use autoplay=0&muted=1 when you want to show the first frame and wait for the user or host page to start playback.
Listen for onPlayerReady before sending playback commands when possible.

Was this document helpful?