Extensions Reference

Introduction

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

Endpoints

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 Secrets” 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//auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

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//auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

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//auth/secret

Required Query String Parameters

None

Optional Query String Parameters

None

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//live_activated_channels

Required Query String Parameters

None

Optional Query String Parameter

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///required_configuration?channel_id=

Required Query String Parameters

None

Optional Query String Parameters

None

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//configurations

Required Body Parameters

Optional Body Parameters

Required Query String Parameters

None

Optional Query String Parameters

None

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//configurations/channels/

Required Query String Parameters

None

Optional Query String Parameters

None

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//configurations/segments/broadcaster

GET https://api.twitch.tv/extensions//configurations/segments/developer

GET https://api.twitch.tv/extensions//configurations/segments/global

Required Query String Parameter

Optional Query String Parameters

None

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/

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

Required Body Parameters

Required Query String Parameters

None

Optional Query String Parameters

None

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///channels//chat

Required Query String Parameters

None

Optional Query String Parameters

None

JavaScript Helper

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:

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: '/',
    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:

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.

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.

onVisibilityChanged

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

This function registers a callback that gets called whenever an extension is hidden/re-shown, either due to the viewer’s action or due to extensions hiding 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.

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.

listen

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

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

Whispers are a set of optional PubSub channels that extensions can use. Each copy of an extension can register for "whisper-" 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.

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.

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.

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.

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.

isSubscriptionStatusAvailable

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.

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:

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):

Products have the following fields:

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:

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:

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.

JWT Schema