Show Custom Action Buttons On Your Page

You can build additional interfaces that are hosted with any add-ons, extensions, or 3rd party sites. Each action is a single URL or custom HTML that will be loaded and displayed when a user presses a button on the Owncast page.

Plugin action buttons require Owncast v0.3.0

Plugins can also contribute action buttons alongside the ones you register by hand. See the plugin manifest documentation.

Examples

Some examples of this functionality might be things like:

1. A leader board for some chat-based game you built or an external game you're playing on stream.
2. Lists of actions that perform fun animations on your stream overlays when selected.
3. Integrations with your polling chat bot that shows recent polls and the results.
4. Tip Jar to accept donations.
5. A schedule that is fancier or more interactive than what you can represent in Markdown.

Limitations

1. URLs embedded via external actions must be hosted on a server that supports SSL and has a https protocol. Unsecured URLs are not supported.
2. These URLs must support existing inside an iframe. This means X-FRAME-OPTIONS and the CSP cannot be blocking. If you are blocked then you're limited to loading this URL in a new tab and that's not a great experience.
3. While you can experiment with using URLs that you don't personally control, it's often likely that many of them will not work due to limitations placed on the remote server. An example of this is just throwing in a PayPal or Google URL.

How to register actions

1. Visit the admin, and under "Integrations" go to the "External Actions" page.
2. Add an action.
3. Set the URL or custom HTML of this action. URLs should be a HTTPS destination and follow the best practices listed.
4. Give it a name that will be displayed on the button that launches this action, an optional description that will show in the modal that presents the action, a URL to an optional icon for the button, and optionally a color that will be used for the button.
5. If you really want to register a URL you don't control, but it doesn't work with the default functionality, you can tell it to "Open Externally" and it will open a new tab in your browser. This is not optimal, but it's an option.

Query parameters passed to URL actions

When a viewer opens a URL action, Owncast appends query parameters to your URL:

• instance is always appended and holds the URL of the Owncast page the viewer is on. Useful if you host one action for multiple servers.
• username and userId are appended only when the viewer has a chat user. username is the display name, which is not unique. userId is a stable identifier for that chat user.

These parameters are conveniences, not authenticated identity. Anyone can open your URL with any values, so never grant access or make privileged API calls based on them. Use them to pre-fill forms and label sessions.

The iframe sandbox

A URL action loads inside a modal in an iframe with sandbox="allow-same-origin allow-scripts allow-popups allow-forms". Your page can run scripts, submit forms, and open popups, but it cannot navigate the top-level Owncast page or trigger downloads.

There is no postMessage bridge. An embedded action cannot close or resize the modal, and it has no way to call back into Owncast. Treat the action as a self-contained page.

Best practices

1. This action's UI should perform little to no navigation. It shouldn't be treated as a way to show just any page.
2. Design your UI to live in a small window that doesn't require much, if any, scrolling, and is responsive to mobile and small displays.
3. Make sure your URL's server allows loading your content from your Owncast server via X-FRAME-OPTIONS and the CSP.
4. The query parameters Owncast appends tell you which server and which chat user opened the action. Use them to pre-fill forms, and remember they can be faked, so never treat them as proof of identity.
5. For HTML actions that include custom styling via <style> tags, you should make sure to have selectors that are as specific as possible, not colliding with any other elements in the page.
6. For HTML actions that directly embed a <form> element, it makes sense to set target="_blank" to open the submit page in a new tab. That way your viewers won't have to stop the stream when submitting the form.