package
X (Twitter) adapter for Chat SDK: reply to mentions, send direct messages, and post from your bot account with the X API v2, plus encrypted XChat conversations from the @chat-adapter/x/chat subpath
npm install @chat-adapter/xGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
vercel-release-bot
infra+release@vercel.com
X (Twitter) adapter for Chat SDK, using the X API v2 and the X Activity API. Reply to public mentions, hold DM conversations, post from the bot account, and like posts.
Documentation: chat-sdk.dev/adapters/official/x · Guides: vercel.com/kb/chat-sdk
pnpm add @chat-adapter/xTo scaffold a new X bot with this adapter preselected:
npx create-chat-sdk@latest my-bot --adapter x memoryVisit the adapters directory to see other available official and vendor-official adapters.
import { Chat } from "chat";
import { createXAdapter } from "@chat-adapter/x";
const bot = new Chat({
userName: "mybot",
adapters: {
x: createXAdapter(),
},
});
bot.onNewMention(async (thread, message) => {
await thread.post(`Hi @${message.author.userName}!`);
});
bot.onDirectMessage(async (thread, message) => {
await thread.post("Hello from X!");
});When using createXAdapter() without arguments, credentials are auto-detected from environment variables.
X_CONSUMER_SECRETtweet.read, tweet.write, users.read, dm.read, dm.write, like.write, and offline.accessX_USER_ACCESS_TOKEN, or store X_CLIENT_ID plus X_REFRESH_TOKEN to let the adapter manage token refreshX delivers events through the X Activity API. Set this up once in the X developer console, which handles the auth for you:
https://your-domain.com/api/webhooks/x). It must be public HTTPS without a port. X immediately sends a CRC challenge, which the adapter answers automaticallypost.mention.create, dm.received, and dm.sent (private events, so the bot user must have authorized your app first)Subscription and webhook management is one-time setup, not adapter runtime. If you script it instead of using the console, the Activity API endpoints are auth-picky and operation-specific and do not fully match the published spec (creating a private-event subscription needed OAuth 1.0a user context in testing, while list and delete used the app-only bearer token), so the console is the simpler path.
X_CONSUMER_SECRET=... # App API key secret, used for webhook CRC and signature verification
# Auth option A: static access token
X_USER_ACCESS_TOKEN=... # OAuth 2.0 user-context access token for outbound calls
# Auth option B: managed OAuth refresh (recommended for long-running bots)
X_CLIENT_ID=... # OAuth 2.0 client ID
X_REFRESH_TOKEN=... # OAuth 2.0 refresh token (requires the offline.access scope)
X_CLIENT_SECRET=... # Optional, only for confidential clients
X_ENCRYPTION_KEY=... # Optional, base64 32-byte key to encrypt persisted tokens
X_USER_ID=... # Bot account user ID. Optional if omitted it is fetched from /2/users/me; the adapter requires a resolvable bot id and fails init otherwise
X_USERNAME=... # Optional, bot @handle for mention detection (fetched when omitted)
X_API_BASE_URL=... # Optional, override the X API base URLX OAuth 2.0 user tokens are short-lived (about two hours). With X_CLIENT_ID and X_REFRESH_TOKEN set, the adapter refreshes the access token before expiry and persists the rotated refresh token in your state adapter, so the bot survives restarts. Set X_ENCRYPTION_KEY to store those tokens AES-256-GCM encrypted.
Alternatively, pass a token provider and plug in your own refresh logic:
import { createXAdapter } from "@chat-adapter/x";
const adapter = createXAdapter({
userAccessToken: async () => refreshTokenFromMyStore(),
});X uses two webhook mechanisms, both handled by the adapter:
crc_token that the adapter answers with an HMAC-SHA256 response keyed by your consumer secret. X re-validates hourlyx-twitter-webhooks-signature header, verified against the raw request body// Next.js App Router example
import { bot } from "@/lib/bot";
export async function GET(request: Request) {
return bot.webhooks.x(request);
}
export async function POST(request: Request) {
return bot.webhooks.x(request);
}| Feature | Supported |
|---|---|
| Post message | Yes (mention replies and DMs) |
| Top-level posts | Yes (channel.post on x:public) |
| Edit message | Posts only (X edit eligibility rules apply) |
| Delete message | Posts and own DM events |
| Streaming | Buffered (accumulates then posts once) |
| Typing indicator | No |
| Feature | Supported |
|---|---|
| Card format | Plain text fallback |
| Buttons | No (link buttons render as text) |
| Tables | ASCII |
| Modals | No |
| Image uploads | Yes (png, jpeg, webp; up to 4 per post; also DMs) |
Attach images by passing files (or attachments) on the message; the adapter uploads each through X's chunked media endpoints (initialize then append then finalize) and attaches the returned media_ids to the post or DM. A post can carry media with or without text.
await thread.post({
markdown: "France lead the title race",
files: [{ data: pngBuffer, filename: "odds.png", mimeType: "image/png" }],
});Media upload requires the media.write scope on your OAuth 2.0 token, in addition to tweet.write. Mint the token with media.write included or uploads fail with a 403.
| Feature | Supported |
|---|---|
| Mentions | Yes (post.mention.create) |
| DMs | Yes (dm.received / dm.sent) |
| Reactions | Likes only (emoji.heart or "like") |
| User lookup | Yes |
| Feature | Supported |
|---|---|
| Fetch messages | DMs via API, posts from cache |
| Fetch single message | Posts via API, DMs from cache |
x:post:{conversationId} # public post threads (channel: x:public)
x:dm:{participantUserId} # direct message with a single userExamples: x:post:1943467279943467279, x:dm:783214. X DM webhooks carry no conversation id, only participant ids, so DMs are threaded by the other participant's user id: openDM("783214") returns x:dm:783214, and sends route to POST /2/dm_conversations/with/783214/messages. Top-level posts go through channel.post on the x:public channel.
X enforces automation rules. Before deploying a bot:
The adapter is strict by default: it never streams by post-and-edit, rejects unsupported interactions loudly, and only replies where your handlers decide to.
XChat is X's encrypted messaging product. It ships from the @chat-adapter/x/chat
subpath of this package, so it installs with @chat-adapter/x and adds no
dependencies unless you import it.
import { createXchatAdapter } from "@chat-adapter/x/chat";The XChat crypto stack (@xdevplatform/chat-xdk, @xdevplatform/xdk,
juicebox-sdk) is declared as optional peer dependencies. Install them
alongside @chat-adapter/x when you use this subpath.
import { Chat } from "chat";
import { createXchatAdapter } from "@chat-adapter/x/chat";
import { createMemoryState } from "@chat-adapter/state-memory";
const bot = new Chat({
userName: "mybot",
adapters: {
xchat: createXchatAdapter(),
},
state: createMemoryState(),
});
// DMs always
bot.onDirectMessage(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});
// Group chats when the bot is @mentioned
bot.onNewMention(async (thread, message) => {
await thread.post(`You said: ${message.text}`);
});Wire the webhook route (e.g. app/api/webhooks/xchat/route.ts in Next.js):
import { bot } from "@/lib/bot";
export async function GET(request: Request) {
return bot.webhooks.xchat(request);
}
export async function POST(request: Request) {
return bot.webhooks.xchat(request);
}When using createXchatAdapter() without arguments, credentials are auto-detected from environment variables. The bot's @handle is resolved from GET /2/users/me at startup, so mention detection works without any hardcoding.
The bot account needs registered public keys and a Juicebox-backed private-key store before it can participate in encrypted conversations:
chat-xdk (generateKeypairs())POST /2/users/{id}/public_keyschat.setup(pin))The adapter unlocks the keys at startup with the same PIN (XCHAT_PIN). Registration is a one-time step per account — see the chat-xdk documentation for the full flow.
Register a webhook URL so the X Activity API can deliver events (docs):
curl -X POST "https://api.x.com/2/webhooks" \
-H "Authorization: Bearer $APP_BEARER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-domain.com/api/webhooks/xchat"}'X validates the URL with a CRC challenge (see Webhook route below), so the endpoint must be live before you create the webhook.
Webhooks and activity subscriptions can also be created and managed in the X Developer Portal instead of via the API.
Create activity subscriptions for the bot user with the bot's OAuth2 user token:
curl -X POST "https://api.x.com/2/activity/subscriptions" \
-H "Authorization: Bearer $BOT_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"event_type": "chat.received",
"filter": {"user_id": "YOUR_BOT_USER_ID"},
"tag": "bot-chat-received",
"webhook_id": "YOUR_WEBHOOK_ID"
}'Subscribe to chat.conversation_join as well if you want the bot to post a welcome message when it is added to a group.
X sends two kinds of requests:
?crc_token=... answered with an HMAC-SHA256 of the token, keyed by your app's consumer secret. The adapter answers this, so route GET to it too.x-twitter-webhooks-signature header.import { bot } from "@/lib/bot";
export async function GET(request: Request) {
return bot.webhooks.xchat(request);
}
export async function POST(request: Request) {
return bot.webhooks.xchat(request);
}Do not sign the token in your own handler. The challenge and the POST signature use the same key, algorithm, and sha256= prefix, so a handler that HMACs an arbitrary crc_token becomes a signing oracle: a caller can pass a forged event body as the token and replay the response as x-twitter-webhooks-signature. Route GET through the adapter as shown above; it rejects malformed CRC tokens before signing them.
All options are auto-detected from environment variables when not provided.
| Option | Required | Description |
|---|---|---|
botToken / accessToken | No* | OAuth2 user access token for the bot account. Auto-detected from XCHAT_BOT_TOKEN or X_ACCESS_TOKEN |
pin | No | Juicebox PIN; when set, keys unlock automatically during initialize(). Auto-detected from XCHAT_PIN |
consumerSecret | For webhooks | App consumer secret for webhook signature verification. Auto-detected from X_CONSUMER_SECRET. Required to receive webhooks: X signs every POST, so without it every POST is rejected with 401. Polling deployments do not need it |
disableWebhookVerification | No | Accept webhook POSTs without verifying their HMAC. Auto-detected from X_DISABLE_WEBHOOK_VERIFICATION. Only use it when an upstream layer verifies the signature. Not recommended in production |
editSafetyDelayMs | No | Minimum age (ms) a freshly posted message must reach before its first edit is sent, so receiving clients have stored the original the edit targets. Defaults to 5000; 0 disables the wait |
sendReadReceipts | No | Send a read receipt for each delivered inbound message before handlers run (default true) |
userName | No | Bot @handle for mention detection. Auto-detected from X_BOT_USERNAME, otherwise resolved from GET /2/users/me |
welcomeMessage | No | Message posted when the bot joins a group. false disables; omitted uses a default that explains @mention-to-reply |
verifySignatures | No | Require verifiable signatures on incoming messages (default true). X_VERIFY_SIGNATURES=false opts out |
signingKeyVersion | No | Signing key version override. Normally fetched during initialize(). Auto-detected from X_SIGNING_KEY_VERSION |
apiBaseUrl | No | Base URL for media REST calls (defaults to https://api.x.com) |
apiHeaders | No | Extra headers on every X API request. Unless it includes a User-Agent, the adapter prepends chat-sdk-xchat/<version> to the client's default so Chat SDK traffic is identifiable |
logger | No | Logger instance (defaults to ConsoleLogger("info")) |
*Required at runtime — either via config or environment variable.
XCHAT_BOT_TOKEN=xcbot_... # OAuth2 user token for the bot account
XCHAT_PIN=... # Juicebox PIN for key unlock
X_CONSUMER_SECRET=... # App secret (CRC + webhook signature verification)
X_BOT_USERNAME=... # Optional @handle override; resolved from /2/users/me otherwise
X_VERIFY_SIGNATURES=true # Optional; set false to accept unverifiable messages| Feature | Supported |
|---|---|
| Post message | Yes (encrypted + signed) |
| Group replies | Yes (quoted reply to the triggering message) |
| Edit message | Yes (encrypted edit event targeting the original's sequence id; only the bot's own text messages). The first edit of a fresh message is held until the message is editSafetyDelayMs old, so receiving clients have stored the original before the edit arrives |
| Delete message | Yes (delete-for-all: a locally signed delete action removes the message for every participant; only the bot's own messages) |
| Streaming | Limited (message edits work, but the first edit is age-gated by editSafetyDelayMs, so rapid token-by-token updates are coarse) |
| Read receipts | Yes (advances the conversation read watermark through each delivered inbound message unless sendReadReceipts: false; call thread.markAsRead() for manual control) |
| TTL propagation | Yes (replies inherit the inbound message's disappearing-message TTL) |
| Feature | Supported |
|---|---|
| Markdown | No client-side rendering — outgoing markdown appears literally as plain text (tables are the exception, see below) |
| URL / @mention entities | Yes (detected in outgoing text, rendered as tappable links and mention pills) |
| Post cards | Yes (first x.com/.../status/... URL in outgoing text auto-attaches) |
| Media out | Yes (files encrypt-streamed and uploaded via the 3-step media upload flow) |
| Media in | Yes (attachments exposed with lazy download + decrypt via fetchData()) |
| Cards / buttons / modals | No (XChat has no interactive message surface) |
| Tables | ASCII code blocks |
| Feature | Supported |
|---|---|
| Mentions | Yes (structured mention entities, swipe-reply-to-bot, plain-text @handle fallback) |
| Add / remove reactions | Yes |
| Incoming reactions | Yes (routed to onReaction) |
| Typing indicator | Yes (keep-alive re-sent every 3s while a handler runs) |
| DMs | Yes |
| Group chats | Yes (g-prefixed conversation IDs) |
| Group join welcome | Yes (configurable via welcomeMessage) |
| Open DM | Yes (openDM(userId) reuses an existing conversation or runs a fresh key exchange; requires the recipient to have encrypted chat set up) |
| Feature | Supported |
|---|---|
| Fetch messages | Yes (GET /2/chat/conversations/{id}/events, batch-decrypted) |
| Fetch thread info | Yes |
| List threads | No |
chat.onNewMention(handler) fires for group messages that mention the bot. A group message counts as a mention when:
@handle (fallback when no entities are present).To also reply to group messages that don't mention the bot, register chat.onNewMessage(handler) without a pattern.
xchat:{conversationId}xchat:1234567890-9876543210 (both participant IDs)xchat:g123456789 (opaque g-prefixed ID)REST paths use the other participant's user ID for 1:1 conversations and the g... ID for groups; the adapter converts automatically.
KeyChange events and are cached per conversation and key version. When a key is missing at send time, the adapter fetches recent conversation events to extract one.GET /2/users/{id}/public_keys and cached). With verifySignatures: true (the default), unverifiable messages are dropped.media_hash_key reference that the recipient uses to download and decrypt the blob.X_CONSUMER_SECRET matches your app's consumer secret in the developer portal{"response_token": "sha256=<base64 HMAC>"} for GET requestsGET /2/activity/subscriptions with the app bearer tokenwebhook_id points at a webhook whose URL is your live endpointx-twitter-webhooks-signature with HMAC-SHA256 keyed by X_CONSUMER_SECRET — make sure it is the same app that owns the webhook/2/users/me), or use { allGroupMessages: true }openDM(userId)). openDM requires the recipient to have encrypted chat set up, and the server requires the recipient to trust the bot (e.g. follow it) before the first message is accepted.If you use an AI coding agent such as OpenAI Codex, Claude Code, or Cursor, install the Chat SDK skill so it knows the SDK APIs, adapter patterns, and project conventions before writing code.
npx skills add vercel/chatThe skill references bundled documentation in node_modules/chat/docs, plus adapter guides and starter templates in the published package.
You can also install the Vercel Plugin for a broader agent toolkit: it includes the Chat SDK skill alongside specialist agents, agent slash commands, and more:
npx plugins add vercel/vercel-pluginThe plugin is optional; the skill alone is enough to build with Chat SDK.
For agent-readable documentation, see chat-sdk.dev/llms.txt (page index) or chat-sdk.dev/llms-full.txt (full text).
MIT
Estimated unpacked size across 24 packages.
2.7 MB
Includes dependencies.