X: what this connector can do

Member·6 minutes to read

What this page is for

docs/connectors/x.md is the setup guide for whoever runs your organisation's Botseon deployment — creating the vendor application and entering its credentials. This page is the other half: what X actually lets a bot do once it is connected to your account, what it asks you for along the way, its limits, and how to take the connection away again, in Botseon and at X.

Read posts, timelines, and mentions. Posting arrives later.

Finding it

X is one of the built-in plugins in Connect apps (Cmd/Ctrl+Shift+M), on every Botseon deployment. Browse the Research category, or type its name in the search box, and press Add, then Authenticate on its card to sign in to X. If your team admin has blocked it, its card says Blocked by your team admin instead of offering Add, and it is not offered when you type @ in a message. Signing in needs the X app whoever runs your deployment sets up; until then there is nothing to sign in with.

What a bot can do with it

Read — X tells a bot things, nothing changes

Tool	What it does
`x.search_posts`	Search recent public posts.
`x.get_post`	Read one post by id.
`x.get_user_timeline`	Read a user’s recent posts.
`x.list_mentions`	List recent mentions of the account.
`x.list_bookmarks`	List the posts the member has bookmarked.
`x.list_liked_posts`	List the posts the member has liked.
`x.home_timeline`	Read the member’s home timeline, newest first.
`x.list_direct_messages`	Read the member’s recent direct messages.

Write

This connector has no write tools yet. A bot can only read through it.

Tag Botseon on X to start a task

When this deployment runs its own X account, connecting X also links your X account to you, and Settings → X tagging shows which handle is linked. From then on, mention that account in a post or in a reply on X and your main bot gets a task with that post — and the post it replies to, and any post it quotes. The account replies once on X to confirm. Some posts start nothing: one with a video or a GIF, one that also tags another assistant, one X flags as sensitive, or any post once you have no usage left. Tagging is not offered to members in the EU, the EEA, the UK or Australia. If you have no main bot yet, the reply asks you to set one; Unlink in the same Settings row stops it. It works the same on a deployment run at home with no public web address: the deployment reads its account's mentions from X itself, so your tag still reaches your bot. If you run Botseon yourself, the only thing to do is give it your X account's four keys (your operator's guide, docs/connectors/x.md section 6, says where they come from): Botseon finds the account, points X at itself when it starts, and Settings → X tagging appears a few seconds later.

The permissions it asks for, in plain words

Every call a bot makes through this connector is tagged with what kind of thing it is. Only the tags below ever apply here — a tag this connector's tools never carry is not listed, because it can never ask you for it.

read — Looks something up. Nothing changes, and nothing is sent anywhere. A bot never has to ask first for this.

Limits

Read posts, timelines, and mentions. Posting arrives later. Nothing outside that list is possible through this connector, however a bot is asked to use it.

X is also only ever as wide as the scopes your organisation's connected app actually requests — the exact scopes are on the operator's own setup page, docs/connectors/x.md, because narrowing or widening them is a decision for whoever runs your deployment, not for this page.

Disconnecting

In Botseon

Open Plugins from the sidebar, press this connector's card to open its detail page, and under Accounts press the ✕ next to the account (its label is "Remove account" and the name of the account), then Revoke and remove to confirm — or Uninstall to remove the plugin and every account connected to it at once. Either one revokes the stored connection immediately: nothing more is read or changed through it from that moment on. Install a plugin walks through the same screen step by step.

At X

Removing the account in Botseon also asks X to revoke the token, when this deployment's connector is configured with a revoke URL. Confirm the grant is actually gone by opening X's own account settings — the connected-apps, security or authorised-apps page covers it — and removing Botseon there too if it still shows up. That is also where you can revoke access without going through Botseon at all, which is worth knowing if you ever lose access to your Botseon account.

What Botseon keeps, and how your data is used

Whatever a bot reads or writes through this connector becomes part of your conversations and the record of that run — the same records, and the same retention schedule, as everything else a bot works on. Botseon is the processor for that content; your organisation decides what it may read and remember, and can delete it sooner than the schedule would on its own.

Your data is sent to a model provider only to produce the bot's answer, and for nothing else — it is not used to train any model. The Privacy Policy's Models and How long we keep it sections have the full detail, including exactly how long each kind of record is kept for.