X (Twitter) tool

The X tool lets an agent run an X (Twitter) account through the X API v2 - post tweets, replies, quotes and image posts, delete tweets, like and repost, follow and unfollow, read timelines, mentions, followers and bookmarks, search the last 7 days, and send direct messages. One tool configuration maps to one X account. The agent picks one of 21 actions per call. Set it up once with five keys from the X developer console, then assign it to a bot.

Mental model

All five credential fields are plain static strings from a single page of the X developer console - the app's Keys and Tokens page. Nothing expires, there's no OAuth browser sign-in, and there are no refresh tokens to manage. Two subtleties are worth knowing up front, and both are covered below: the Access Token has to be generated after you set the app's permissions (step 3), and the Bearer Token powers only the search action. Everything else runs on the API Key and Access Token pairs.

What it can do

The agent chooses one action per call. The 21 actions, by area:

• Account - get_me, get_user.
• Reads - get_tweet, list_my_tweets, list_user_tweets, list_mentions, list_followers, list_following, list_liked, list_bookmarks.
• Search - search_recent (X operators like from:, to:, #tag, -is:retweet; last 7 days only; needs the Bearer Token).
• Publish - post_tweet (one action covers plain tweets, replies via reply_to_tweet_id, quotes via quote_tweet_id, and up to 4 images via image_urls - public https URLs are fetched and uploaded automatically), delete_tweet.
• Engage - like, unlike, repost, unrepost, follow_user, unfollow_user.
• Direct messages - send_dm, read_dm_conversation (the message history with one user).

User-targeting parameters accept an @handle, a bare handle, or a numeric id; handles are resolved and cached for 24 hours (a lookup costs credits). Lists return 10 by default and up to 100 (X enforces minimums of 5, or 10 for search).

Before you start

You need:

• The X account the agent will act as.
• A developer account at console.x.com, signed in with that account.
• A small amount of prepaid credit loaded (see the cost note above).

Connect an account

1. Create an app. Sign in at console.x.com with the account the agent will post as, and create an app.
2. Load credits. Add prepaid credit to the developer account - pay-per-use won't work without it, and a small top-up covers a lot of use.
3. Set the app's permissions first. In the app's user-authentication / permission settings, choose Read and write (or Read and write and Direct Messages if the agent will DM). Do this before you generate the Access Token - see the callout below.
4. Copy the five keys. On the app's Keys and Tokens page, copy the API Key and API Key Secret, the Access Token and Access Token Secret (regenerated after the permission change in step 3), and the Bearer Token.
5. Paste all five into the Hania form and save. There's no browser authorization step and nothing expires.

Which keys do I copy?

The Keys and Tokens page shows several credential sets. You need exactly these five, in three groups:

• API Key set - the API Key (Consumer Key) and API Key Secret (Consumer Secret).
• Access Token set - the Access Token and Access Token Secret for the account (generated after the permission change).
• Bearer Token - the app-only token, used only for search.

Ignore the OAuth 2.0 section. The console may also show an OAuth 2.0 Client ID and Secret and OAuth 2.0 access/refresh tokens - Hania does not use any of those. Only the API Key set, the Access Token set, and the Bearer Token matter.

Field reference

The tool configuration has five fields. The first four are required; the Bearer Token is optional (leave it blank to disable search).

• API Key (Consumer Key) (required) - from the app's Keys and Tokens page.
• API Key Secret (Consumer Secret) (required, secret) - shown alongside the API Key. Stored encrypted and never returned.
• Access Token (required) - the OAuth 1.0a Access Token for the account. Generate it after setting the app's permissions to "Read and write" (or "Read and write and Direct Messages"); a token made under read-only permissions can't post.
• Access Token Secret (required, secret) - shown alongside the Access Token. Stored encrypted and never returned.
• Bearer Token (optional, secret) - the app-only token from the same page. Used only for the search_recent action, because X's search endpoints reject the OAuth 1.0a keys. Leave blank to disable search.

What the agent can and cannot do

Beyond the actions above, a few behaviors are worth knowing:

• Images must be real images. X accepts the upload of a tiny placeholder image but then rejects the post with a misleading "Your media IDs are invalid". Attach normal-sized images - the agent's own generated images (served from /media/… URLs) work fine.
• 280 characters is the tweet limit for standard accounts; the blueprint has the agent count first.
• Search is last-7-days only and needs the Bearer Token; without it, only search_recent is unavailable.
• Every call costs credits, so the agent is instructed to be purposeful and avoid re-fetching. Repeated reads are de-duplicated for 24 hours.
• Not in v1 - no scheduled tweets, no "post a whole thread" action (the agent builds a thread by chaining replies), and no video upload.

On trust: direct messages can't be unsent and deleted tweets can't be recovered, so the X Social Manager blueprint requires the agent to confirm with you before send_dm and delete_tweet. There is also no bulk-engagement capability - actions run one at a time by design, so an agent can't mass-follow or mass-like.

Troubleshooting

• Post fails with "oauth1 app permissions" - step 3 was skipped, or the Access Token predates the permission change. Set the app to Read and write and regenerate the Access Token pair.
• Search fails naming the Bearer Token - the Bearer Token field is empty. Search is the one action that needs it; paste it in to enable search.
• DM fails with 403 "You do not have permission to DM one or more participants" - the recipient's privacy settings don't accept DMs from this account. They need to follow the account, or turn on "Allow message requests from everyone". This is not a credential problem - the same error appears regardless of auth.
• 401 on everything - a key was mispasted. The Access Token normally looks like <digits>-<letters>; re-copy the five values carefully.
• 429 Too Many Requests - X rate-limited the request; the agent backs off and retries.
• "x rejected the request: Not Found Error: Could not find user…" - a validation error the agent self-corrects, so it may flash through a trace before the call succeeds. Error text comes verbatim from X.

Safety in autonomous runs

Like any tool, the X tool carries a safety classification (read-only / destructive / sends-data-externally) that governs scheduled or triggered (autonomous) runs. Because deleting a tweet is irreversible and a DM can't be unsent, a new configuration is created with Read-only switched off, Destructive switched on, and Sends data externally on - so destructive actions are gated in autonomous runs unless the bot's "Allow destructive actions in autonomous runs" is enabled. Keep those defaults, and let the blueprint's confirmation prompts do their job on deletes and DMs. Interactive chat is never gated by these flags.

Security

The API Key Secret, Access Token Secret and Bearer Token are stored AES-encrypted at rest and are never returned by the API - the console shows only whether each is set. Editing a configuration without retyping a secret preserves the stored one, so you must retype it to replace it. Since nothing about these credentials expires, the way to revoke access is to regenerate or delete the keys in the X developer console.

Blueprint

The fastest way to a working account agent is the X Social Manager blueprint (content-publishing category) - a pre-built agent wired for posting and account management, including the character-count and confirm-before-delete/DM habits mentioned above. Pick it from the blueprint gallery when creating a bot; the only thing you supply is the five credential strings from this guide.