Call BTT Functions from the WebView

Triggering Scripting Functions from any BetterTouchTool Web View

The Floating Web View allows you to trigger various scripting functions via JavaScript.

Important Note: When loaded the webview takes a few milliseconds to initialize BTT's scripting infrastructure. This is why you should only call the scripting functions after the BTTInitialized function has been called (or you can use some fixed delay). For more information see webview lifecycle

The available scripting functions are:

resize_webview
trigger_named
update_touch_bar_widget
update_stream_deck_widget
trigger_action
execute_assigned_actions_for_trigger
refresh_widget
get_trigger
get_triggers
update_trigger (to create or if exists update a trigger)
add_new_trigger
delete_trigger
delete_triggers
trigger_named
trigger_named_async_without_response
cancel_delayed_named_trigger_execution
get_dock_badge_for
get_active_touch_bar_group
is_true_tone_enabled
get_location
set_persistent_string_variable
set_string_variable
set_persistent_number_variable
set_number_variable
get_number_variable
get_string_variable
export_preset
display_notification
paste_text
set_clipboard_content
get-selected-text

Floating Menus:

update_menu_item
get_menu_item_value
set_menu_item_value
webview_menu_item_load_html_url_js

Note: There are some built-in variables, which can also be quite helpful:

Built-In Scripting Variables

There are two ways to trigger these scripting functions, both are equally powerful:

1.) Using the bttweb:// links

bttweb:// is a custom URL scheme which allows you to trigger scripting functions and retrieve their results, just like any other http call. You can use them in normal a elements <a href="bttweb://trigger_named/?trigger_name=test"></a> or use XMLHTTPRequest or fetch for this.

The general format for bttweb:// links is always bttweb://**scripting_function_name**/?arg1=xxx&arg2=yyy&arg....

Loading bttweb links using fetch with async/await: // a little helper function

async function bttwebRequest(requestPath) {
    const response = await fetch(requestPath);
    const responseText = await response.text();
    return responseText;
}

let result = await bttwebRequest('bttweb://trigger_named/?trigger_name=test');

2.) Using The Scripting Interface via JavaScript.

BetterTouchTool automatically injects JavaScript functions into any HTML loaded into the floating HTML View. Using these you can trigger the scripting interfaces mentioned above.

Closing the webview

You can close the floating webview by passing the closeFloatingWebView set to 1. E.g. trigger_named({trigger_name: 'test', closeFloatingWebView:1});

Example script function calls:

resize_webview

This method will resize the floating webview to the specified width and height.

Example

await resize_webview({"width" :100, "height": 250});

trigger_named

This method will trigger the specified named trigger (which can be configured in the "Other" tab in BetterTouchTool.)

Example

let result = await trigger_named({trigger_name: 'Action5'});
// Currently only the AppleScript and Shell Script actions return results.

<a href="bttweb://trigger_named/trigger_name=Action5">

trigger_named_async_without_response

This method will trigger the specified named trigger (which can be configured in the "Other" tab in BetterTouchTool.). It won't wait for a response.

Example

trigger_named_async_without_response({trigger_name: 'Action5'});
// Currently only the AppleScript and Shell Script actions return results.

<a href="bttweb://trigger_named_async_without_response/trigger_name=Action5">

update_touch_bar_widget

This method will update the contents of a Touch Bar Script Widget (identified by its uuid). You can provide a new text to show, a new icon and a new background color.

For the icon you can either provide it directly using the icon_data parameter (must be base64 encoded) or you can provide a file path (via the icon_path parameter) that points to the new icon.

You can get the uuid by right-clicking any script widget in BTT.

Example:

let widgetConfig = {
	text: "hi there!",
	icon_path: "/Users/andi/Desktop/test.png",
	background_color: "200,100,100,255"	
};

update_touch_bar_widget({uuid: '9990CE09-9820-4D67-9C52-8BABAB263056', json: widgetConfig});

trigger_action

This method will trigger any of BetterTouchTool's predefined actions (or any combination of them).

You need to provide a JSON description of the action you want to trigger as a string. The easiest way to get such a JSON description is to right-click the trigger you have configured in BetterTouchTool and choose "Copy JSON". This will copy the complete JSON (including the configuration for the trigger itself), but this action will ignore anything that's not needed. (or you can delete the not needed parts)

Example:

let actionDefinition = {
  "BTTPredefinedActionType" : 153, 
  "BTTPredefinedActionName" : "Move Mouse To Position", 
  "BTTMoveMouseToPosition" : "{100, 100}", 
  "BTTMoveMouseRelative" : "6"
};


let result = await trigger_action({json: JSON.stringify(actionDefinition)});

execute_assigned_actions_for_trigger

This method executes all the assigned actions for a given trigger (i.e. gesture, shortcut, drawing etc.) identified by its uuid.

You can get the uuid by right-clicking any configured trigger in BetterTouchTool.

Example

let result = await execute_assigned_actions_for_trigger({uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});
// Currently only the AppleScript and Shell Script actions return results.

<a href="bttweb://execute_assigned_actions_for_trigger/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Trigger</a>

refresh_widget

This method will execute all scripts assigned to a script widget and update its contents accordingly.

The widget is identified by its uuid, which you can get by right-clicking the widget in BetterTouchTool.

Example

refresh_widget({uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});

<a href="bttweb://refresh_widget/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Refresh Widget</a>

update_trigger

This method will create or update the configuration of any specified trigger (i.e. gestures, shortcuts, touchbar items etc.).

You need to provide the uuid of the trigger you want to update (get by right-clicking it in BTT) and a JSON object defining the updates. To know how the JSON object should look like, right-click the trigger in BTT and choose "Copy JSON".

Example:

Hint: don't forget to use JSON.stringify() before passing the updateDefinition object.

var updateDefinition = {
	"BTTTouchBarButtonName" : "New Name",
	"BTTTouchBarItemIconHeight" : 25
}

update_trigger({uuid: '123e4567-e89b-12d3-a456-426655440000', json: JSON.stringify(updateDefinition)});

get_trigger

This allows you to retrieve the JSON configuration of a trigger identified by its UUID.

let triggerJSONString = await get_trigger({uuid:'123e4567-e89b-12d3-a456-426655440000'})
let parsedJSON = JSON.parse(triggerJSONString);

console.log('parsed json:', parsedJSON);

add_new_trigger

This method will add a new trigger to BTT (i.e. gestures, shortcuts, touchbar items etc.).

You need to provide a JSON object defining the new trigger. To know how the JSON object should look like, right-click any existing trigger in BTT and choose "Copy JSON".

Example

var newTriggerDefinition = {
  "BTTTriggerClass" : "BTTTriggerTypeKeyboardShortcut",
  "BTTPredefinedActionType" : 5,
  "BTTPredefinedActionName" : "Mission Control",
  "BTTAdditionalConfiguration" : "1179648",
  "BTTTriggerOnDown" : 1,
  "BTTEnabled" : 1,
  "BTTShortcutKeyCode" : 2,
  "BTTShortcutModifierKeys" : 1179648,
  "BTTOrder" : 3
}

add_new_trigger({json: JSON.stringify(newTriggerDefinition)});

delete_trigger

This method will delete a trigger from BetterTouchTool. You need to provide the uuid of the trigger you want to delete (get by right-clicking it in BTT).

Example

delete_trigger({uuid: '2F34005D-4537-464D-94E9-A7F42DA39DF1'});

<a href="bttweb://delete_trigger/?uuid=2F34005D-4537-464D-94E9-A7F42DA39DF1">Delete Trigger</a>

get_clipboard_content

Gives you the current text content of the clipboard.

Example

(async ()=> {

let result = await get_clipboard_content({format: "public.html" /*optional*/, asBase64: false, excludeConcealed: false});

returnToBTT(result);

})();

For the format parameter you can use any possible UTI or one of these strings:

Default formats are (more are possible):

all - returns all currently stored formats as a JSON string
NSPasteboardTypeString
NSPasteboardTypeTIFF
NSPasteboardTypePNG
NSPasteboardTypeRTF
NSPasteboardTypeRTFD
NSPasteboardTypeHTML
NSPasteboardTypeTabularText
NSPasteboardTypeFont
NSPasteboardTypeRuler
NSPasteboardTypeColor
NSPasteboardTypeSound
NSPasteboardTypeMultipleTextSelection
NSPasteboardTypeTextFinderOptions
NSPasteboardTypeURL
NSPasteboardTypeFileURL

get_selection

Gives you the currently selected text/item

Example

(async ()=> {

let result = await get_selection({format: "public.html" /*optional*/, asBase64: false});

returnToBTT(result);

})();

For the format parameter you can use any possible UTI or one of these strings:

Default formats are (more are possible):

NSPasteboardTypeString
NSPasteboardTypeTIFF
NSPasteboardTypePNG
NSPasteboardTypeRTF
NSPasteboardTypeRTFD
NSPasteboardTypeHTML
NSPasteboardTypeTabularText
NSPasteboardTypeFont
NSPasteboardTypeRuler
NSPasteboardTypeColor
NSPasteboardTypeSound
NSPasteboardTypeMultipleTextSelection
NSPasteboardTypeTextFinderOptions
NSPasteboardTypeURL
NSPasteboardTypeFileURL

set_persistent_string_variable

This allows you to set a variable to a given string that persists over BTT relaunches.

JavaScript for Automation Example:

set_persistent_string_variable({variable_name: 'test', to: "this is a test value"});

set_string_variable

This allows you to set a variable to a given string. This variable will NOT persist over BTT relaunches.

set_string_variable({variable_name: 'test', to: "this is a test value"});

set_persistent_number_variable

This allows you to set a variable to a given number that persists over BTT relaunches.

set_persistent_number_variable({variable_name: 'test', to: 12345});

set_number_variable

This allows you to set a variable to a given number. This variable will NOT persist over BTT relaunches.

set_number_variable({variable_name:'OutputVolume', to: 0.5});

get_number_variable

This allows you to retrieve the contents of a number variable with the given name

let result = await get_number_variable({variable_name:'OutputVolume'})

get_string_variable

This allows you to retrieve the contents of a string variable with the given name

let result = await get_string_variable({variable_name:'BTTActiveAppBundleIdentifier'})

display_notification

This shows a notification

let result = await display_notification({title:'notification title', subTitle: 'some subtitle', soundName: 'frog', imagePath: '~/Downloads/image.png'})

paste_text

This pastes some text

Parameters:

text: The text to paste.

insert_by_pasting: If set to true BTT will use cmd+v to paste the text. Otherwise it will actually try to type it (only possible for standard formats)

move_cursor_left_by_x_after_pasting: If specified BTT will move the cursor by the given amount to the left.

format: Optional. The format the text will be interpreted as when pasting (e.g. if you want to paste a table, you can set the string to <table>...</table> and specify the format NSPasteboardTypeHTML) Note, this only works if insert_by_pasting is set to true.

Default formats are (more are possible):

NSPasteboardTypeString
NSPasteboardTypeTIFF
NSPasteboardTypePNG
NSPasteboardTypeRTF
NSPasteboardTypeRTFD
NSPasteboardTypeHTML
NSPasteboardTypeTabularText
NSPasteboardTypeFont
NSPasteboardTypeRuler
NSPasteboardTypeColor
NSPasteboardTypeSound
NSPasteboardTypeMultipleTextSelection
NSPasteboardTypeTextFinderOptions
NSPasteboardTypeURL
NSPasteboardTypeFileURL

let result = await paste_text({text:'<strong>Hello world</strong>', format: 'NSPasteboardTypeHTML', insert_by_pasting: true})

set_clipboard_content

Changes the content of the clipboard

Parameters:

content: The content to put in your clipboard. format: Optional. The format the content will be interpreted as when pasting (e.g. if you want to paste a table, you can use set the string to

...

and specify the format NSPasteboardTypeHTML)

Default formats are (more are possible):

NSPasteboardTypeString
NSPasteboardTypeTIFF
NSPasteboardTypePNG
NSPasteboardTypeRTF
NSPasteboardTypeRTFD
NSPasteboardTypeHTML
NSPasteboardTypeTabularText
NSPasteboardTypeFont
NSPasteboardTypeRuler
NSPasteboardTypeColor
NSPasteboardTypeSound
NSPasteboardTypeMultipleTextSelection
NSPasteboardTypeTextFinderOptions
NSPasteboardTypeURL
NSPasteboardTypeFileURL

let result = await set_clipboard_content({content:'<strong>Hello world</strong>', format: 'NSPasteboardTypeHTML'})

get_items_from_clipboard_manager

This function allows you to retrieve arbitrary items from the BTT clipboard manager (if the clipboard manager is active)

Parameters:

start: The offset from which to start retrieving items.
numberOfItems: The number of items to retrieve starting from start
format: Optional: the format you want to retrieve. This defaults to NSPasteboardTypeString (standard string). If you set it to all it will retrieve all stored formats for every item. For other supported formats scroll up to the previous set_clipboard_content function.
snippetGroup: Optional: the name of the snippet group you want to retrieve from
asBase64: Return the content as base64 encoded string
selected: Optional: if set to true, this will return the currently selected items from the open clipboard manager window, in the order they were selected. When using this parameter, start, numberOfItems and snippetGroup are ignored. Returns an empty items array if no clipboard manager window is open or no items are selected.

async function retrieveItems() {
    //additional supported parameters: format, snippetGroup, asBase64 and selected
    // if format is set to "all", it will return all stored information about the requested items, apart from "all" it supports any pasteboard UTI
	return get_items_from_clipboard_manager({start: 0, numberOfItems: 5});
}

async function retrieveSelectedItems() {
    // retrieve the currently selected items from the open clipboard manager, in selection order
    return get_items_from_clipboard_manager({selected: true});
}

The output of this will be a JSON string, you need to use JSON.parse(result) to convert it to a JavaScript object:

{
  "items" : [
   
    {
      "meta" : {
        "copiedFrom" : "com.sublimetext.4",
        "uuid" : "1B1F7F7D-EF28-4B45-9AF1-248768BFCB8C",
        "previewText" : "Test5",
        "date" : "2025-10-01T13:25:09Z"
      },
      "content" : "Test5"
    },
    {
      "meta" : {
        "copiedFrom" : "com.sublimetext.4",
        "uuid" : "10C6C74F-8373-4810-909E-544318EC4ED7",
        "previewText" : "Test4",
        "date" : "2025-10-01T13:25:08Z"
      },
      "content" : "Test4"
    },
    {
      "meta" : {
        "copiedFrom" : "com.sublimetext.4",
        "uuid" : "D8956BBC-7699-43D7-BF22-3E648B05D631",
        "previewText" : "Test3",
        "date" : "2025-10-01T13:25:08Z"
      },
      "content" : "Test3"
    },
    {
      "meta" : {
        "copiedFrom" : "com.sublimetext.4",
        "uuid" : "A9880066-4438-4CD2-A103-FB7E3CAD47FC",
        "previewText" : "Test2",
        "date" : "2025-10-01T13:25:07Z"
      },
      "content" : "Test2"
    },
    {
      "meta" : {
        "copiedFrom" : "com.sublimetext.4",
        "uuid" : "0BD5D9D6-B76D-4E91-99E9-5B59F9067C44",
        "previewText" : "Test1",
        "date" : "2025-10-01T13:25:07Z"
      },
      "content" : "Test1"
    }
  ],
  "latest" : "2025-10-01T13:25:14Z"
}

paste_clipboard_manager_items_with_uuids

This function will paste one or more specific items from the BTT clipboard manager (if the clipboard manager is active)

Parameters:

uuids: A comma separated string with the UUIDs of the clipboard manager items you want to paste. To retrieve these UUIDs use the get_items_from_clipboard_manager function
deleteAfterPaste: if true, the pasted items will be removed from the clipboard manager

async function pasteSomeItems() {
    //additional supported parameters: deleteAfterPaste
	return paste_clipboard_manager_items_with_uuids({uuids: "0BD5D9D6-B76D-4E91-99E9-5B59F9067C44,A9880066-4438-4CD2-A103-FB7E3CAD47FC"});
}

get-selected-text

To access the currently selected text, make use of the selected_text variable like this:

let selectedText = await get_string_variable({variable_name:'selected_text'})

Triggering Scripting Functions from any BetterTouchTool Web View​

1.) Using the bttweb:// links​

2.) Using The Scripting Interface via JavaScript.​

Closing the webview​

Example script function calls:​

resize_webview​

Example​

trigger_named​

Example​

trigger_named_async_without_response​

Example​

update_touch_bar_widget​

Example:​

trigger_action​

Example:​

execute_assigned_actions_for_trigger​

Example​

refresh_widget​

Example​

update_trigger​

Example:​

get_trigger​

add_new_trigger​

Example​

delete_trigger​

Example​

get_clipboard_content​

Example​

get_selection​

Example​

set_persistent_string_variable​

JavaScript for Automation Example:​

set_string_variable​

set_persistent_number_variable​

set_number_variable​

get_number_variable​

get_string_variable​

display_notification​

paste_text​

set_clipboard_content​

get_items_from_clipboard_manager​

paste_clipboard_manager_items_with_uuids​

get-selected-text​

Triggering Scripting Functions from any BetterTouchTool Web View

1.) Using the bttweb:// links

2.) Using The Scripting Interface via JavaScript.

Closing the webview

Example script function calls:

resize_webview

Example

trigger_named

Example

trigger_named_async_without_response

Example

update_touch_bar_widget

Example:

trigger_action

Example:

execute_assigned_actions_for_trigger

Example

refresh_widget

Example

update_trigger

Example:

get_trigger

add_new_trigger

Example

delete_trigger

Example

get_clipboard_content

Example

get_selection

Example

set_persistent_string_variable

JavaScript for Automation Example:

set_string_variable

set_persistent_number_variable

set_number_variable

get_number_variable

get_string_variable

display_notification

paste_text

set_clipboard_content

get_items_from_clipboard_manager

paste_clipboard_manager_items_with_uuids

get-selected-text