Call BTT Functions from the WebView

Triggering Scripting Functions from any BetterTouchTool Web View

The floating webview lets you trigger various scripting functions via JavaScript.

Important Note: After loading, the webview needs a few milliseconds to set up BTT's scripting infrastructure. So only call the scripting functions after the BTTInitialize function has been called (or use a 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 (creates a trigger, or updates it if it already exists)
add_new_trigger
delete_trigger
delete_triggers
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
display_notification
paste_text
set_clipboard_content
get_clipboard_content
get_items_from_clipboard_manager
paste_clipboard_manager_items_with_uuids
get_selection (call it via callBTT('get_selection', ...), see below)

Floating Menus:

update_menu_item
get_menu_item_value
set_menu_item_value
webview_menu_item_load_html_url_js

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

Built-In Scripting Variables

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

1.) Using the bttweb:// links

bttweb:// is a custom URL scheme that lets you trigger scripting functions and get their results, just like any other http call. You can use these links in normal a elements <a href="bttweb://trigger_named/?trigger_name=test"></a>, or load them with XMLHttpRequest or fetch.

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 in the floating webview. You can use them to call the scripting functions listed above.

Closing the webview

You can close the floating webview by passing the closeFloatingWebView parameter set to 1. For example: trigger_named({trigger_name: 'test', closeFloatingWebView:1}).

Example script function calls:

resize_webview

This method resizes the floating webview to the specified width and height.

Example

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

trigger_named

This method triggers the specified named trigger (you can configure named triggers in the "Automations, Named & Other Triggers" section in BetterTouchTool).

Example

let result = await trigger_named({trigger_name: 'Action5'});
// Script actions (e.g. AppleScript, JavaScript, shell scripts, Shortcuts) return their result. Most other actions don't return anything useful.

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

trigger_named_async_without_response

This method triggers the specified named trigger (you can configure named triggers in the "Automations, Named & Other Triggers" section in BetterTouchTool). It doesn't wait for a response.

Example

trigger_named_async_without_response({trigger_name: 'Action5'});
// This doesn't wait for the trigger, so you don't get its result. Use trigger_named if you need it.

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

update_touch_bar_widget

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

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

You can get the uuid by right-clicking any script widget in BTT and choosing "Copy Selected Item UUID".

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 triggers any of BetterTouchTool's predefined actions (or any combination of them).

You need to pass a JSON description of the action you want to trigger, as a string. The easiest way to get that JSON is to right-click a trigger you've configured in BetterTouchTool and choose "Copy" (cmd+c). This copies the complete JSON, including the configuration of the trigger itself. trigger_action ignores anything it doesn't need, but you can also delete the unneeded parts yourself.

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 of a given trigger (e.g. a 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'});
// Script actions (e.g. AppleScript, JavaScript, shell scripts, Shortcuts) return their result. Most other actions don't return anything useful.

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

refresh_widget

This method runs all scripts assigned to a script widget and updates 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 creates or updates the configuration of any specified trigger (e.g. gestures, shortcuts, Touch Bar items, etc.).

You need to provide the uuid of the trigger you want to update (you can get it by right-clicking the trigger in BTT) and a JSON object that defines the updates. To see what the JSON object should look like, right-click the trigger in BTT and choose "Copy" (cmd+c). This copies its 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 lets you get 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 adds a new trigger to BTT (e.g. a gesture, shortcut, Touch Bar item, etc.).

You need to provide a JSON object that defines the new trigger. To see what the JSON object should look like, right-click any existing trigger in BTT and choose "Copy" (cmd+c). This copies its 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 deletes a trigger from BetterTouchTool. You need to provide the uuid of the trigger you want to delete (you can get it by right-clicking the trigger 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 clipboard content. By default you get plain text. Use format to ask for another format. If the clipboard doesn't have that format, you get the plain text instead. Set asBase64 to true to get the raw data as base64 (e.g. for images). With excludeConcealed set to true, you get an empty result if the clipboard content is marked as concealed or transient (e.g. a password copied from a password manager).

Example

(async ()=> {

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

console.log(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 or item. In the webview, this function isn't available as a separate JavaScript function. Call it via the generic callBTT helper instead (or via bttweb://get_selection/?...).

Example

(async ()=> {

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

console.log(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

Sets a variable to a given string. The variable persists across BTT relaunches.

Example

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

set_string_variable

Sets a variable to a given string. This variable does NOT persist across BTT relaunches.

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

set_persistent_number_variable

Sets a variable to a given number. The variable persists across BTT relaunches.

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

set_number_variable

Sets a variable to a given number. This variable does NOT persist across BTT relaunches.

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

get_number_variable

Gets the value of the number variable with the given name.

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

get_string_variable

Gets the value of the string variable with the given name.

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

display_notification

Shows a notification.

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

paste_text

Pastes text.

Parameters:

text: The text to paste.

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

move_cursor_left_by_x_after_pasting: If specified, BTT moves the cursor to the left by the given amount.

format: Optional. The format to interpret the text as when pasting (e.g. to paste a table, 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 on the clipboard. This doesn't paste anything, it only sets the clipboard. By default the content is stored as plain text.

format: Optional. The format to store the content as (e.g. to copy a table, set the content to <table>...</table> and specify the format NSPasteboardTypeHTML). For NSPasteboardTypePNG or NSPasteboardTypePDF, pass the data as base64.

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 lets you retrieve any 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. Defaults to NSPasteboardTypeString (standard string). If you set it to all, it retrieves all stored formats for every item. For other supported formats, see the set_clipboard_content function above.
snippetGroup: Optional: the name of the snippet group you want to retrieve items from.
asBase64: Return the content as a base64 encoded string.
selected: Optional: if set to true, this returns the items currently selected in the open clipboard manager window, in the order they were selected. When you use this parameter, start, numberOfItems, and snippetGroup are ignored. If no clipboard manager window is open or no items are selected, it returns an empty items array.

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 result is a JSON string. Use JSON.parse(result) to convert it into 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 pastes 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 get these UUIDs, use the get_items_from_clipboard_manager function.
deleteAfterPaste: If true, the pasted items are 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 get the currently selected text, use 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​

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

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