RFC 0006 - Configuration Service


The Extensions Configuration Service will allow developers to persist configuration information for their extension and expose it to their frontend and backend. Today, developers must implement this themselves to deliver a customized extension experience. This service alleviates the need to implement and pay the cost for this functionality.


We recognize that the process to build an extension can be improved greatly. Even simple extensions that leverage a configuration variable require a backend for persistence. Extension backends can be challenging to build, expensive to host, and difficult to operate at large scale. Depending on an extension’s design, it may be subject to extremely large traffic spikes as viewers tune in to popular channels going live.

The Configuration Service is the first in a series of services designed to replace functionality commonly implemented by developers with Twitch hosted solutions. As additional hosted services become available, developing and operating extension backends will become easier. Our goal is to have developers focus on building a great user experience rather than implementation details.

Detailed Design

Defining Configuration

There are two configuration scopes: channel specific and extension-wide. Channel specific configuration is further split by write access into a segment only the developer can update (for use by an extension backend service (EBS)), and a segment for both the developer and broadcaster (intended for the config and live dashboard pages to update directly).

Setting Configuration

Developers have control over configuration. To set broadcaster configuration, there is the Twitch.ext.configuration.set() function in the JavaScript helper API. This method will reject viewers or moderators; it should only be invoked from the config or live dashboard views.

The following API is available for extensions backends to set configuration:

PUT https://api.twitch.tv/extensions/<extension_id>/configuration
	“segment”: “developer|broadcaster|global”,
“channel”: <channel_id>
“version”: <config_version_name>
“content”: <data_string (e.g. escaped json or base64 encoded binary)>

The PUT request requires a signed JWT (external or broadcaster roles are allowed). The channel element is ignored when the segment type is global; it does not need to be sent for this case. The version field should match the required version specified in the dev site, and will be used to verify that broadcasters are ready to activate after saving configuration. The remainder of the body is the configuration payload to be updated. Developers are responsible for the serialisation format of the content.

Retrieving Configuration

Configuration is made available to Extension frontends when they load. It is accessed by the Twitch.ext.configuration.onChange() callback registration function in the JavaScript helper API.

If required, Extension backends can retrieve configuration by calling:

GET https://api.twitch.tv/extensions/<extension id>/configuration

Size Limits

  • 5KB for each per-channel broadcaster segment
  • 5KB for each per-channel developer segment
  • 5KB for the per-extension global segment

Rate Limits

Configuration updates are limited to ten calls per segment per minute.

Dev Site Updates

Today, the dev site contains a “Required Configurations” field that may be used by developers to confirm necessary configuration before activation. A “Configuration Location” drop down will be introduced above this field with the three options, “Twitch hosted”, “Custom”, and “None”, allowing developers to select an extension’s source of configuration. “Required Configurations” will be renamed to “Configuration Version” and only appears when “Configuration Location” is not “None”.

Developer Rig Updates

The Developer Rig will be updated to allow local development of an extension using configuration service capabilities before the service is made available.

Additionally, the Developer Rig will provide an interface to retrieve and update extension configuration.

Rollout Considerations

The configuration service is not mandatory for extensions. Any developer can choose to leverage the configuration service for their extension by updating the configuration settings on the dev site.

Prior to making the configuration service available to developers, Twitch will add support for it in the Developer Rig. This will allow developers to locally test what it is like to leverage the configuration service once it is live.

When migrating existing extensions to use the configuration service, developers should preload existing configuration into the service before releasing the updated extension.


Functionality provided by the configuration service will expand over time. The following areas will have future design and development efforts:

  • Live delivery of configuration updates: two defining features of configuration are that it is long-lived and changes infrequently. There is often urgency to propagate changes immediately to currently active clients for both extension frontends and backends. In the initial rollout of the configuration service, updates will require a reload. Backends that require live configuration updates should remain the source of truth of configuration.
  • Configuration schema updates: developers will initially be responsible for all configuration schema updates and migrations.
  • The configuration service is not a state service: attempting to use the configuration service to distribute continually updating state will cause rate limits to be triggered and subsequent requests to be discarded.
    Storage limits: decisions around initial storage limits were made based upon a number of different inputs. This may be revisited in the future as additional use cases appear.


There have been many internal discussions around what the configuration service is, or even should be. A delineation was drawn between configuration and state, where configuration represents long-lived data and state was transient. As conversations continued, it became clear that state and configuration have different requirements. Persisting configuration sees much more use in current extensions than persisting and passing state.

This new service is optional. If more custom configuration options are necessary for their use case, a developer may choose to implement something tailored.


Really cool feature, glad to see this. All of the extensions I have built send a query back to the EBS immediately when they load to get configuration options for the particular channel, those calls will no longer be need when this change rolls out which is great.

I do like having configuration changes propagate to viewers live, but I currently use pubsub broadcasts for that and it’s not a big issue, good to see it’s something you’re considering in the future.

My only real issue is simply with the text that you’re suggesting will be added to the Dev Site in the update. Brevity is good and all, but I’m pretty sure even experienced devs who haven’t built an extension and used the Required Configurations feature before may not be able to easily decipher what option is best suited for their extension, nevertheless non-devs who are trying to have a crack. Why not some actual sentences? For example:

  • Will your extension need to store some configuration data for each channel?
    • Yes / No radio buttons

Yes leads to:

  • Where will you store the channel configuration data?
    • Twitch Hosted Config / My EBS
  • Does your extension require configuration before it can be used?
    • Yes / No

Yes leads to:

  • Enter the configuration string for this version of the extensions
    • text input

Looking forward to this rollout!

1 Like

I have been very keen for this service! The 10 requests per segment seems like it might run into problems though? If you have 11 viewers load the channel at the same time it will make 11 calls for the same channel segment and will fail?

I can’t see it specified anywhere but there should be any reason why the EBS can’t set the configuration service payload too? This was my specific use case (You may think if you have an EBS why not use that to store the data, but for managing scaling i saw the configuration service as very valuable.)

I will play around and provide some feedback!

The 10 requests per segment seems like it might run into problems though?

My interpretation was it’s 10req/second to set the config, no limitation on get.

I can’t see it specified anywhere but there should be any reason why the EBS can’t set the configuration service payload too?

It’s right there in the Setting Configuration section. The code sample is for an EBS.

Ah, I should have read more before commenting. Thanks. Very excited for this service.

Just want to say that this is something I have been waiting for since Extensions came out! In fact honestly I was a bit surprised that this wasn’t a thing when Extensions first launched as it made complete sense to me that this would be how it all worked.

Glad to see this is coming and if there is a beta I would love to volunteer to be a part of it - I have 3 or 4 live and actively used Extensions which could be improved by this service.

Thank you everyone for the great commentary thus far. Please keep it coming!

@xzion - please do not consider the text to be final by any means. Contextual supporting information will be included too.

@Seravy and @xzion - the 10 request rate limit is actually a little different to what both of you have specified. Good callout from a clarity perspective though! Current configuration is returned on extension load. As discussed in the first point in drawbacks, live updates will not be a part of the initial roll out for the Configuration Service.

Reading between the lines: live updates is something that many people at Twitch are extremely passionate about, and is something that we will continue to work towards. We did not want it to block the rollout of the Configuration Service, and we did not want to propose a solution that would be deprecated shortly there after.

The get endpoint is most pertinent for the 10 request per segment per minute rate limit. This is what EBSs use to retrieve broadcaster configuration updates. I’d suggest that this limit is slightly less relevant to the put method.

@tf2casperr, given the incremental nature of service adoption, we will be putting the Configuration Service directly into General Availability. Prior to launch, its functionality should be available for extensions running in local mode in the Developer Rig though.

Thanks for the updates. I think I understand now, having the configuration returned on load via that call back works to begin with. Will it be announced here when it becomes available to use?

For Twitch Picks, we use a pattern where the streamer can reconfigure the extension from the viewer. A lot of streamers keep their own stream open, and it’s handy for them to also be able to edit their polls from not only their config and live-config but also the viewer.

Would the .set invocation also be available from that context, even if it’s still the broadcaster?

Short answer: yes

Longer answer: the setter uses the JWT for auth, so it will work wherever the corresponding user has the appropriate permission. This will work for the broadcaster, as there is a config segment they can write to. This will not work for viewers though.