Twitter DM Scraper

An actor for sending bulk direct messages on Twitter/X. This actor authenticates using browser cookies and can send personalized messages to multiple users with configurable delays.

Features

• Bulk DM Sending: Send messages to multiple Twitter users at once
• Cookie Authentication: Uses browser cookies for authentication (no username/password required)
• Rate Limiting: Configurable delays between messages to avoid rate limits
• Error Handling: Comprehensive error handling and logging
• Cross-Platform: Works on Windows, macOS, and Linux

Input Schema

The actor expects a JSON input with the following structure:

{
  "cookies": [
    {
      "name": "auth_token",
      "value": "your_auth_token_value"
    },
    {
      "name": "ct0",
      "value": "your_ct0_value"
    }
  ],
  "targets": [
    "@username1",
    "user_id_123456",
    "https://twitter.com/username2"
  ],
  "message": "Hello! This is a test message.",
  "delay_seconds": 5
}

Input Parameters

Parameter	Type	Required	Description
cookies	Array	Yes	Browser cookies from Twitter/X session
targets	Array	Yes	List of usernames, user IDs, or profile URLs
message	String	Yes	The message to send to all targets
delay_seconds	Number	No	Delay between messages (default: 5 seconds)

Cookie Extraction

To get the required cookies:

Method 1: Browser Developer Tools

1. Log into Twitter/X in your browser
2. Open Developer Tools (F12)
3. Go to Application/Storage tab
4. Navigate to Cookies → twitter.com (or x.com)
5. Export cookies for: auth_token, ct0, kdt, twid

Method 2: Browser Extensions

Use cookie export extensions like:

• Cookie Editor (Chrome/Firefox)
• EditThisCookie (Chrome)

Required Cookies

• auth_token: Authentication token
• ct0: CSRF token
• kdt (optional): Additional security token
• twid (optional): Twitter ID token

Usage Examples

Basic Usage

{
  "cookies": [
    {"name": "auth_token", "value": "abc123..."},
    {"name": "ct0", "value": "def456..."}
  ],
  "targets": ["elonmusk", "twitter", "jack"],
  "message": "Hello from the DM scraper!",
  "delay_seconds": 10
}

Advanced Usage with User IDs

{
  "cookies": [
    {"name": "auth_token", "value": "abc123..."},
    {"name": "ct0", "value": "def456..."},
    {"name": "kdt", "value": "ghi789..."}
  ],
  "targets": [
    "44196397",
    "https://twitter.com/username",
    "another_user"
  ],
  "message": "Custom message with personalization",
  "delay_seconds": 15
}

Output Schema

The actor returns a JSON object with the following structure:

{
  "total_targets": 3,
  "successful_sends": 2,
  "failed_sends": 1,
  "results": [
    {
      "target": "@username1",
      "success": true,
      "error": null,
      "message": "Hello! This is a test message."
    },
    {
      "target": "@username2",
      "success": false,
      "error": "User not found",
      "message": "Hello! This is a test message."
    }
  ]
}

Error Handling

Common errors and solutions:

Authentication Errors

• "No cookies found": Ensure cookies are properly formatted in input
• "Authentication verification failed": Cookies may be expired or invalid
• "404 account/settings": Account may be restricted or suspended

DM Sending Errors

• "User not found": Target username/ID doesn't exist
• "DM send failed": User may have DMs disabled or blocked you
• "Rate limit exceeded": Increase delay_seconds value

Rate Limiting

Twitter has strict rate limits for DMs:

• Recommended delay: 10-30 seconds between messages
• Daily limit: ~1000 DMs per day for verified accounts
• Hourly limit: ~150 DMs per hour

Best Practices

1. Start Small: Test with 2-3 targets first
2. Use Delays: Always set delay_seconds to at least 5 seconds
3. Fresh Cookies: Extract cookies from a fresh browser session
4. Monitor Logs: Check actor logs for authentication and sending status
5. Respect Limits: Don't exceed Twitter's rate limits
6. Personalize Messages: Avoid generic spam-like content

Limitations

• Requires valid Twitter cookies (expires periodically)
• Subject to Twitter's rate limiting and terms of service
• May not work with accounts that have restricted DM settings

Legal and Ethical Considerations

• Comply with Twitter's Terms of Service
• Respect user privacy and consent
• Avoid sending spam or unsolicited messages
• Use for legitimate business or personal communication only
• Consider implementing opt-out mechanisms

License

This actor is provided for educational and legitimate use cases. Users are responsible for compliance with Twitter's terms of service and applicable laws.

---

Note: This tool is designed for legitimate communication purposes. Please use responsibly and in accordance with Twitter's terms of service.