X (Twitter)

Post, reply, quote, and interact with X (Twitter) using the X API v2

X Tool enables agents to post content, reply to posts, create quote posts, manage polls, upload media, and interact with X (formerly Twitter) using the official X API v2.

from praisonaiagents import Agent
from praisonai_tools import XTool

agent = Agent(name="SocialAgent", tools=[XTool()])
agent.start('Post on X: "Just deployed our latest feature!"')

The user drafts a post; the agent publishes or reads timelines through the X tool.

Quick Start

Get started with X Tool in three simple steps.

1. Simple Post

   from praisonai_tools import post_to_x
   
   # Simple post
   result = post_to_x("Shipping a new feature today! 🚀")
   print(f"Posted: {result['url']}")

2. Function Helper

   from praisonai_tools import post_to_x, reply_to_x, quote_x_post
   
   # Post with media
   post_result = post_to_x("Check out this image!", media_paths=["image.jpg"])
   post_id = post_result['data']['id']
   
   # Reply to post
   reply_to_x(post_id, "Great update!")
   
   # Quote tweet
   quote_x_post(post_id, "This is exactly what we needed!")

3. Agent Usage

   from praisonaiagents import Agent
   from praisonai_tools import post_to_x
   
   agent = Agent(
       name="social_poster",
       llm="gpt-4o-mini",
       instructions="When asked to post on X, call post_to_x and return the URL.",
       tools=[post_to_x],
   )
   
   agent.start('Post on X: "Just deployed our latest feature!"')

Installation

Install the required packages to get started with X Tool.

pip install praisonai-tools requests-oauthlib

How It Works

X Tool supports three authentication modes for different use cases.

OAuth 1.0a Setup (Recommended for Posting)

1. Create X Developer Account

   Visit developer.x.com and create a developer account.

2. Create App and Get Keys
   1. Create a new app in the X Developer Portal
   2. Generate API Key and API Key Secret
   3. Enable OAuth 1.0a with read/write permissions
   4. Generate Access Token and Access Token Secret
3. Configure Environment Variables

   X_API_KEY=
   X_API_SECRET=
   X_ACCESS_TOKEN=
   X_ACCESS_SECRET=

   export X_API_KEY=
   export X_API_SECRET=
   export X_ACCESS_TOKEN=
   export X_ACCESS_SECRET=

4. Test Authentication

   from praisonai_tools import XTool
   
   # Test connection
   x_tool = XTool()
   user_info = x_tool.get_user("your_username")
   print(f"Connected as: {user_info['data']['name']}")

Configuration Options

Configure X Tool with your API credentials and preferences.

XTool Class

from praisonai_tools import XTool

x_tool = XTool(
    api_key="your_api_key",               # Optional if env var set
    api_key_secret="your_api_secret",     # Optional if env var set
    access_token="your_access_token",     # Optional if env var set
    access_token_secret="your_access_secret"  # Optional if env var set
)

XTool.post() Parameters

Function Helpers

Common Patterns

from praisonai_tools import post_to_x

# Basic text post
result = post_to_x("Hello X! 👋")
print(f"Post URL: {result['url']}")

from praisonai_tools import post_to_x

# Post with image
result = post_to_x(
    text="Check out our new feature! 🚀",
    media_paths=["screenshot.png"]
)
print(f"Posted with media: {result['url']}")

from praisonai_tools import post_to_x, reply_to_x

# Create thread
main_post = post_to_x("🧵 Thread about AI agents: 1/3")

reply_1 = reply_to_x(
    main_post['data']['id'], 
    "AI agents can automate social media posting... 2/3"
)

reply_2 = reply_to_x(
    reply_1['data']['id'],
    "The future is autonomous content creation! 3/3"
)

from praisonai_tools import post_to_x

# Create poll
result = post_to_x(
    text="What's your favorite AI model? 🤖",
    poll_options=["GPT-4", "Claude", "Gemini", "Llama"],
    poll_duration_minutes=1440  # 24 hours
)

Agent Integration Patterns

from praisonaiagents import Agent
from praisonai_tools import post_to_x, reply_to_x, search_x

agent = Agent(
    name="social_manager",
    llm="gpt-4o",
    instructions="""You manage social media presence on X. 
    - Post engaging content
    - Reply to mentions
    - Share updates about our products""",
    tools=[post_to_x, reply_to_x, search_x]
)

# Schedule posts
agent.start("Post about our new AI feature launch")

from praisonaiagents import Agent
from praisonai_tools import search_x, reply_to_x

support_agent = Agent(
    name="support_bot",
    instructions="""Monitor mentions and provide helpful responses.
    Be professional and solution-oriented.""",
    tools=[search_x, reply_to_x]
)

# Monitor and respond
support_agent.start("Check for mentions of our brand and respond helpfully")

from praisonaiagents import Agent
from praisonai_tools import search_x, quote_x_post, post_to_x

curator = Agent(
    name="content_curator",
    instructions="""Find and share interesting tech content.
    Add thoughtful commentary when quoting posts.""",
    tools=[search_x, quote_x_post, post_to_x]
)

curator.start("Find and share interesting AI news with commentary")

Authentication Flow Diagram

Best Practices

# ✅ Use OAuth 1.0a for posting  
x_tool = XTool(
    api_key="key",
    api_key_secret="secret", 
    access_token="token",
    access_token_secret="token_secret"
)

import time
from praisonai_tools import post_to_x

def post_with_retry(text, max_retries=3):
    for attempt in range(max_retries):
        try:
            return post_to_x(text)
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

from praisonai_tools import post_to_x, reply_to_x

def safe_post(text, max_chunk=270):
    if len(text) <= 280:
        return post_to_x(text)
    # Split into thread; each chunk leaves room for " N/M" suffix
    chunks = [text[i:i+max_chunk] for i in range(0, len(text), max_chunk)]
    total = len(chunks)
    first = post_to_x(f"{chunks[0]} 1/{total}")
    prev_id = first['data']['id']
    for i, chunk in enumerate(chunks[1:], start=2):
        reply = reply_to_x(prev_id, f"{chunk} {i}/{total}")
        prev_id = reply['data']['id']
    return first

# .env file
X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token
X_ACCESS_SECRET=your_access_secret

Premium Features

Quote Posts:

# Available on all plans via X API v2
quote_x_post("1234567890", "Adding my thoughts on this important topic...")

Extended Posts:

# Premium accounts can post up to 25,000 characters
long_post = "A" * 5000  # Long content
post_to_x(long_post)  # Works with Premium

Related