How to use the Custom Request action

The Touch Portal OBS Guides

This guide will show you how to use the Custom Request action for OBS. Touch Portal relies on the Websocket Plugin that is shipped with OBS. Touch Portal communicates with OBS through this websocket plugin. All OBS actions that are available in Touch Portal communicate with the plugin using messages and this Custom Request action allows you to do the same. This allows you to use requests that are not yet available in Touch Portal.

OBS WebSocket Documentation

This action requires knowledge about the OBS WebSocket communication. You can find the documentation here. As we understand this might be a bit too technical for most user, we will try to explain how to use this in this tutorial as well.

The Custom Request action

The communication to the websocket requires the JSON data format. With this action we provide the wrapper that handles the communication and the full message formatting. The only thing you need to do is add the request type, provide an optional ID and the actual data for the request.

Request Type

This is type of request you want to send to the websocket. This is the identifier for what the websocket should do.

Request ID

This is a personal id you can give this action. This id will be sent back from the websocket to Touch Portal and you can listen for it if you need. All ids are prefixed with tpc_ to ensure they are not interfering with other returned results and events.

Request Data

Where the type is to identify what the websocket should do, the data is what specifies how that request should be done by the websocket. This usually is the more tricky part to get correct as this needs to be in correct JSON format.

Learn by an example - Show and Hide sources

Step 1 - Prepare a toggle button

For this we are going to drag and drop the Toggle Button from the premade buttons list. Drag it on an empty button.

This will create a functioning toggle button from which we will start this example. Open the button so we can add the functionality.

Step 2 - Add the OBS custom Requests

Now we check the actions list on the left side of the button edit screen and search for Custom Request

Drag that action to the places beneath the two comments, so that means you add the action two times. This will result in the following layout.

Step 3 - Add the Request Types

Both actions will require the same type. The type we will be using is the SetSceneItemEnabled. The Websocket documentation has a menu at the top and from there you can go to the list of all available requests the Websocket offers.

So we use this for both custom request actions. The data will eventually specify whether this request should show or hide the scene item (source).

For this example we will leave the ID empty as it is optional and outside of the scope of this example.

Step 4 - Add the Request Data

The last step we need to do is specify the data we need to send to make the two action either show or hide the source. We need to look at the documentation for the request to know what we need to send. If you click on the request we are using you will see the details of that request like the image below. The Request fiels is the what we need for the data.

This request shows 3 fields we need to send to the websocket as data to make the request work. We need to the sceneName, which you know as it is part of the scene that holds the source/scene item you want to show and hide. In our case this is the scene Gaming.

How does JSON work for specifying the data?

Every JSON Object is contained within a start { and an ending }. Then every data item we need to specify is a combination of the key and the value, which format is "key":"value" for a string, "key":100 for a number and "key":true for a boolean. Using the double qoutes at the correct places is very important otherwise the data will be invalid and the action will fail. An example of how it looks like:
Important to note here is every item within a JSON is seperated with a comma.

We also need the scene item id for the source you are trying to show and hide. This is an id that the Websocket holds as a reference to a source/scene item in a scene. This means you cannot get that information from OBS. So the easiest way to get this id is to use Touch Portal for this. Be sure to enable the OBS logging option in the Touch Portal Logs tab so that information is written in the log from the websocket. Now go into OBS and show and hide your source a few times. The Touch Portal logs will show the event that the scene item changed its state and in that message is also the sceneItem being show

Now we have all information for making the data as well. The scene item id for our source is 3. This results in our full data text for showing the source to:


and for the hiding:


Which leaves us with the following result

End Result

You will now have a basic understanding on how the OBS Custom Request action works and how you can use the documentation of the Websocket to create your own OBS actions.

Back to Guide Overview