adbkeyboard-manual-send-workflow.md 6.12 KB

ADBKeyboard Manual Send Workflow

When to Use

Use this workflow when mcp_android_phone_send_wechat_message fails to find the target group/contact. Confirmed (2026-06-29): The tool fails for BOTH group chats AND individual contacts. Always use this workflow as the primary send method for WeChat.

Prerequisites

  • ADBKeyboard installed (com.android.adbkeyboard/.AdbIME visible in ime list -s)
  • Root access (su)
  • Screen awake and unlocked (verify with mcp_android_phone_get_lock_status)

Verified Complete Workflow (Outer Screen 1080×2364)

Tested and confirmed working 2026-06-29 on Pixel 10 Pro Fold outer screen.

Step 1: Open WeChat

# Ensure WeChat is in foreground
su -c "am start -n com.tencent.mm/.ui.LauncherUI"
sleep 2

CRITICAL: am start with --es Chat_User '<chatroom_id>' does NOT navigate into the group chat — it opens WeChat but stays on the main screen. Use search-and-tap instead:

# 1. Tap the search icon (top-right magnifying glass)
#    For 1080×2364: approximately (897, 225) — verify with OCR each session
su -c "input tap 897 225"
sleep 1

# 2. Type the group name using ADBKeyboard
su -c "ime set com.android.adbkeyboard/.AdbIME"
sleep 0.5
su -c "am broadcast -a ADB_INPUT_TEXT --es msg 'GROUP_NAME'"
sleep 2

# 3. Find the group in search results using OCR
#    Use mcp_android_phone_ocr_find_text to locate it
# 4. Tap the group result center coordinates from OCR
su -c "input tap X Y"
sleep 3

# 5. Verify you're in the group chat — OCR should show "GROUP_NAME(500)" with member count

Pitfall: Search results may show both contacts and groups. Look for the group indicator — member count in parentheses like "(500)". If you accidentally tap a contact, press back twice and re-search.

Step 3: Ensure ADBKeyboard is Set

su -c "ime set com.android.adbkeyboard/.AdbIME"
sleep 0.5

Step 4: Clear Input Field (CRITICAL)

Text accumulation bug: Every ADB_INPUT_TEXT broadcast APPENDS to the existing input field text. Never broadcast without clearing first. If you sent a failed attempt, the text is still in the buffer.

# Clear the field by sending multiple backspace keycodes
# 10-15 backspaces covers most cases
for i in $(seq 1 15); do
  su -c "am broadcast -a ADB_INPUT_CODE --ei code 67"
  sleep 0.1
done

Then verify the field is empty by tapping it and checking with OCR.

Step 5: Type the Message

su -c "am broadcast -a ADB_INPUT_TEXT --es msg 'YOUR MESSAGE HERE'"

Confirmed working (2026-06-29): CJK characters, emoji (📰 🔥 📊), and ASCII all work correctly through ADB_INPUT_TEXT. Multi-line text with literal newlines works too.

Limitations:

  • Very long messages (~1000+ chars) may be truncated by Android broadcast limits
  • The broadcast is atomic — either all text appears or none does
  • Always verify text appeared with OCR before tapping send: bash mcp_android_phone_ocr_find_text --text "KEYWORD_FROM_YOUR_MESSAGE"

Step 6: Find Send Button Position

CRITICAL: The send button POSITION SHIFTS depending on whether the ADBKeyboard is showing. Always use OCR to find its current position — never hardcode coordinates.

# Find send button position dynamically
mcp_android_phone_ocr_find_text --text "发送"
# Returns center coordinates — use these for the tap

Verified positions (2026-06-29), 1080×2364 outer screen:

Keyboard State Send Button (center) Context
Keyboard HIDDEN (983, 2231) After pressing back to dismiss keyboard
Keyboard VISIBLE (983, 2120) While ADBKeyboard is active

Always verify with OCR — positions may differ by WeChat version or screen configuration.

Step 7: Tap Send

# Use OCR-verified coordinates
su -c "input tap X Y"
sleep 3

Step 8: Verify Send in Database

Always verify — do not assume the send succeeded:

SELECT msgId, type, isSend, createTime, substr(content, 1, 80) as preview
FROM message 
WHERE talker = 'CHATROOM_ID@chatroom' 
AND isSend = 1 
AND createTime > RECENT_TIMESTAMP_MS
ORDER BY createTime DESC LIMIT 3

A successful send shows isSend = 1 with a recent createTime (> current epoch ms). If no rows returned, the send failed — check step 6 (wrong send button position) or step 4 (text not actually entered).

Step 9: Restore Keyboard

su -c "ime set com.google.android.inputmethod.latin/com.android.inputmethod.latin.LatinIME"

Troubleshooting Flow

Send failed?
├─ Text not in input field? → Step 4: clear and re-type
├─ Keyboard not showing? → Step 3: re-set ADBKeyboard
├─ Send button tap wrong? → Step 6: re-OCR for position
├─ Wrong chat? → Step 2: back, re-search, verify member count
└─ Chat didn't open? → Step 1-2: restart WeChat, re-navigate

Common Failure Patterns and Fixes

  1. "Text accumulated from previous attempts" → The input field contains leftover text from previous ADB_INPUT_TEXT broadcasts. Fix: Step 4 (clear with backspace).

  2. "Send button not found in OCR" → Keyboard is showing but covering the button, or screen scrolled. Fix: dismiss keyboard with input keyevent 4, then re-OCR.

  3. "Search opened wrong chat" → Tapped a contact instead of the group. The group result shows member count like "(500)". Fix: press back twice, re-search, look for member count.

  4. "ADBKeyboard not typing" → Check ime list -s to confirm ADBKeyboard is set. The ime set command sometimes silently fails after app switches. Re-run Step 3.

  5. "Verify shows no sent message" → The most common cause is tapping the wrong send button position. The button moves when keyboard opens/closes. Re-do Step 6 (OCR for position), re-tap.

Screen-Specific Coordinates (Reference Only — Always Verify with OCR)

Screen Resolution Send (keyboard hidden) Send (keyboard visible) Search Icon
Pixel Fold outer 1080×2364 (983, 2231) (983, 2120) (897, 225)
Pixel Fold inner 2076×2152 TBD TBD TBD