This is a list of all actions BTT supports and their possible JSON representation. The actions have evolved for 15 years, attributes differ a lot among the actions.

• Keyboard Shortcuts
• Mouse Related Actions
  • Left Click
  • Left Click - Without Modifier Keys
  • Right Click
  • Middle Click
  • Double Left Click
  • Ctrl + Left Click
  • Opt + Left Click
  • CMD + Left Click
  • CMD + Double Left Click
  • CMD + Shift + Left Click
  • Custom Mouse Buttons \& Modifiers.
    • 1. Left Click + Shift + Command
    • 2. Right Click with No Modifiers + Physically Pressed Keys
    • 3. Middle Click, Down-Only, with Shift and Left Control
• Action Sequence Flow Actions
  • Delay (Async / Non-Blocking)
  • Delay (Blocking)
  • Execute Action Sequence After Timeout (Cancellable)
  • Cancel Timed / Delayed Action Sequences
  • Ask For Input \& Save To Variable
  • Start Repeat
  • End / Stop Repeat
  • Break
  • Cancel Repeat
  • Wait for Keyboard Input
  • Cancel Wait for Conditions To Become True
  • Wait for Conditions To Become True
  • Cancel Wait for Conditions To Become True
  • Wait for Change Of Focused Window
  • IF Image Is Visible
• Helper Functions

Keyboard Shortcuts

Send a keyboard shortcut to the system - just as if you had pressed it on your keyboard

Basic example:

  {
    "BTTShortcutToSend" : "63,59,58,56,55,49",
  }

The structure of BTTShortcutToSend is always like this:

• First come the modifier key codes, sorted from highest to lowest

• At the end the standard key code

  To only send the key down event, add this:

  {
  "BTTShortcutToSend" : "63,59,58,56,55,49",
  "BTTShortcutUpDown" : "onlyDown",
  }
  

  To only send the key up event, add this:

  {
  "BTTShortcutToSend" : "63,59,58,56,55,49",
  "BTTShortcutUpDown" : "onlyUp",
  }
  

Supported modifier key codes:

Supported Standard key codes:

Mouse Related Actions

Left Click

Performs a left mouse click at the current location. It will include the currently pressed modifier keys.

Parameters:

• BTTPredefinedActionType: 3

Example:

{
    "BTTPredefinedActionType" : 3,
}

Left Click - Without Modifier Keys

Performs a left mouse click at the current location. It will NOT include any modifier keys.

Parameters:

• BTTPredefinedActionType: 421

Example:

{
    "BTTPredefinedActionType" : 421,
}

Right Click

Performs a right mouse click at the current location. It will include the currently pressed modifier keys.

Parameters:

• BTTPredefinedActionType: 4

Example:

{
    "BTTPredefinedActionType" : 4,
}

This action has no additional parameters.

Middle Click

Performs a middle mouse click at the current location. It will include the currently pressed modifier keys.

Parameters:

• BTTPredefinedActionType: 1

Example:

{
    "BTTPredefinedActionType" : 1,
}

Double Left Click

Performs a double left mouse click at the current location. It will include the current modifier keys.

Parameters:

• BTTPredefinedActionType: 54

Example:

{
    "BTTPredefinedActionType" : 54,
}

Ctrl + Left Click

Presses the ctrl modifier key and then performs a left click

Parameters:

• BTTPredefinedActionType: 87

Example:

{
    "BTTPredefinedActionType" : 87,
}

Opt + Left Click

Presses the option modifier key and then performs a left click

Parameters:

• BTTPredefinedActionType: 88

Example:

{
    "BTTPredefinedActionType" : 88,
}

CMD + Left Click

Presses the command modifier key and then performs a left click

Parameters:

• BTTPredefinedActionType: 2

Example:

{
    "BTTPredefinedActionType" : 2,
}

CMD + Double Left Click

Presses the command modifier key and then performs a double left click. This can e.g. be used to open a file in a new tab in Finder.

Parameters:

• BTTPredefinedActionType: 149

Example:

{
    "BTTPredefinedActionType" : 149,
}

CMD + Shift + Left Click

Presses the command modifier key and then performs a left click

Parameters:

• BTTPredefinedActionType: 111

Example:

{
    "BTTPredefinedActionType" : 111,
}

Custom Mouse Buttons & Modifiers.

Perform custom mouse clicks with various options:

Custom Click Examples

1. Left Click + Shift + Command

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "left",
  "BTTModifiers": ["shift", "command"],
  "BTTIncludePressedModifiers": false,
  "BTTClickDownUpConfig": "downAndUp"
}

• Performs a normal (down+up) left click, with Shift and Command pressed, ignoring any physically pressed keys.

2. Right Click with No Modifiers + Physically Pressed Keys

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "right",
  "BTTModifiers": [],
  "BTTIncludePressedModifiers": true,
  "BTTClickDownUpConfig": "downAndUp"
}

• Performs a normal (down+up) right click. Any physically pressed modifier keys (e.g. if you’re holding Shift) are automatically included because BTTIncludePressedModifiers is set to true.

3. Middle Click, Down-Only, with Shift and Left Control

{
  "BTTPredefinedActionType": 119,
  "BTTClickType": "middle",
  "BTTModifiers": ["shift", "left_control"],
  "BTTIncludePressedModifiers": false,
  "BTTClickDownUpConfig": "downOnly"
}

• Issues the mouse-down portion of a middle click and keeps it held down. Shift and left Control are simulated, while physically pressed modifier keys are ignored because BTTIncludePressedModifiers is set to false.

Action Sequence Flow Actions

Delay (Async / Non-Blocking)

This action pauses the execution of the current action sequence but allows the BTT process to continue processing other stuff. Usually you'd use this action to add some delays to your action sequences, e.g. when waiting for some UI to react. If you need longer timeouts (e.g. to trigger something after 10 minutes) use the "Trigger Action Sequence After Timeout" action instead.

Parameters:

• BTTPredefinedActionType: 345
• BTTDelayNextActionBy: The amount of time to pause the action execution. Provided as string with a dot as decimal separator.

Example:

[
 {
    "BTTPredefinedActionType" : 345,
    "BTTDelayNextActionBy" : 2.5
  }
]

Delay (Blocking)

This one freezes the BTT process for the specified amount of time, preventing any action processing during that time. You should only ever use this with small delays.

Parameters:

• BTTPredefinedActionType: 129
• BTTDelayNextActionBy: The amount of time to freeze / block the action execution. Provided as string with a dot as decimal separator.

Note: Usually you should use the "Delay (Async / Non-Blocking) action instead. The blocking one is only helpful for very few usecases.

Example:

 [
  {
    "BTTPredefinedActionType" : 129,
    "BTTDelayNextActionBy" : 2.5
  }
 ]

Execute Action Sequence After Timeout (Cancellable)

This allows to execute an action sequence after a specific amount of time. While the previously described delay actions are only meant to be used for short delays, this one can also be used for longer delays. Addtionally you can specify a name for the timer, which allows you to cancel it if necessary. (Using the predefined action "Cancel Timed Action Sequence")

Parameters:

• BTTPredefinedActionType: 351
• BTTGenericActionConfig: The timeout in seconds as string using a dot as decimal separator.
• BTTGenericActionConfig2: The name of the timer
• BTTAdditionalActions: An array of actions that shall be executes after the timeout.

Example:

{

        "BTTPredefinedActionType" : 351,
        "BTTGenericActionConfig2" : "timerName",
        "BTTGenericActionConfig" : "3.5",
        "BTTAdditionalActions" : [
          {

            "BTTTriggerType" : 740,
            "BTTPredefinedActionType" : 366,
            "BTTTriggerClass" : "BTTTriggerTypeCustomActionConfig",
            "BTTAdditionalActions" : [
              {
                "BTTTriggerClass" : "BTTTriggerTypeCustomActionConfig",
                "BTTPredefinedActionType" : 3,
              },
              {
                "BTTTriggerClass" : "BTTTriggerTypeCustomActionConfig",
                "BTTPredefinedActionType" : 3,
              }
            ]
          }
        ]
      }

Cancel Timed / Delayed Action Sequences

Cancels the execution of a action sequences that has been scheduled via predefined action "Execute Action Sequence After Timeout (Cancellable)".

Parameters:

• BTTPredefinedActionType: 352
• BTTGenericActionConfig2: The name of the scheduled action sequence you want to cancel.

Example:

  {
    "BTTPredefinedActionType" : 352,
    "BTTGenericActionConfig2" : "theNameOfTheTimer"
  }

Ask For Input & Save To Variable

Shows a floating input field and saves the entered text into a variable.

Parameters:

• BTTPredefinedActionType: 403
• BTTAdditionalActionData: Contains the configuration object
  • BTTActionAskForInputPrompt The input prompt (string)
  • BTTActionAskForInputVariableName The variable name (string)
  • BTTActionAskForInputVariableType: 0 - String or 1 Number
  • BTTActionAskForInputOnlyHideOnEnterOrEsc: 0: Hide when clicking outside, when hitting esc or when hitting enter. 1: Hide when hitting esc or when hitting enter.
  • BTTActionAskForInputUseActivatingWindow If set to 1 the window will take focus - might be necessary in some situations to receive keyboard input.

Example:

{
    "BTTPredefinedActionType" : 403,
    "BTTAdditionalActionData" : {
      "BTTActionAskForInputVariableName" : "address",
      "BTTActionAskForInputPrompt" : "Enter your address:"
    }
  }

Start Repeat

This marks the start of a for loop / repeat. All actions that come between this and the "End / Stop Repeat" action will be repeated.

Parameters:

• BTTPredefinedActionType: 329
• BTTGenericActionConfig: The name of the for loop
• BTTAdditionalActionData: Contains further action configuration object
  • BTTActionForLoopRepeat : Number of times the for loop should repeat (number)
  • BTTActionForLoopRepeatVariable: If the number of repeats is controlled by a BTT variable, you can specify the variable here.

Example:

{
    "BTTPredefinedActionType" : 329,
    "BTTAdditionalActionData" : {
      "BTTActionForLoopRepeat" : 99
    },
    "BTTGenericActionConfig" : "nameOfTheLoop",
  }

End / Stop Repeat

Marks the end of the repeat / for loop

Parameters:

• BTTPredefinedActionType: 332

Example:

 {
    "BTTPredefinedActionType" : 332
  }

Break

Can only be used between "Start Repeat" and "End/Stop Repeat". Behaves like a standard break e.g. in Java Script.

Parameters:

• BTTPredefinedActionType: 332

Example:

 {
    "BTTPredefinedActionType" : 332
  }

Cancel Repeat

This will cancel the specified repeat loop (if it is running)

Parameters:

• BTTPredefinedActionType: 424
• BTTGenericActionConfig: The name of the repeat / loop that shall be canceled.

Example:

[
  {
    "BTTPredefinedActionType" : 424,
    "BTTGenericActionConfig" : "theLoopIdentifier"
  }
]

Wait for Keyboard Input

This will pause the currently executing action sequence until the specified continue or cancel key has been pressed

Parameters:

• BTTPredefinedActionType: 486
• BTTActionWaitForKeyboardInputCancelKeyCode: A keycode that cancels the action sequence when pressed (number)
• BTTActionWaitForKeyboardInputContinueKeyCode: A keycode that continues the action sequence when pressed (number)
• BTTActionWaitForKeyboardInputTimeout: A keycode that continues the action sequence when pressed (number)

A list of macOS key codes can be found at the top of this document in the Keyboard Shortcuts section or alternatively here: https://eastmanreference.com/complete-list-of-applescript-key-codes

Example:

[
  {
    "BTTPredefinedActionType" : 486,
    "BTTActionWaitForKeyboardInputCancelKeyCode" : 7,
    "BTTActionWaitForKeyboardInputContinueKeyCode" : 8,
    "BTTActionWaitForKeyboardInputTimeout" : 10
  }
]

Cancel Wait for Conditions To Become True

This will pause the currently executing action sequence until the specified conditions have been met

Parameters:

• BTTPredefinedActionType: 418
• BTTGenericActionConfig: The identifier of the condition wait that you want to cancel *

Example:

[
  {
    "BTTPredefinedActionType" : 418,
    "BTTGenericActionConfig" : "example"
  }
]

Wait for Conditions To Become True

This will pause the currently executing action sequence until the specified conditions have been met

Parameters:

• BTTPredefinedActionType: 417
• BTTWaitForConditionFormat: The condition to be met (read only)
• BTTWaitForConditionData:The condition to be met (data, can only be created via BTT UI)
• BTTGenericActionConfig: An identifier to reference the wait
• BTTGenericActionConfig2: A JSON string with the properties BTTActionWaitForConditionsInterval and BTTActionWaitForConditionsTimeout

Example:

[
   {
    "BTTPredefinedActionType" : 417,
    "BTTWaitForConditionFormat" : "fingers_touching_trackpad >= 5",
    "BTTWaitForConditionData" : "base64encodedconditiondata", // unfortunately this can currently only be created via BTT's UI
    "BTTGenericActionConfig" : "identifier",
    "BTTGenericActionConfig2" : "{"BTTActionWaitForConditionsInterval" : 2, "BTTActionWaitForConditionsTimeout" : 10}",
  }
]

Cancel Wait for Conditions To Become True

This will pause the currently executing action sequence until the specified conditions have been met

Parameters:

• BTTPredefinedActionType: 418
• BTTGenericActionConfig: The identifier of the condition wait that you want to cancel *

Example:

[
  {
    "BTTPredefinedActionType" : 418,
    "BTTGenericActionConfig" : "example"
  }
]

Wait for Change Of Focused Window

This will pause the currently executing action sequence until the focused window changes

Parameters:

• BTTPredefinedActionType: 423
• BTTGenericActionConfig2: A JSON string with the properties BTTActionWaitForFocusChangeInterval and BTTActionWaitForFocusChangeTimeout

Example:

[
  {
    "BTTPredefinedActionType" : 423,
    "BTTGenericActionConfig2" : "{"BTTActionWaitForFocusChangeInterval" : 2,"BTTActionWaitForFocusChangeTimeout" : 10}"
  }
]

IF Image Is Visible

This starts a if control structure with an if and else branch. The if branch is entered if a specified image is currently visible on screen.

Parameters:

• BTTPredefinedActionType: 423
• BTTGenericActionConfig2: A JSON string with the properties BTTActionWaitForFocusChangeInterval and BTTActionWaitForFocusChangeTimeout

Example:

[
  {
    "BTTPredefinedActionType" : 423,
    "BTTGenericActionConfig2" : "{"BTTActionWaitForFocusChangeInterval" : 2,"BTTActionWaitForFocusChangeTimeout" : 10}"
  }
]

BTTPredefinedActionIFImageVisible BTTPredefinedActionIFTextVisible BTTPredefinedActionIFJSTrue BTTPredefinedActionIF BTTPredefinedActionELSE BTTPredefinedActionENDIF BTTPredefinedActionControlFlowWaitForImageToBecomeVisible BTTPredefinedActionWaitForTextOnScreen BTTPredefinedActionToggleMultiple

Helper Functions

function getModifierBitmask(modifiers) {
    const modifierMap = {
        "Shift": 1 << 17,
        "Control": 1 << 18,
        "Left Control": 1 << 0, 
        "Right Control": 1 << 13, 
        "Option": 1 << 19,
        "Left Option": 1 << 5, 
        "Right Option": 1 << 6, 
        "Command": 1 << 20,
        "Left Command": 1 << 3, 
        "Right Command": 1 << 4,
        "Function": 1 << 23
    };

    let bitmask = 0;

    for (const modifier of modifiers) {
        if (modifierMap[modifier] !== undefined) {
            bitmask |= modifierMap[modifier];
        } else {
            console.warn(`Unknown modifier: ${modifier}`);
        }
    }

    return bitmask;
}