Contents

Extensions Reference

Introduction

This reference covers Extensions endpoints, the JavaScript helper, client query parameters, and the JWT schema.

Endpoints

Endpoint Description
Create Extension Secret

Creates a new secret for a specified extension, identified by a client ID value assigned to the extension when it is created. Also rotates any current secrets out of service, with enough time for extension clients to gracefully switch over to the new secret. The delay period, between the generation of the new secret and its use by Twitch, is specified by a required parameter, activation_delay_secs. The default delay is 300 (5 minutes); if a value less than this is specified, Twitch uses 300.

Use this function only when you are ready to install the new secret it returns.

Note: You get the initial secret via the Twitch developer site (see “Creating Your First Secret” in Building Extensions). Use this endpoint to rotate the secret later, if desired.

Get Extension Secret

Retrieves a specified extension’s secret data: a version and an array of secret objects. The extension is identified by a client ID value assigned to the extension when it is created. Each secret object returned contains a base64-encoded secret, a UTC timestamp when the secret becomes active, and a timestamp when the secret expires.

Revoke Extension Secrets

Deletes all secrets associated with a specified extension, identified by a client ID value assigned to the extension when it is created.

This immediately breaks all clients until both a new Create Extension Secret is executed and the clients manually refresh themselves. Use this only if a secret is compromised and must be removed immediately from circulation.

Get Live Channels with Extension Activated

Returns one page of live channels that have installed and activated a specified extension, identified by a client ID value assigned to the extension when it is created. A channel that just went live may take a few minutes to appear in this list, and a channel may continue to appear on this list for a few minutes after it stops broadcasting.

Set Extension Required Configuration

Enable activation of a specified extension, after any required broadcaster configuration is correct. The extension is identified by a client ID value assigned to the extension when it is created. This is for extensions that require broadcaster configuration before activation. Use this if, in extension Capabilities, you select Custom/My Own Service.

Set Extension Configuration Segment

Sets a single configuration segment (any type). The segment type is specified by a required body parameter.

Each segment is limited to 5 KB and can be set at most 20 times per minute. Updates to this data are not delivered to Extensions that have already rendered.

Get Extension Channel Configuration

Gets the developer and broadcaster configuration segments for a specified channel.

Each channel can be retrieved at most 20 times per minute.

Get Extension Configuration Segment

Gets a broadcaster or developer configuration segment for a specified channel, or the global configuration segment.

Each channel can be retrieved at most 20 times per minute.

Send Extension PubSub Message

Twitch provides a publish-subscribe system for your EBS (Extension Back-end Service) to communicate with both the broadcaster and viewers. Calling this endpoint forwards your message using the same mechanism as the send JavaScript helper function. A message can be sent to either a specified channel or globally (all channels on which your extension is active).

Send Extension Chat Message

Sends a specified chat message to a specified channel. The message will appear in the channel’s chat as a normal message. The “username” of the message is the extension name you specified when you created the extension.

The extension is identified by a client ID value assigned to the extension when it is created.

There is a limit of 12 messages per minute, per channel. Extension chat messages use the same rate-limiting functionality as the New Twitch API (see Rate Limits). The maximum message size is 280 characters.

Create Extension Secret

Creates a new secret for a specified extension, identified by a client ID value assigned to the extension when it is created. Also rotates any current secrets out of service, with enough time for extension clients to gracefully switch over to the new secret. The delay period, between the generation of the new secret and its use by Twitch, is specified by a required parameter, activation_delay_secs. The default delay is 300 (5 minutes); if a value less than this is specified, Twitch uses 300.

Use this function only when you are ready to install the new secret it returns.

Note: You get the initial secret via the Twitch developer site (see “Creating Your First Secret” in Building Extensions). Use this endpoint to rotate the secret later, if desired.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

URL

POST https://api.twitch.tv/extensions/<client ID>/auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This creates a new secret for extension pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDIyOTM3MzUsInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.JLQWkGh86g-3Q1Ki-aWABeNQYgYYQIOYmpmNq3bTAVM' \
-H 'Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'Content-Type: application/json' \
-d '{"activation_delay_secs": 300}' \
-X POST https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/auth/secret

Example Response

{
  "format_version": 1,
  "secrets": [
    {
      "active": "2017-08-09T15:49:41.553002151Z",
      "content": "TK4/j3AEJ9f14jODdxhX0kVcD/h6lKA9Sxz/CCUtVLI=",
      "expires": "2017-08-09T16:55:35.894628749Z"
    },
    {
      "active": "2017-08-09T15:50:35.90304258Z",
      "content": "B6OJ/WWA/bTsCbGYzaZwq3KdgDsC1485h4BKdnIBGOE=",
      "expires": "2117-07-16T15:50:35.90304258Z"
    }
  ]
}

Get Extension Secret

Retrieves a specified extension’s secret data: a version and an array of secret objects. The extension is identified by a client ID value assigned to the extension when it is created. Each secret object returned contains a base64-encoded secret, a UTC timestamp when the secret becomes active, and a timestamp when the secret expires.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

URL

GET https://api.twitch.tv/extensions/<client ID>/auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This gets the secret data for extension pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDIyOTM3MzUsInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.s_uedGCjGzlD5CpTQ_IpqUiQuB12dGsUIdbarLn3LrU' \
-H 'Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-X GET https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/auth/secret

Example Response

{
  "format_version": 1,
  "secrets": [
    {
      "active": "2017-08-09T15:49:41.553002151Z",
      "content": "TK4/j3AEJ9f14jODdxhX0kVcD/h6lKA9Sxz/CCUtVLI=",
      "expires": "2017-08-09T16:55:35.894628749Z"
    },
    {
      "active": "2017-08-09T15:50:35.90304258Z",
      "content": "B6OJ/WWA/bTsCbGYzaZwq3KdgDsC1485h4BKdnIBGOE=",
      "expires": "2117-07-16T15:50:35.90304258Z"
    }
  ]
}

Revoke Extension Secrets

Deletes all secrets associated with a specified extension, identified by a client ID value assigned to the extension when it is created.

This immediately breaks all clients until both a new Create Extension Secret is executed and the clients manually refresh themselves. Use this only if a secret is compromised and must be removed immediately from circulation.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

URL

DELETE https://api.twitch.tv/extensions/<client ID>/auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This deletes all secrets associated with extension pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDIyOTM3MzUsInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.s_uedGCjGzlD5CpTQ_IpqUiQuB12dGsUIdbarLn3LrU' \
-H 'Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-X DELETE https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/auth/secret

Example Response

204 Success

Get Live Channels with Extension Activated

Returns one page of live channels that have installed and activated a specified extension, identified by a client ID value assigned to the extension when it is created. A channel that just went live may take a few minutes to appear in this list, and a channel may continue to appear on this list for a few minutes after it stops broadcasting.

Authentication

None

URL

GET https://api.twitch.tv/extensions/<client ID>/live_activated_channels

Required Query String Parameters

None

Optional Query String Parameter

Name Type Description
cursor string Cursor value returned from a prior call to this endpoint. The cursor specifies the starting point of the results. If this is not specified, the start of the live channel list is returned.

Example Request

This gets the live channels that have installed and activated extension pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H "Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t" \
-X GET https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/live_activated_channels

Example Response

{
  "channels": [
    {
      "game": "PLAYERUNKNOWN'S BATTLEGROUNDS",
      "id": "27419011",
      "title": "Still hunting for chicken!",
      "username": "TravistyOJ",
      "view_count": "943",
    }
  ]
  "cursor": "OTk1MjQwNzFAMjR1NjJraW01bW4wc2xod2lnZHQ3djR5Ymt3ZWY1QDEuMC4z"
}

Set Extension Required Configuration

Enable activation of a specified extension, after any required broadcaster configuration is correct. The extension is identified by a client ID value assigned to the extension when it is created. This is for extensions that require broadcaster configuration before activation. Use this if, in extension Capabilities, you select Custom/My Own Service.

You enforce required broadcaster configuration with a required_configuration string in the extension manifest. The contents of this string can be whatever you want. Once your EBS determines that the extension is correctly configured on a channel, use this endpoint to provide that same configuration string, which enables activation on the channel. The endpoint URL includes the channel ID of the page where the extension is iframe embedded.

If a future version of the extension requires a different configuration, change the required_configuration string in your manifest. When the new version is released, broadcasters will be required to re-configure that new version.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

URL

PUT https://api.twitch.tv/extensions/<client ID>/<extension version>/required_configuration?channel_id=<channel ID>

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This enables activation of extension pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDIyOTg3ODksInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.sKjspl1jw0XGcpjF8vo2IcS2dQLQU_rSsmRCnrohCP4' \
-H 'Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'Content-Type: application/json' \
-d '{"required_configuration": "RCS-1"}' \
-X PUT https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/0.0.1/required_configuration?channel_id=27419011

Example Response

204 Success

Set Extension Configuration Segment

Sets a single configuration segment (any type). The segment type is specified by a required body parameter.

Each segment is limited to 5 KB and can be set at most 20 times per minute. Updates to this data are not delivered to Extensions that have already rendered.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

Note: Your signed JWT must include the exp, user_id, and role fields, documented in JWT Schema. The role value must be external. For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
}

URL

PUT https://api.twitch.tv/extensions/<client ID>/configurations

Required Body Parameters

NameTypeDescription
channel_idstringID of the channel that the configuration is for. Required if segment is broadcaster or developer. Not allowed if segment is global.
segmentstringConfiguration segment type. Valid values: "global", "developer", "broadcaster".

Optional Body Parameters

NameTypeDescription
contentstringString-encoded configuration.
versionstringConfiguration version with which the segment is stored.

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request #1

This sets the global configuration segment for the extension identified by client ID pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Mzk2NDYyNTksInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.tggCMefJ_OL392z2dN25RykjYYsPxGYuUoGXEHKAQN0' \
-H 'client-id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'content-type: application/json' \
-d '{"segment":"global","version":"1","content":"{\"foo\":\"bar\"}"}'\
-X PUT https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/configurations/

Example Response #1

204 Success

Example Request #2

This sets the broadcaster configuration segment for the extension identified by client ID pxifeyz7vxk9v6yb202nq4cwsnsp1t and channel ID 27419011.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Mzk2NDYyNTksInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.tggCMefJ_OL392z2dN25RykjYYsPxGYuUoGXEHKAQN0' \
-H 'client-id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'content-type: application/json' \
-d '{"segment":"broadcaster","channel_id":"27419011","version":"1","content":"{\"foo\":\"bar\"}"}' \
-X PUT https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/configurations/

Example Response #2

204 Success

Get Extension Channel Configuration

Gets the developer and broadcaster configuration segments for a specified channel.

Each channel can be retrieved at most 20 times per minute.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

Note: Your signed JWT must include the exp, user_id, and role fields, documented in JWT Schema. The role value must be external. For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
}

URL

GET https://api.twitch.tv/extensions/<client ID>/configurations/channels/<channel ID>

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This gets the developer and broadcaster configuration segments for the channel identified by ID 27419011.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Mzk2NDYyNTksInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.tggCMefJ_OL392z2dN25RykjYYsPxGYuUoGXEHKAQN0' \
-H 'client-id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'content-type: application/json'
-X GET https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/configurations/segments/broadcaster?channel_id=27419011

Example Response

{
  "broadcaster:27419011": {
    "segment": {
      "segment_type": "broadcaster",
      "channel_id": "27419011"
    },
    "record": {
      "content": "{\"foo\":\"bar\"}",
      "version": "1"
    }
  },
  "developer:27419011": {
    "segment": {
      "segment_type": "developer",
      "channel_id": "27419011"
    },
    "record": {
      "content": "{\"foodev\":\"bardev\"}",
      "version": "1"
    }
  }
}

Get Extension Configuration Segment

Gets a broadcaster or developer configuration segment for a specified channel, or the global configuration segment.

Each segment can be retrieved at most 20 times per minute.

Authentication

Signed JWT created by the EBS, following the requirements documented in “Signing the JWT” (in Building Extensions)

Note: Your signed JWT must include the exp, user_id, and role fields, documented in JWT Schema. The role value must be external. For example:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
}

URLs

GET https://api.twitch.tv/extensions/<client ID>/configurations/segments/broadcaster

GET https://api.twitch.tv/extensions/<client ID>/configurations/segments/developer

GET https://api.twitch.tv/extensions/<client ID>/configurations/segments/global

Required Query String Parameter

NameTypeDescription
channel_idstringID of the channel that the configuration is for. Required for broadcaster or developer segments. Not allowed for global segments.

Optional Query String Parameters

None

Example Request

This gets the global configuration segment for the extension identified by client ID pxifeyz7vxk9v6yb202nq4cwsnsp1t.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1Mzk2NDYyNTksInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.tggCMefJ_OL392z2dN25RykjYYsPxGYuUoGXEHKAQN0' \
-H 'client-id: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'content-type: application/json' \
-X GET https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/configurations/segments/global

Example Response

{
  "global:": {
    "segment": {
      "segment_type": "global"
    },
    "record": {
      "content": "{\"foo\":\"bar\"}",
      "version": "1"
    }
  }
}

Send Extension PubSub Message

Twitch provides a publish-subscribe system for your EBS to communicate with both the broadcaster and viewers. Calling this endpoint forwards your message using the same mechanism as the send JavaScript helper function. A message can be sent to either a specified channel or globally (all channels on which your extension is active).

Authentication

Signed JWT (Twitch or EBS JWTs are allowed)

Note: Your signed JWT must include the channel_id and pubsub_perms fields, documented in JWT Schema. For example, to send to a channel:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "27419011",
  "pubsub_perms": {
    "send":[
      "broadcast"
    ]
  }
}

To send globally:

{
  "exp": 1503343947,
  "user_id": "27419011",
  "role": "external",
  "channel_id": "all",
  "pubsub_perms": {
    "send":[
      "global"
    ]
  }
}

URLs

POST https://api.twitch.tv/extensions/message/<channel ID>

POST https://api.twitch.tv/extensions/message/all

Required Body Parameters

NameTypeDescription
content_typestringValid value: "application/json".
messagestringYour message to be sent.
targetsArray of stringsValid values: "broadcast", "global".

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request #1 (Channel)

This forwards your specified message to channel 27419011.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDMzNDM5NDcsInVzZXJfaWQiOiIyNzQxOTAxMSIsImNoYW5uZWxfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCIsInB1YnN1Yl9wZXJtcyI6eyJzZW5kIjpbIioiXX19.TiDAzrq58XczdymAozwsdVilRkjr9KN8C0pCv7px-FM" \
-H "Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t" \
-H "Content-Type: application/json" \
-d '{"content_type":"application/json", "message":"{\"foo\":\"bar\"}", "targets":["broadcast"]}' \
-X POST https://api.twitch.tv/extensions/message/27419011

Example Response #1

204 Success

Example Request #2 (Global)

This forwards your specified message to all channels on which your extension is active.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDMzNDM5NDcsInVzZXJfaWQiOiIyNzQxOTAxMSIsImNoYW5uZWxfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCIsInB1YnN1Yl9wZXJtcyI6eyJzZW5kIjpbIioiXX19.TiDAzrq58XczdymAozwsdVilRkjr9KN8C0pCv7px-FM" \
-H "Client-Id: pxifeyz7vxk9v6yb202nq4cwsnsp1t" \
-H "Content-Type: application/json" \
-d '{"content_type":"application/json", "message":"{\"foo\":\"bar\"}", "targets":["global"]}' \
-X POST https://api.twitch.tv/extensions/message/all

Example Response #2

204 Success

Send Extension Chat Message

Sends a specified chat message to a specified channel. The message will appear in the channel’s chat as a normal message. The “username” of the message is the extension name you specified when you created the extension.

The extension is identified by a client ID value assigned to the extension when it is created.

There is a limit of 12 messages per minute, per channel. Extension chat messages use the same rate-limiting functionality as the New Twitch API (see Rate Limits). The maximum message size is 280 characters.

Authentication

Signed JWT created by the EBS, following the requirements documented in Signing the JWT (in Building Extensions) or Twitch JWT containing the broadcaster role. The channel_id inside the JWT must match the channel ID in the request URL.

URL

POST https://api.twitch.tv/extensions/<client ID>/<extension version>/channels/<channel ID>/chat

Required Query String Parameters

None

Optional Query String Parameters

None

Example Request

This sends the chat message “This is a normal message” to channel 27419011.

curl -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MDMzNDM5NDcsImNoYW5uZWxfaWQiOiIyNzQxOTAxMSIsInVzZXJfaWQiOiIyNzQxOTAxMSIsInJvbGUiOiJleHRlcm5hbCJ9.JZ1fpqMIfEa7Ry4oLVtB_we4qxr4Wc_8t_6TepNOtiY' \
-H 'Client-ID: pxifeyz7vxk9v6yb202nq4cwsnsp1t' \
-H 'Content-Type: application/json' \
-d '{ "text": "This is a normal message." }' \
-X POST https://api.twitch.tv/extensions/pxifeyz7vxk9v6yb202nq4cwsnsp1t/1.0.1/channels/27419011/chat

Example Response

204 No Content

JavaScript Helper

NamespaceSee ...
window.Twitch.extHelper: Extensions
window.Twitch.ext.actionsHelper: Actions
window.Twitch.ext.configurationHelper: Configuration
window.Twitch.ext.featuresHelper: Feature Flags
window.Twitch.ext.bitsHelper: Bits

Helper: Extensions

The Extensions JavaScript helper uses these strings:

  • version — This encodes the Helper version in 1.1.1 (semantic versioning) format.
  • environment — This encodes the environment. For external users, this is always production.

onAuthorized

twitch.ext.onAuthorized: function(authCallback: Function)

This callback is fired each time the JWT is refreshed.

authCallback is a function with one argument, an object with these properties:

Property Type Description
channelId string Channel ID of the page where the extension is iframe embedded.
clientId string Client ID of the extension.
token JWT JWT that should be passed to any EBS call for authentication.
userId string Opaque user ID.

For example:

window.Twitch.ext.onAuthorized(function(auth) {
  console.log('The JWT that will be passed to the EBS is', auth.token);
  console.log('The channel ID is', auth.channelId);
});

Usually, the JWT obtained from this call is passed as a header during AJAX calls to the EBS. For example:

window.Twitch.ext.onAuthorized(function(auth) {
  $.ajax({
    url: '/<some backend path>',
    type: 'GET',
    headers: {
      'x-extension-jwt': auth.token,
    }
  });
});

onContext

twitch.ext.onContext: function(contextCallback: Function)

This callback is fired when the context of an extension is fired.

contextCallback is a function with two arguments, a context object and an array of strings naming the context properties that were changed. The context object has these properties:

PropertyTypeDescription
arePlayerControlsVisibleboolean

If true, player controls are visible (e.g., due to mouseover). Do not use this for mobile extensions; it is not sent for mobile.

bitratenumberBitrate of the broadcast.
bufferSizenumberBuffer size of the broadcast.
displayResolutionstringDisplay size of the player.
gamestringGame being broadcast.
hlsLatencyBroadcasternumberNumber of seconds of latency between the broadcaster and viewer.
hostingInfoobject

Information about the current channel’s hosting status, or undefined if the channel is not currently hosting.

Host mode enables broadcasters to stream another channel’s live broadcast (audio, video, and Extensions), while the host broadcaster is offline or interacting only with chat.

This object contains two strings:

  • hostedChannelId — Numeric ID of the channel being hosted by the currently visible channel
  • hostingChannelId — Numeric ID of the host channel
isFullScreenbooleanIf true, the viewer is watching in fullscreen mode. Do not use this for mobile extensions; it is not sent for mobile.

isMuted

booleanIf true, the viewer has muted the stream.
isPausedbooleanIf true, the viewer has paused the stream.
isTheatreModebooleanIf true, the viewer is watching in theater mode. Do not use this for mobile extensions; it is not sent for mobile.
languagestringLanguage of the broadcast (e.g., "en").
modestringValid values:
  • viewer — The helper was loaded in a viewer context, such as the Twitch channel page.
  • dashboard — The helper was loaded into a broadcaster control context, like the live dashboard. Use this mode to present controls that allow the broadcaster to update the extension’s behavior during broadcast.
  • config — The helper was loaded into the extension dashboard for configuration, including initial configuration. All setup needed to run the extension should be in this mode.
playbackModestringIndicates how the stream is being played. Valid values:
  • video — Normal video playback.
  • audio — Audio-only mode. Applies only to mobile apps.
  • remote — Using a remote display device (e.g., Chromecast). Video statistics may be incorrect or unavailable.
  • chat-only — No video or audio, chat only. Applies only to mobile apps. Video statistics may be incorrect or unavailable.
themestringThe user's theme setting on the Twitch website. Valid values: "light" or "dark".
videoResolutionstringResolution of the broadcast.
volumenumberCurrently selected player volume. Valid values: between 0 and 1.

onError

twitch.ext.onError: function(errorCallback: Function)

This callback is fired if any errors are generated by the extension helper.

errorCallback is a function with one argument, the error value, when any errors occur within the helper.

onHighlightChanged

twitch.ext.onHighlightChanged: void function(callback: Function)

This function allows an extension to adjust its visibility when the viewer highlights the extension by hovering over the extension’s menu icon or open menu, in the video player. The function applies only to video-overlay and component Extensions.

ArgumentTypeDescription
callbackfunction

A callback that is called with one argument:

  • isHighlighted — A boolean indicating whether the extension is highlighted by the user.

onPositionChanged

twitch.ext.onPositionChanged: void function(callback: Function)

This function registers a callback that gets called whenever an extension changes position in the player. This applies only to video-component extensions. This also is triggered as the extension loads.

ArgumentTypeDescription
callbackfunction

A callback that is called with one argument:

  • position - An object indicating the x and y coordinates of the extension. These coordinates are expressed as fixed-point integers (two decimal points) representing the percentage of the player width/height where the top-left corner of the extension is located. For example, a value of 1050 for x indicates the corner of the extension is 10.5% of the player’s width from the left, on the x axis.

onVisibilityChanged

twitch.ext.onVisibilityChanged: void function(callback: Function)

This function registers a callback that is triggered whenever an extension is hidden or re-shown either due to the viewer’s action or due to the video player changing to a state where extensions are not shown (such as when the video pauses or an ad is running.) When an extension is not visible, it does not receive onContext updates and must perform only minimal work in the background.

ArgumentTypeDescription
callbackfunctionA callback that is called with one or two arguments:
  • isVisible — A boolean indicating whether the extension is visible.
  • context — A fresh context object like the one passed by onContext. context is present only when isVisible is true.

send

twitch.ext.send: function(target: String, contentType: String, message: Object)
twitch.ext.send: function(target: String, contentType: String, message: String)

This function can be called by the front end to send directly to PubSub. It uses the Twitch-provided JWT for broadcasters, to allow broadcasters to send a broadcast (channel) or whisper message. Broadcasters cannot send to global.

Argument Type Description
contentType string Content type of the serialized message; for example, "application/json".
message object or string Either an object that will be automatically serialized as JSON or a string.
target string Target topic. Usually this is "broadcast" (but it could be "whisper-<userId>").

listen

twitch.ext.listen: void function(target: String, callback: Function)

This function binds the callback to listen to the target topic.

Argument Type Description
callback function Function with three arguments: target, contentType, and message. These fields correspond to the values in the send message, except the message is always a string.
target string Target topic. Usually this is "broadcast" or "global" (but it could be "whisper-<userId>").

If an extension front end listens to "broadcast" on a channel, it will receive messages sent to the channel, for that extension/channel combination. If it listens to "global", it will see messages sent to global, for all channels with that extension installed.

Non-Extensions PubSub topics also are supported.

Whispers are a set of optional PubSub channels that extensions can use. Each copy of an extension can register for "whisper-<userId>" where userId comes from the onAuthorized message. Attempts to listen to another userId will be blocked. Once the extension is listening, the EBS or broadcaster can send an individualized message to the channel.

unlisten

twitch.ext.unlisten: void function(target: String, callback: Function)

This function unbinds the listen callback from the target.

Argument Type Description
callback function Function with three arguments: target, contentType, and message. These fields correspond to the values in the send message, except the message is always a string.

This must be the original function object: passing in a new function or a copy of the original has no effect.
target string Target topic. Often this is "broadcast" but it might be "whisper-<userId>".

Non-Extensions PubSub topics also are supported.

Helper: Actions

followChannel

twitch.ext.actions.followChannel: void function(channelName: String)

This function prompts users to follow the specified channel, with a dialog controlled by Twitch. When users confirm (through the dialog) that they want to follow the channel, the callback registered with Twitch.ext.actions.onFollow is invoked.

Argument Type Description
channelName string Channel to be followed.

minimize

twitch.ext.actions.minimize: function()

This function causes your video-component or video-overlay extension to be minimized.

onFollow

twitch.ext.actions.onFollow: void function(callback: Function)

This function registers a callback that is invoked whenever a user completes an interaction prompted by the followChannel action.

ArgumentTypeDescription
callbackfunctionFunction with two arguments:
  • didFollow – A boolean that indicates whether users confirm that they want to follow the channel.
  • channelName – The channel that was followed.

requestIdShare

twitch.ext.actions.requestIdShare: function()

This function opens a prompt for users to share their identity. After a successful identity link, the Twitch.ext.onAuthorized callback is invoked with the user’s ID. This function has no effect if:

  • Your extension does not have identity linking enabled.
  • It is called when the extension is installed on the user’s own channel.

Helper: Configuration

broadcaster

twitch.ext.configuration.broadcaster: {version: string, content: string}|undefined

This property returns the record for the broadcaster segment if one is found; otherwise, undefined.

developer

twitch.ext.configuration.developer: {version: string, content: string}|undefined

This property returns the record for the developer segment if one is found; otherwise, undefined.

global

twitch.ext.configuration.global: {version: string, content: string}|undefined

This property returns the record for the global segment if one is found; otherwise, undefined.

onChanged

twitch.ext.configuration.onChanged: void function (callback: Function)

This function registers a callback that is called whenever an extension configuration is received. The callback function takes no input and returns nothing. After this is called for the first time, the records for the global, developer and broadcaster segments will be set if the data is available.

set

twitch.ext.configuration.set: void function (segment: String, version: String, content: String)

This function can be called by the front end to set an extension configuration. It uses the Twitch-provided JWT for broadcasters, to allow broadcasters to set a broadcaster configuration segment.

PropertyTypeDescription
contentstringThe string-encoded configuration.
segmentstringThe configuration segment to set. Valid value. "broadcaster".
versionstringThe version of configuration with which the segment is stored.

Helper: Feature Flags

isChatEnabled

twitch.ext.features.isChatEnabled: boolean 

If this flag is true, you can send a chat message to the current channel using Send Extension Chat Message (subject to the authentication requirements documented for that endpoint). This flag may be false if:

  • You did not enable the “Chat Capabilities” option for your extension on the Twitch developer site.
  • The broadcaster disabled chat for your extension.

isSubscriptoinStatusAvailable

twitch.ext.features.isSubscriptionStatusAvailable: boolean

If this flag is true, your extension has the ability to get the subscription status of identity-linked viewers from both the helper in the twitch.ext.viewer.subscriptionStatus object and via the Twitch API. It also has the ability to prompt a user to subscribe to the channel the extension is installed on via twitch.ext.actions.subscribeToChannel.

This flag may be false if:

  • You did not enable the “Subscription Status” option for your extension on the Twitch developer site.
  • The broadcaster did not grant your extension the permission to view their viewer’s subscriber status when they activated the extension, or they revoked that permission from the Manage Permissions page.
     

onChanged [features]

twitch.ext.features.onChanged: void function(callback: Function(changes: []string))

This function enables you to receive real-time updates to changes of the features object. If this callback is invoked, you should re-check the Twitch.ext.features object for a change to any feature flag your extension cares about. The callback is called with an array of feature flags which were updated.

callback is a function with one argument:

ArgumentTypeDescription
changedstring[]The callback which will be called when feature flags are updated. Feature flags are received in your extension from Twitch asynchronously, after the first call to onAuthorized. If you care about only the initial state, you can get that in your onAuthorized callback. If you need to know about updates, use  Twitch.ext.features.onChanged.

Helper: Bits

Some functions use the Product object. Here is an example (fields are described under getProducts):

{
   "sku": "carrot",
   "displayName": "Carrot",
   "cost": {
       "amount": "500",
       "type": "bits"
   }
   "inDevelopment": true
}

getProducts()

twitch.ext.bits.getProducts: {Promise: Product[]}

This function returns a promise which resolves to an array of products available for Bits, for the extension, if the context supports Bits in Extensions actions. Otherwise, the promise rejects with an error; this can occur, for instance, if the extension is running in an older version of the developer rig or an older version of the mobile app (earlier than V6.4), which does not support Bits in Extensions actions.

Products are returned only if the extension is configured for Bits (see the Extensions Monetization Guide). The products that are returned depend on the state of both the extension version (whether it is released) and the product (whether the kit is in development):

Is the extension version released?Which products are returned?Is the inDevelopment field included in the returned products?
YesProducts whose catalog entries specify inDevelopment = false or undefinedNo
NoAll products for that extensionYes

Products have the following fields:

Product FieldTypeDescription
costCostCost object.
   amountstringNumber of Bits required for the product.
   typestringAlways the string "bits". Reserved for future use.
displayNamestringRegistered display name for the SKU.
inDevelopmentboolean or undefined

This field is returned only for extension versions that are not in the Released state. Valid values:

  • true – Indicates that the product’s catalog entry specifies it is in development. If the developer tests the use of Bits, the Bits are not deducted from the user’s balance.
  • false – Indicates that the product’s catalog entry specifies it is not in development. If the developer tests the use of Bits, the Bits are deducted from the user’s balance.
  • undefined – Indicates that the product’s catalog entry does not specify anything about whether it is in development. If the developer tests the use of Bits, the Bits are deducted from the user’s balance.
skustringUnique ID for the product.

onTransactionCancelled

twitch.ext.bits.onTransactionCancelled: void function(callback: Function)

This function takes a callback that is fired whenever a transaction is cancelled. A transaction can be cancelled in several ways:

  • The user clicks the Cancel button.
  • The user closes the confirmation dialog by clicking outside it.
  • The useBits function fails and the user dismisses the error dialog that is displayed.

onTransactionComplete

twitch.ext.bits.onTransactionComplete: void function(callback: TransactionObject)

This function registers a callback that is fired whenever a Bits in Extensions transaction is completed. The callback receives a TransactionObject with these fields:

TransactionObject FieldTypeDescription
displayNamestringDisplay name of the user who executed the Bits in Extensions transaction (i.e., exchanged Bits to “purchase” a Bits in Extensions “product”).
initiatorenum

Valid values:

  • CURRENT_USER (the user who executed, or initiated, the transaction).
  • OTHER (a user other than CURRENT_USER).

The OTHER value indicates when this message is being sent to a user other than the one who executed the transaction. For example, suppose user A exchanges 10 Bits to set off a firework on a channel. Twitch processes the transaction, then sends a message to all instances of the extension:

  • On user A's machine, the extension gets an initiator value of CURRENT_USER.
  • On the machines of all other users who have the extension, the initiator value is OTHER.

In this way, the extension can easily display the firework in the browsers of all users who have the extension.

productProductFull product object from getProducts call
transactionIDstringID of the transaction.
transactionReceiptstringJWT containing the following transaction information in the payload. The JWT is a large, base64-encoded string. It can be verified using your developer secret. (See https://jwt.io/ for details on JWTs and verification.)
   topicenumIndicates the type of receipt. Valid value: bits_transaction_receipt.
   expiresstringUnix timestamp when this receipt expires.
   dataJSONContainer for receipt payload data.
      productProductFull Product object from getProducts call.
      timestringUTC timestamp when this transaction occurred.
      transactionIdstringID of the transaction.
      userIdstringTwitch ID of the user who executed the transaction.
userIdstringTwitch ID of the user who executed the transaction.

setUseLoopBack

twitch.ext.bits.setUseLoopback: boolean

This function sets the state of the extension helper, so it does not call live services for usage of Bits. Instead, it does a local loopback to the completion handler, after a fixed delay to simulate user approval and process latency.

showBitsBalance

twitch.ext.bits.showBitsBalance: void

Call this function when the viewer hovers over a product in your extension UI, to cause the Twitch UI to display a dialog showing the viewer’s Bits balance. The dialog displays for 1.5 seconds, unless your extension calls showBitsBalance again, in which case the 1.5-second timer resets.

This is a “fire-and-forget” function: the extension developer does not need to tell Twitch when the viewer stops hovering over the product.

On mobile, this function is ignored.

useBits

twitch.ext.bits.useBits: void function(sku: String)

This function redeems a product with the specified SKU for the number of Bits specified in the catalog entry of that product. For more information, see Exchanging Bits for a Product.

Helper: Viewer

The Twitch.ext.viewer object is a collection of info about the twitch viewer that is watching the channel page where your extension is activated. It will only be populated if the viewer is logged in, and only after the `onAuthorized` callback has been called. Accessing its properties will otherwise return `null`.

Much of the information stored here is also present in the extension JWT, and is presented as part of this object for convenience. It is passed to the extension iframe from the client without validation, so it is recommended that you use this info for rendering conditional UI elements, and that you pass the JWT to your EBS for validation if you are using any of this information to grant users permission to take privileged actions within your extension.

opaqueId

Twitch.ext.viewer.opaqueId: string

The opaque id of the viewer.

id

Twitch.ext.viewer.id: string | null

The Twitch ID of a linked viewer. null if the viewer has not opted to share their identity with the extension.

role

Twitch.ext.viewer.role: string

The role of the user. See the JWT schema for possible values.

isLinked

Twitch.ext.viewer.isLinked: boolean

Provided as a convenience to check whether or not a user has shared their identity with their extension

sessionToken

Twitch.ext.viewer.isLinked: string

The encoded JWT. This is the same as the token property of the authData parameter that currently gets passed to the onAuthorized callback.

subscriptionStatus

Twitch.ext.viewer.subscriptionStatus: SubscriptionStatus | null

Subscription status will be an object containing information about the viewer’s subscription. The SubscriptionStatus object will have the following properties:

Property Type Description      
tier String null  The tier of the subscription. Possible values are 1000 2000 3000 for tier one, two, and three subscriptions respectively.

The value of subscriptionStatus will be null if the user is either not a subscriber, or opting not to share their identity. The value will also be null if the extension otherwise doesn’t have subscription capabilities.

onChanged

Twitch.ext.viewer.onChanged: void function(callback: Function())

This function binds a callback will be invoked when the viewer’s status changes (e.g. if a viewer subscribes and changes their subscription status).

Client Query Parameters

In addition to the context provided by the Javascript helper’s callbacks, the extension window receives the following query parameters, which indicate information about the extension environment that isn’t subject to change over the frame’s life cycle.

Name Type Description
anchor string The type of the anchor in which the extension is activated. Valid only when platform is "web". Valid values: "component""panel", "video_overlay".
language string The user’s language setting (e.g., "en").
locale string The user’s language locale (e.g. "en-US")
mode string The extension’s mode. Valid values: "config", "dashboard", "viewer".
platform string The platform on which the Twitch client is running. Valid values: "mobile", "web".
popout boolean Indicates whether the extension is popped out. If true, the extension is running in its own window; otherwise, false.
state string The release state of the extension. Valid values: "testing", "hosted_test", "approved", "released", "ready_for_review", "in_review", "pending_action", "uploading".

JWT Schema

Schema ItemTypeDescription
channel_idstringNumeric ID of the channel from which your front-end is being served.
expNumericDateExpiration time for the JWT, expressed as seconds since Jan 1, 1970. (For a definition of NumericDate, see Terminology in the JWT RFC.)
is_unlinkedbooleantrue when the token is for a user that previously shared identity; otherwise, false.
opaque_user_idstringIdentifies the session using this JWT. Any token generated by your EBS should leave this field blank. When present, the value is interpreted as follows:
  • Values beginning with "U" are stable references to a Twitch account across sessions and channels. You can use them to provide persistent services to users.
  • Values beginning with "A" are transient references to an anonymous Twitch session; the user has not logged into the Twitch website. These values are not stable and should never be associated with persistent data. It is possible for them to represent different users over time. If your extension requires a stable user identity, your front-end interface should display an appropriate login request when this field does not begin with "U."
Broadcasters’ tokens are set with "U" + their Twitch user IDs, to avoid confusing opaque IDs with user IDs when the broadcaster is a viewer.
pubsub_permsobjectDefines the ability of the token holder to send and listen to messages for your extension. pubsub_perms contains two arrays: listen and send, which contain the topics the associated user is allowed to listen to and publish to, respectively.

A wildcard/asterisk means the associated user can listen/publish to all topics associated with that extension/channel combination. A list of specific values means only the specified targets are allowed. If a permission is absent, it is equivalent to the empty listing: there are no default allowed targets. When sending messages from the EBS, specify an asterisk as the send permission, to allow the message to pass through the system.

For an example, see Example JWT Payload.
rolestringType of user for whom this JWT has been signed. This is required. Valid values:
  • broadcaster — The owner of the channel, who should have configuration rights.
  • moderator — A viewer who has moderation rights on the channel. This is provided only for users who allow your extension to identify them.
  • viewer — A user watching the channel.
  • external — The token is not from a Twitch token generator. Your EBS should use this value to generate tokens when it broadcasts messages. Multiple endpoints require this role.
user_idstringThe user’s Twitch user ID. This is provided only for users who allow your extension to identify them. There are no guarantees this will be available, as users can revoke an extension's ability to identify them at any time. Users who revoke an extension's ability to identify them are issued a new opaque identifier.

Example JWT Payload

{
  "exp": 1484242525,
  "opaque_user_id": "UG12X345T6J78",
  "channel_id": "test_channel",
  "role": "broadcaster",
  "is_unlinked": "false",
  "pubsub_perms": {
    "listen": [ "broadcast", "whisper-UG12X345T6J78" ],
    "send": ["broadcast","whisper-*"]
  }
}
+