Skip to content

Latest commit

 

History

History
557 lines (438 loc) · 11.6 KB

README.md

File metadata and controls

557 lines (438 loc) · 11.6 KB

BotWitter API - Python Client Library

PyPI version Python Support License: MIT

Official Python client library for BotWitter API - A comprehensive Twitter automation and management platform.

Installation

Install using pip:

pip install botwitter-api

Or install from source:

git clone https://github.com/botwitter/python-api.git
cd python-api
pip install -e .

Quick Start

from botwitter import BotWitterClient

# Initialize client
client = BotWitterClient(
    base_url="http://localhost:8080/api/v1",
    auth_token="your-auth-token"  # Optional
)

# List all accounts
accounts = client.accounts.list()
print(f"Total accounts: {accounts['pagination']['total']}")

# Create a new account
account = client.accounts.create({
    "username": "mybot",
    "password": "secure_password",
    "email": "mybot@example.com",
    "auto_assign_proxy": True
})

# Follow a user
result = client.accounts.follow(
    username="mybot",
    target_username="elonmusk"
)

# Create a tweet
tweet = client.accounts.tweet(
    username="mybot",
    text="Hello Twitter! 🚀"
)

Core Features

🔐 Account Management

# Create account
account = client.accounts.create({
    "username": "testuser",
    "cookie": "auth_token=xxx; ct0=yyy",  # Cookie-based auth
    "tags": ["bot", "automation"],
    "auto_assign_proxy": True
})

# Bulk create accounts
result = client.accounts.bulk_create([
    {"username": "bot1", "password": "pass1"},
    {"username": "bot2", "password": "pass2"},
])

# Get account by username
account = client.accounts.get_by_username("testuser")

# Update profile
client.accounts.update_profile(
    account_id=1,
    name="Bot Account",
    bio="Automated Twitter bot",
    location="San Francisco"
)

# Change password
client.accounts.change_password(
    username="testuser",
    new_password="new_secure_pass"
)

📊 Account Actions

# Follow/Unfollow
client.accounts.follow(username="mybot", target_username="elonmusk")
client.accounts.unfollow(username="mybot", user_id=123456789)

# Like/Unlike tweets
client.accounts.like(username="mybot", tweet_id="1234567890")
client.accounts.unlike(username="mybot", tweet_url="https://x.com/user/status/123")

# Retweet/Unretweet
client.accounts.retweet(username="mybot", tweet_id="1234567890")
client.accounts.unretweet(username="mybot", tweet_id="1234567890")

# Reply to tweets
client.accounts.reply(
    username="mybot",
    text="Great tweet!",
    tweet_id="1234567890"
)

# Quote tweet
client.accounts.quote(
    username="mybot",
    text="Adding my thoughts...",
    tweet_id="1234567890"
)

# Bookmark tweet
client.accounts.bookmark(username="mybot", tweet_id="1234567890")

🌾 Farming (Automated Engagement)

from botwitter.models import FarmingConfig

# Configure farming
config = FarmingConfig(
    likesPerHour=10,
    followsPerHour=5,
    retweetsPerHour=8,
    aiRepliesPerHour=3,
    likesEnabled=True,
    followsEnabled=True,
    retweetsEnabled=True,
    aiRepliesEnabled=True,
    # Filters
    keywordFilters=["crypto", "bitcoin", "blockchain"],
    excludeKeywords=["scam", "airdrop"],
    languageFilters=["en", "tr"],
    minLikeCount=10,
    maxLikeCount=10000,
    onlyVerifiedUsers=False,
    # Sleep schedule
    sleepEnabled=True,
    activeStartHour=7,
    activeEndHour=23,
)

# Start farming
result = client.farming.start(
    account_id=1,
    config=config
)

# Get farming status
status = client.farming.get_status(username="mybot")
print(f"Total likes: {status.total_likes}")
print(f"Total follows: {status.total_follows}")

# Pause/Resume farming
client.farming.pause(account_id=1)
client.farming.resume(account_id=1)

# Stop farming
client.farming.stop(account_id=1)

📡 RSS to Twitter Posting

from botwitter.models import RSSPostingConfig

# Add RSS feed
subscription = client.rss.add_feed(
    account_id=1,
    feed_url="https://example.com/feed.xml",
    feed_title="Tech News",
    check_interval_seconds=300
)

# Configure RSS posting
config = RSSPostingConfig(
    autoPostEnabled=True,
    maxPostsPerHour=5,
    tweetTemplate="{title}\n\n{link}",
    keywordFilters=["tech", "AI"],
    excludeKeywords=["spam"],
)

client.rss.set_config(account_id=1, config=config)

# Start RSS posting
client.rss.start(account_id=1)

# Stop RSS posting
client.rss.stop(account_id=1)

🔄 Batch Operations

from botwitter.models import BatchOperationRequest, BatchOperationType

# Create batch operation
batch = client.batch.create(
    BatchOperationRequest(
        operation=BatchOperationType.FOLLOW_USER,
        account_ids=[1, 2, 3, 4, 5],
        data={"user_id": "elonmusk"},
        delay_ms=5000  # 5 seconds delay between operations
    )
)

print(f"Batch ID: {batch.batch_id}")

# Get batch status
status = client.batch.get(batch.batch_id)
print(f"Completed: {status.completed_count}/{status.total_count}")

# Pause/Resume batch
client.batch.pause(batch.batch_id)
client.batch.resume(batch.batch_id)

# Cancel batch
client.batch.cancel(batch.batch_id)

🎯 Task Automation

from botwitter.models import FollowTaskRequest, FollowMode, FollowConfig

# Create follow task
task = client.tasks.create(
    FollowTaskRequest(
        config=FollowConfig(
            mode=FollowMode.QUERY,
            searchQuery="crypto enthusiast",
            searchProduct="Top",
            totalFollowTarget=100
        ),
        tags=["crypto-bot"]
    )
)

# List tasks
tasks = client.tasks.list(status="STARTED")

# Pause/Resume task
client.tasks.pause(task.id)
client.tasks.resume(task.id)

🌐 Proxy Management

# Add proxy
proxy = client.proxies.create({
    "ip": "192.168.1.100",
    "port": 8080,
    "type": "HTTP",
    "username": "user",
    "password": "pass"
})

# Bulk import proxies
result = client.proxies.bulk_import([
    "user:pass@192.168.1.1:8080",
    "192.168.1.2:8080"
])

# List proxies
proxies = client.proxies.list(status="WORKING")

# Assign proxy to account
client.accounts.update_proxy(
    account_id=1,
    proxy_id=proxy.id
)

# Auto-assign proxy
client.accounts.update_proxy(
    account_id=1,
    auto_assign=True
)

💬 Direct Messages

# Get inbox
inbox = client.messages.get_inbox(username="mybot")

# Search users for DM
users = client.messages.search_users(
    username="mybot",
    query="john"
)

# Send message
result = client.messages.send_message(
    username="mybot",
    recipient_id=123456789,
    text="Hello! How are you?"
)

# Send message with image
result = client.messages.send_message(
    username="mybot",
    recipient_id=123456789,
    text="Check this out!",
    media="base64_encoded_image_data"
)

# Get conversation
conversation = client.messages.get_conversation_with_username(
    username="mybot",
    target_username="johndoe"
)

🏘️ Communities

# Get community info
community = client.communities.get_info(
    account_id=1,
    community_id="1234567890"
)

# Join community
client.communities.join(
    account_id=1,
    community_id="1234567890"
)

# Post to community
client.communities.post_tweet(
    account_id=1,
    community_id="1234567890",
    text="Hello community!"
)

# Leave community
client.communities.leave(
    account_id=1,
    community_id="1234567890"
)

📊 Data Fetching

# Get user tweets
tweets = client.data_fetcher.get_user_tweets(
    user_id=123456789,
    limit=50
)

# Search tweets by hashtag
results = client.data_fetcher.search_by_hashtag(
    tag="crypto",
    limit=100,
    product="Latest"
)

# Search tweets by text
results = client.data_fetcher.search_by_text(
    query="artificial intelligence",
    limit=50
)

# Get tweet info
tweet = client.data_fetcher.get_tweet(tweet_id=1234567890)

# Validate tweet
validation = client.data_fetcher.validate_tweet(tweet_id=1234567890)
print(f"Valid: {validation['is_valid']}")

🤖 AI Integration

# Send prompt to AI
response = client.ai.prompt(
    prompt="Write a creative tweet about artificial intelligence"
)
print(response["response"])

⚙️ Configuration

# Get AI configuration
ai_config = client.configuration.get_ai_config()

# Update AI configuration
client.configuration.update_ai_config({
    "endpoint": "https://api.openai.com/v1/chat/completions",
    "api_key": "sk-...",
    "model": "gpt-4",
    "enabled": True
})

# Get proxy configuration
proxy_config = client.configuration.get_proxy_config()

# Update account configuration
client.configuration.update_account_config({
    "auto_check_account": True,
    "auto_replace_proxy": True
})

📈 System Statistics

# Get system stats
stats = client.system.get_stats()

print(f"Total accounts: {stats.account.total}")
print(f"Working accounts: {stats.account.working}")
print(f"Working proxies: {stats.proxy.working}")
print(f"System healthy: {stats.system.healthy}")

Error Handling

from botwitter import (
    BotWitterClient,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    BotWitterError
)

client = BotWitterClient(base_url="http://localhost:8080/api/v1")

try:
    account = client.accounts.get(account_id=999)
except NotFoundError as e:
    print(f"Account not found: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
except BotWitterError as e:
    print(f"API error: {e}")

Advanced Usage

Context Manager

with BotWitterClient(base_url="http://localhost:8080/api/v1") as client:
    accounts = client.accounts.list()
    # Connection automatically closed

Custom Timeout

client = BotWitterClient(
    base_url="http://localhost:8080/api/v1",
    timeout=60  # 60 seconds
)

Disable SSL Verification

client = BotWitterClient(
    base_url="http://localhost:8080/api/v1",
    verify_ssl=False
)

Models

The library provides Pydantic models for type safety:

from botwitter.models import (
    Account,
    AccountRequest,
    Proxy,
    Task,
    FarmingConfig,
    FarmingSession,
    RSSPostingConfig,
    # ... and many more
)

# Use models for type hints
def create_account(client: BotWitterClient, data: AccountRequest) -> Account:
    return client.accounts.create(data)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development

# Clone repository
git clone https://github.com/botwitter/python-api.git
cd python-api

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking
mypy botwitter

# Format code
black botwitter

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Get BotWitter

You can purchase BotWitter and get API access at https://botwitter.com

Disclaimer

This library is for educational and automation purposes. Make sure to comply with Twitter's Terms of Service and API usage guidelines when using this library.