Labsco
browser-act logo

x-dm-auto-chat

★ 3,745

by browser-act · part of browser-act/skills

X (Twitter) DM automated chat end-to-end Skill: scan DM inbox to identify pending-reply conversations, read message history, generate persona-based replies and send; also supports searching users and starting new conversations. Built-in E2E passcode unlock, DM permission filtering, and rate control. Use when user mentions X auto-reply DMs, Twitter DM automated chat, auto-handle unread DMs, reply to X private messages with persona, X DM outreach campaign, batch send DMs to Twitter users, auto-pro

🧩 One of 7 skills in the browser-act/skills package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

X (Twitter) — DM Auto Chat (End-to-End)

Full X DM automation Skill: inbox scan → conversation read → persona-based reply → send; also supports search-and-outreach. The calling Agent generates reply text based on persona; this Skill handles all mechanical operations.

Language

All process output to user (progress updates, process notifications) follows the user's language.

Objective

Encapsulate "refresh DM list → identify pending replies → read context → reply with persona → send" and "search user → enter chat → send first message" into callable end-to-end capabilities.

Pre-execution Checks

1. Tool Readiness

If browser-act has been confirmed available in the current session → skip.

Invoke browser-act via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

2. Open DM Entry + Comprehensive State Check

browser-act --session <name> navigate https://x.com/i/chat
browser-act --session <name> wait stable --timeout 15000
browser-act --session <name> eval "$(python scripts/check-page-state.py)"

Return format:

{
  "url": "https://x.com/i/chat/pin/recovery?from=%2Fi%2Fchat",
  "logged_in": true,
  "need_passcode": true,
  "on_inbox": false,
  "on_conversation": false,
  "has_panel": false,
  "has_composer": false,
  "inbox_count": 0
}

Decision matrix:

  • logged_in: false → inform user to log in first; wait; retry this step
  • need_passcode: true → proceed to step 3 below
  • on_inbox: true and inbox_count > 0 → ready, enter business flow
  • on_inbox: true but inbox_count === 0 → account has no DM conversations; outreach scenario can still proceed, pending-reply scenario has nothing to do

3. DM Passcode Unlock (when need_passcode is true)

  1. If caller has provided passcode in advance → use it directly; otherwise ask user for 4-digit DM passcode via AskUserQuestion tool (do not use plain text prompt — must call AskUserQuestion)
  2. browser-act --session <name> state — find indexes of 4 <input maxlength=1 pattern=[0-9]*> elements (usually 4 consecutive)
  3. Enter each digit: browser-act --session <name> input <idx1> "<d1>", <idx2> "<d2>", <idx3> "<d3>", <idx4> "<d4>"
    • Must use browser-act input (CDP real keyboard events), cannot use eval to set value — X ignores non-real keyboard input
  4. browser-act --session <name> wait stable --timeout 10000
  5. Re-run check-page-state.py, confirm need_passcode: false and on_inbox: true
  6. 3 consecutive failures still showing need_passcode: true → inform user passcode may be wrong; terminate

Business Flows

Choose Scenario A, Scenario B, or both. Each scenario is an ordered AI Workflow (not a single JS).

Scenario A: Scan unread DMs → Persona-based reply

Flow: Scan inbox → Filter unread & latest peer messages → Per-conversation: read context → Generate reply with persona → Send → Next

Steps:

  1. Scan inbox:

    browser-act --session <name> eval "$(python scripts/scan-inbox-merged.py)"

    Returns items[], each containing conversation_id / conversation_url / peer_screen_name / peer_display_name / peer_can_dm / latest_message_preview / latest_message_from_self / unread, etc.

  2. Filter pending-reply conversations: from items, select conversations meeting all conditions:

    • unread === true (has unread) or latest_message_from_self === false (peer's latest message not yet replied)
    • peer_can_dm === true (recipient allows DM)
    • is_muted !== true and is_deleted_by_viewer !== true
    • Optional caller filters: only reply to specific screen_names, exclude already-replied (use external JSONL ledger)

  3. For each pending-reply conversation (strictly serial, random sleep 8-15 seconds between each):

    a. Open conversation:

    browser-act --session <name> navigate https://x.com<conversation_url>
browser-act --session <name> wait stable --timeout 15000

    b. If passcode re-triggered → re-unlock (usually won't re-trigger within same session)

    c. Read context:

    browser-act --session <name> eval "$(python scripts/read-conversation.py)"

    Returns messages[], each with direction (self/peer), text, timestamp_text, links, images.

    d. (Optional) Load full history: If caller needs longer context, loop:

    browser-act --session <name> eval "$(python scripts/scroll-load-history.py)"

    Until reached_top: true, then re-read with read-conversation.py.

    e. Generate reply: Calling Agent combines persona, message history to generate reply text. Reply content is entirely the caller's decision; this Skill does not participate in generation. Suggested inputs:

    • Persona prompt (provided by caller)
    • Recent N messages (typically messages.slice(-6))
    • Peer name (peer_display_name / peer_screen_name) for address
    • Return one string reply_text, length < 10,000 characters

    f. Send reply:

    1. browser-act --session <name> eval "$(python scripts/check-composer.py)" → record last_message_id
    2. browser-act --session <name> state — find <textarea placeholder=Message> index TA_IDX
    3. browser-act --session <name> input <TA_IDX> "<reply_text>" (must use CDP real keyboard, cannot use eval)
    4. browser-act --session <name> wait --selector '[data-testid="dm-composer-send-button"]' --state attached --timeout 5000
    5. browser-act --session <name> eval "document.querySelector('[data-testid=\"dm-composer-send-button\"]').click(); 'clicked'"
    6. browser-act --session <name> wait stable --timeout 15000
    7. Verify: browser-act --session <name> eval "$(python scripts/verify-sent.py '<reply_text>' --prev-last-id <last_message_id from step f1>)"
      • sent: true and composer_cleared: true → success, record result
      • sent: false → record failure, do not retry (prevents duplicate sends); proceed to next conversation

    g. Random delay: sleep 8-15 seconds (avoid anti-abuse limits)

  4. Batch completion: Summarize results (success count / failure count / conversation_id per item); return or write to external log file.

Scenario B: Search users → Start new conversation → Send first message

Flow: Search candidates → Filter sendable → Enter conversation → Generate first message → Send

Steps:

  1. Search target users (one search per target, 1-2 second interval between searches):

    browser-act --session <name> eval "$(python scripts/search-users.py '<search_query>')"

    Returns users[], each with user_id / name / screen_name / can_dm / can_dm_reason / verification fields.

  2. Filter users who can receive DMs:

    • can_dm === true and !suspended and !protected
    • can_dm_reason === "Allowed"
    • If screen_name is already in send history → skip (deduplication)

  3. For each target user (strictly serial, sleep 10-20 seconds between each):

    a. Calculate conversation URL:

    browser-act --session <name> eval "$(python scripts/open-conversation-by-user.py '<user_id>')"

    Returns conversation_url (e.g., /i/chat/{smaller_id}-{larger_id}).

    b. Navigate to conversation:

    browser-act --session <name> navigate https://x.com<conversation_url>
browser-act --session <name> wait stable --timeout 15000

    c. Handle passcode (may appear on first DM entry) → unlock

    d. Verify composer ready:

    browser-act --session <name> eval "$(python scripts/check-composer.py)"

    composer_ready: true → record last_message_id; false → skip this user

    e. Generate first message: Calling Agent generates first outreach text first_text based on persona + target user info (screen_name / name / verification type). Suggested content:

    • Brief self-introduction (caller identity)
    • Personalized reason for reaching out to this specific user
    • Clear call-to-action
    • Keep length < 500 characters (first messages that are too long are more likely to be flagged as spam)

    f. Send: Follow the 7 sub-steps in "Scenario A step 3f", substituting first_text for reply_text.

    g. Random delay: sleep 10-20 seconds

  4. Batch completion: Summarize results.

Capability Components (callable individually)

In addition to the Scenario A / B end-to-end flows, the following components can also be called directly:

Composite: Inbox scan (API + DOM merged)

browser-act --session <name> eval "$(python scripts/scan-inbox-merged.py)" Returns merged conversation list with peer screen_name + message preview + unread flag.

API: Fetch inbox from API only (with pagination)

browser-act --session <name> eval "$(python scripts/fetch-inbox-api.py --cursor-id {cursor_id} --graph-snapshot-id {snap} --limit {N})"

DOM: Read current conversation messages

browser-act --session <name> eval "$(python scripts/read-conversation.py)"

DOM: Scroll to load message history

browser-act --session <name> eval "$(python scripts/scroll-load-history.py)"

DOM: Check composer state

browser-act --session <name> eval "$(python scripts/check-composer.py)"

DOM: Verify message was sent

browser-act --session <name> eval "$(python scripts/verify-sent.py '<expected_text>' --prev-last-id <last_id>)"

API: Search X users (with DM permission)

browser-act --session <name> eval "$(python scripts/search-users.py '<query>')"

JS: Calculate conversation URL from user_id

browser-act --session <name> eval "$(python scripts/open-conversation-by-user.py '<user_id>')"

JS: Comprehensive page state check

browser-act --session <name> eval "$(python scripts/check-page-state.py)"

Success Criteria

End-to-end Scenario A:

  • sent: true rate >= 90% for each pending-reply conversation
  • Failed conversations have clear reason recorded (wrong passcode, composer unavailable, 429, etc.)

End-to-end Scenario B:

  • All filtered sendable users enter conversation page (composer_ready: true)
  • First message sent: true rate >= 90%

Atomic components: see success criteria in each atomic Skill (scripts in this directory fully reuse the atomic implementations).

Execution Efficiency

  • Batch processing: One run processes one batch (N conversations or N target users) then returns; no long-running resident loop — let the caller decide the scheduling cadence
  • Strictly serial: All DM operations for the same account must be serial — no parallel; parallel operations accelerate anti-abuse triggering
  • No retry on failure: DM send failures are usually permission / rate / network issues; retrying risks duplicate sends — record uniformly and skip
  • Resume from breakpoint: Batch tasks use JSONL to record {target, status, timestamp, error?} per item; resume from breakpoint on interruption
  • Small-scale validation first: Before bulk runs, validate the full pipeline with 1-2 items, then scale to full batch
  • Reuse browser session: Use the same browser-act session (e.g., --session x-dm) for the whole batch; passcode unlock and login state persist within the session, no need to re-unlock for each item

Experience Notes

Path: {working-directory}/browser-act-skill-forge-memories/x-dm-automation-x-dm-auto-chat.memory.md (working directory is determined by the Agent running the Skill)

Before execution: If the file exists, read it first — it records unexpected situations encountered during past executions (e.g., a strategy has become ineffective, a selector changed, a rate threshold discovered); adjust strategy order accordingly.

After execution: If an unexpected situation is encountered (strategy became ineffective, page redesigned, anti-scraping upgraded, better path discovered, new can_dm_reason enum values), append a line: {YYYY-MM-DD}: {what happened} → {conclusion}

Normal execution does not write to the file. Do not record what keywords were used, which conversations were replied to, or how many messages were sent — those are task outputs, not experience.