# twitter

> This skill governs the mechanics of interacting with Twitter. It ensures BAiSED uses the correct API endpoints and authentication methods to maintain account health.

- Author: Clawd Bot
- Repository: BAiSEDagent/openclaw-skills
- Version: 20260208142402
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/BAiSEDagent/openclaw-skills
- Web: https://mule.run/skillshub/@@BAiSEDagent/openclaw-skills~twitter:20260208142402

---

# Twitter

## Description
Operational guidelines for interacting with the Twitter/X API.

## Instructions


# Twitter/X API Operations

This skill governs the mechanics of interacting with Twitter. It ensures BAiSED uses the correct API endpoints and authentication methods to maintain account health.

## Guidelines
1.  **Correct Endpoints:** Use `x_reply_to_tweet` for replies. NEVER use `post_tweet_x` for a reply, as it breaks the thread context.
2.  **Authentication:** Ensure `X OAuth` headers are active. If a 401 error occurs, trigger a token refresh flow immediately.
3.  **Rate Limits:** Be mindful of API limits. Do not poll `get_home_timeline` more than once every 15 minutes.
4.  **User-Agent:** Always include the `User-Agent` header identifying as "BAiSED-Agent/1.0" to prevent flagging.

## Examples

**User/Trigger:** "Reply to @jessepollak's latest tweet."
**Agent Action:** 1. `get_user_timeline` (find tweet ID). 2. `x_reply_to_tweet` (send content).
**Good Output:** "Executing `x_reply_to_tweet(tweet_id='12345', text='...')`."
**Bad Output:** "Posting new tweet: '@jessepollak Great point!'" (This creates a new orphan tweet, not a reply).

## Resources
* [Twitter Tools List](instructions/tool-definitions.md): Definitions of all 16 API functions.
---

# Twitter API Setup

This guide covers setting up authentication for the Twitter API v2, understanding API tiers, rate limits, and navigating the Developer Portal.

## Creating a Twitter Developer Account

1. **Sign up for a Developer Account**
   - Visit [developer.twitter.com](https://developer.twitter.com)
   - Click "Sign up" or log in with your existing Twitter account
   - Complete the developer application form
   - Describe your intended use case for the API
  - Accept the Developer Agreement and Policy

2. **Email Verification**
    - Check your email for a verification link from Twitter
    - Click the link to verify your account
    - Your developer account will be reviewed (usually instant for basic access)

3# Understanding API Tiers

Twitter offers three main API access tiers:

### Free
- **Cost**: $0 / month
- **Conections** 1 Project, 1 App
- **Capabilities** Write-only access (with limited lookup)
- **Rules**:
   - 5,000 Tweets / month (posting and removal)
   - Ibm access to get me and get recent search (limited)
    - Decahose limited sample

### Basic
- **Cost**: $100 / month
- **Conections** 2 Projects, 2 Apps per Project
- **Capabilities**: Read and Write access
- **Rules**:
   - 10,000 Twitts / month (posting
   - 50,000 Tweets / month (reading data)
   - 1,000 Tweets / day (posting limit)

### Pro
- **Cost**: $5,000 / month
- **Conections** Up to 10 Apps
- **Capabilities**: High-volume read and write
- **Rules**:
    - 100,000 Tweets / month (posting)
    - 1,000,000 Tweets / month (reading data)
   - Access to Full Archive Search and filtered stream

## OAuth 2.0 Setup

Twitter API v2 requires OAuth 2.0 for most programmatic actions.

1. **Create a Project and App**
   - In the Developer Portal, create a new Project and associate a New App with it.

2. **User Authentication Settings**
   - In your App settings, set "User authentication settings"
   - Enable OAuth 2.0
   - Set App type to "Web App" or "Native App"
   - Provide a Callback URL (e.g., https://twin.so/auth/callback)
   - Set appropriate permissions (Read and Write and Direct Message)

3. **Client ID and Secret**
   - Generate your Client ID and Client Secret
   - Store these securely

## Rate Limits

Twitter enforces rate limits based on 15-minute windows.

- **Get Recent Search*** 60 requests / 15 minutes
- **Post Tweet**: 200 requests / 15 minutes
- **Get User Tweets**: 500 requests / 15 minutes

Always check the x-rate-limit-remaining response headers to avoid being banned temporarily.
---

# Posting to Twitter

This guide covers how to create tweets, replies, retweets, quote tweets, and multi-part threads using the Twitter API v2.

## Creating a Tweet

To post a basic tweet, you need to send a POST request to the endpoint:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "Hello World!"
---

### Media Attachments

If you want to include media, you must first upload it via the media upload API endpoint and then reference the media_id in your tweet request.

First, upload your media:

---
endpoint: `POST https://upload.twitter.com/1.1/media/upload.json`
headers:
  `Content-Type`: multipart/form-data
body:
  `media`: [binary file data]
---

The response will include a `media_id_string` field. Use this ID when creating your tweet:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "Check out this image!"
  `media`: {
    `media_ids`: ["1234567890"]
  }
---

You can attach up to 4 images, 1 GIF, or 1 video per tweet. For videos longer than 30 seconds, use chunked upload.

## Creating a Reply

To reply to an existing tweet, include the `reply` parameter with the tweet ID you want to reply to:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "This is a reply"
  `reply`: {
    `in_reply_to_tweet_id`: "1234567890"
  }
---

The reply will appear in the conversation thread beneath the original tweet.

## Creating a Retweet

To retweet a tweet, use the retweets endpoint:

---
endpoint: `POST /https://api.twitter.com/2/users/:id/retweets`
path parameters:
  `id`: Your user ID
body:
  `tweet_id`: "1234567890"
---

This will retweet the specified tweet to your timeline.

### Removing a Retweet

To undo a retweet:

---
endpoint: `DELETE /https://api.twitter.com/2/users/:id/retweets/:source_tweet_id`
path parameters:
  `id`: Your user ID
  `source_tweet_id`: The ID of the tweet you retweeted
---

## Creating a Quote Tweet

A quote tweet is a tweet that includes another tweet embedded within it. To create a quote tweet, include the URL or ID of the tweet you want to quote:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "Great point! Adding my thoughts here."
  `quote_tweet_id`: "1234567890"
---

You can also include media attachments in quote tweets following the same process as regular tweets.

## Creating a Thread

To create a multi-tweet thread, post tweets sequentially, with each subsequent tweet replying to the previous one.

First tweet:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "This is the first tweet in my thread. 1/3"
---

Save the `id` from the response, then post the second tweet:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "This is the second tweet in my thread. 2/3"
  `reply`: {
    `in_reply_to_tweet_id`: "[ID from first tweet]"
  }
---

Continue this pattern for each subsequent tweet in the thread:

---
endpoint: `POST /https://api.twitter.com/2/tweets`
body:
  `text`: "This is the final tweet in my thread. 3/3"
  `reply`: {
    `in_reply_to_tweet_id`: "[ID from second tweet]"
  }
---

### Thread Best Practices

- Number your tweets (e.g., 1/5, 2/5) so readers know the thread length
- Post tweets in quick succession to avoid others replying between thread tweets
- Keep each tweet focused and readable on its own
- Use the first tweet as a summary or hook to encourage reading the full thread

## Error Handling

If you receive a 403 Forbidden error, it might be due to:
- Duplicate content (posting the exact same text twice)
- Rate limiting
- Invalid ID to reply to

### Common Error Codes

- `400 Bad Request`: Invalid request format or missing required fields
- `401 Unauthorized`: Invalid or expired authentication credentials
- `403 Forbidden`: Request understood but refused (see reasons above)
- `404 Not Found`: The tweet ID referenced does not exist
- `429 Too Many Requests`: Rate limit exceeded, wait before retrying

### Rate Limits

Twitter API v2 has the following rate limits for posting:
- 300 tweets per 3-hour window
- 50 tweets per 24 hours for retweets
- Media uploads have separate rate limits based on file size

If you hit a rate limit, the response will include a `x-rate-limit-reset` header indicating when you can resume posting.
---

# Reading from Twitter

This guide covers how to retrieve tweets and user information using the Twitter API v2.

## Prerqequisites

- Ensure you have the appropriate API tier (Free has very limited read capabilities).
- You need an access token with `tweet.read` and user.read` scopes.


## Fetching User Tweets

To get recent tweets from a specific user, you need their `User ID`.

endpoint: `GET /tweets/users/:uler__id/tweets`


### Parameters
- `max_results`: Number of tweets to return (10-100)
- `tweet.fields: Additional data (e.g., created_at, public_metrics)
/ `pagination_token`: Used for fetching the next set of results

## Searching Recent Tweets

Search allows you to find tweets from the last 7 days based on a query.

endpoint: `GET /tweets/search/recent`


### Example Queries
- `baised -is_retweet`: Search for tweets containing "baised" that are not retweets
- `from:jessepollck TEST`: Search for tweets from Jesse Pollack containing "TEST"

## User Lookup

You can look up a user information by their handle (username).

endpoint: `GET /users/by_username/:username`

returns:
- **ID**: The numeric ID needed for fetching tweets
- **Name** The display name
- **Public Metrics** Follower count, fillowing count, etc.

## Reading Home V[emine (Subject to tier)

For Basic and Pro tiers, you can read the authenticated user's timeline.

endpoint: `GET /tweets/users/:me_id/timeline/reverse_cronological`
---

# Twitter Engagement

This gumdH covers how to interact with tweets and users through likes, follows, mentions, and direct messages.

## Liking a Tweet

Liking a tweet is a POST request that requires the authenticated user ID and the ID of the tweet you want to like.

endpoint: `POST /users/:id/likes`
body:
  `tweet_id`: "1234567890"

## Following Users (Basic Tier+)

Following users allows your account to build a network and see more relevant content. **Note: This feature requires at least the Basic tier ($100/mo).**

endpoint: `POST /users/:source_user_id/following`
body:
  `target_user_id`: "987654321"

## Checking Mentions

Mentions are tweets that include your @username. Checking mentions is critical for engagement.

endpoint: `GET /users/:id/mentions`

### Filtering Mentions
Use `tweet.fields` to get additional context about who mentioned you and when.

## Direct Messages (DMs)

DMs allow for private conversations. They require specific OAuth scopes (bdm.read`, `dm.write`).


### Sending a DM
To send a DM, you need the recipient's user ID.

endpoint: `POST /dm_conversations/with/:participant_id/messages`
body:
  `text`: "Hello! Thanks for the follow."

### Receiving DMs
You can list recent dm events to see incoming messages.

endpoint: `GET /dm_events`

## Engagement Strategy

- Ald respond - Always try to reply to mentions to increase algorithmic reach.
- Like relevant content - Liking tweets in your niche helps gain visibility.
- **Do not spam** - Excessive follow/unfollow or liking can lead to account suspension.
---

# Twitter Best Practices

This guide covers best practices for using the Twitter API effectively and maintaining a positive presence on the platform.


## Voice and Tone for Automated Accounts


### Transparency

- **Disclose automation**: Make it clear in your bio if the account is automated or bot-assisted
- **Use appropriate labeling**: Consider adding  or "Automated" to your display name
- **Be authentic**: Even automated content should reflect genuine value and purpose


### Tone Guidelines


---
`do`:
  - Keep messages conversational and human-friendly
  - Use personality that matches your brand
  - Respond thoughtfully when engaging
  - Vary your message structure
`donts`:
  - Sound robotic or repetitive
  - Use excessive hashtags (#spam #like #this)
  - Deploy generic responses to everything
  - Ignore context in conversations
---


### Content Quality

- **Add value**: Every tweet should provide information, entertainment, or utility
- **Avoid pure promotional content**: Follow the 80/20 rule (80% value, 20% promotion)
- **Respect the conversation**: Don't hijack threads or force your content into unrelated discussions


## Optimal Timing


### Best Times to Post

General guidelines based on engagement data:

- **Weekdays**: 8-10 AM and 6-9 PM (in your audience's timezone)
- **Wednesday and Thursday**: Typically highest engagement days
- **Lunch hours**: 12-1 PM often sees good engagement
- **Weekends**: Saturday mornings (9-11 AM) for casual content


### Frequency Recommendations

---
`personal_or_small_accounts`:
  - 1-5 tweets per day
  - Space out by 2-4 hours minimum
`brand_or_business_accounts`:
  - 3-10 tweets per day
  - Mix of original content and engagement`section_news_accounts`:
  - 10-50 tweets per day
  - Ensure content is timely and relevant
---



### Timing Strategy

- **Test and measure**: Use Twitter Analytics to find your audience's active hours
- **Consistency is key**: Post regularly rather than in bursts

## Content Performance

- **Visuals**: Tweets with images or videos get receive significantly more engagement.
- **Questions**: Asking your audience questions encourages replies.
- **Threads**: Deep dives into topics via threads are highly resharable.
- **Timely Topics**: Engaging with trending but relevant topics can boost visibility.

human-in-the-loop Best Practice:
 For high-stakes accounts, have a human review automated drafts before publishing to maintain quality control.