WhatsApp macOS Automation via AppleScript - Findings

gistfile0.txt

# WhatsApp macOS Automation via AppleScript

Findings from a session attempting to automate WhatsApp Desktop on macOS using AppleScript/osascript.

---

## Prerequisites

1. **Accessibility permissions**: Terminal (or the app running osascript) needs accessibility access in System Settings → Privacy & Security → Accessibility
2. **WhatsApp Desktop** must be installed and running

---

## What Works

### Activating WhatsApp
```applescript
tell application "WhatsApp" to activate
```

### Opening Search (Cmd+F)
```applescript
tell application "System Events"
    tell process "WhatsApp"
        keystroke "f" using command down
    end tell
end tell
```

### Typing in Search
```applescript
keystroke "Contact Name"
```

### Clearing Previous Search Text
```applescript
keystroke "a" using command down  -- select all
key code 51                        -- delete/backspace
```

### Getting Window Position/Size
```applescript
tell application "System Events"
    tell process "WhatsApp"
        set winPos to position of window 1
        set winSize to size of window 1
    end tell
end tell
```

### Clicking at Coordinates
```applescript
tell application "System Events"
    click at {x, y}
end tell
```

---

## What Doesn't Work Well

### Direct Text Field Access
WhatsApp uses custom UI elements - standard AppleScript text field queries return nothing:
```applescript
set textFields to every text field of window 1  -- returns 0
set textAreas to every text area of window 1    -- returns 0
```

### Keyboard Navigation to Message Input
After finding a contact via search, pressing Enter/Down Arrow doesn't reliably move focus to the message input field. The search results appear but you need to **click** to open the conversation and click again to focus the message input.

### Multi-line Messages
Newlines in `keystroke` don't translate to line breaks in WhatsApp. This:
```applescript
keystroke "Line 1

Line 2"
```
Results in text running together. URLs at the end of paragraphs can merge with preceding text.

---

## Working Approach: Coordinate-Based Clicking

The reliable method is:
1. Activate WhatsApp
2. Open search (Cmd+F)
3. Clear previous text (Cmd+A, Delete)
4. Type contact name
5. Wait for results
6. **Click** on the message input field at the bottom-right using coordinates
7. Type message (single line works best)
8. Press Enter to send

```applescript
tell application "WhatsApp" to activate
delay 0.5

tell application "System Events"
    tell process "WhatsApp"
        -- Get window geometry
        set winPos to position of window 1
        set winSize to size of window 1
        set winX to item 1 of winPos
        set winY to item 2 of winPos
        set winWidth to item 1 of winSize
        set winHeight to item 2 of winSize
        
        -- Open search and find contact
        keystroke "f" using command down
        delay 0.3
        keystroke "a" using command down
        key code 51
        delay 0.2
        keystroke "Contact Name"
        delay 1.5
        
        -- Click on conversation to open it
        key code 125  -- down arrow
        delay 0.2
        key code 36   -- enter
        delay 0.5
    end tell
    
    -- Click on message input (bottom right of window)
    -- Adjust these percentages based on WhatsApp's layout
    set clickX to winX + (winWidth * 0.7)
    set clickY to winY + (winHeight * 0.97)
    click at {clickX, clickY}
    delay 0.3
    
    -- Type and send
    keystroke "Your message here"
    key code 36  -- enter to send
end tell
```

---

## Key Codes Reference

| Key | Code |
|-----|------|
| Enter/Return | 36 |
| Delete/Backspace | 51 |
| Down Arrow | 125 |
| Up Arrow | 126 |
| Escape | 53 |

---

## Recommendations

1. **Keep messages single-line** to avoid formatting issues
2. **Send URLs separately** if they need to be clickable
3. **Add delays** (0.3-1.5s) between actions - WhatsApp UI needs time to respond
4. **Use coordinate clicking** for the message input rather than keyboard navigation
5. **Calculate coordinates dynamically** based on window position/size for reliability

---

## Limitations

- No direct access to WhatsApp's internal state (contacts list, message history)
- Can't read incoming messages
- UI automation is fragile - WhatsApp updates may break coordinate calculations
- No official AppleScript dictionary for WhatsApp

---

*Tested February 2026, macOS, WhatsApp Desktop*