X

Install

Quick start

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!");
});

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);
}

Configuration

Authentication

1. Create an X app

1. Go to the X developer portal and create a Project and App.
2. Under Keys and tokens, copy the API Key Secret to X_CONSUMER_SECRET.
3. Enable OAuth 2.0 user authentication with the scopes tweet.read, tweet.write, users.read, dm.read, dm.write, like.write, and offline.access.
4. Complete the OAuth 2.0 flow for the bot account. Either store the access token as X_USER_ACCESS_TOKEN, or store X_CLIENT_ID plus X_REFRESH_TOKEN to let the adapter manage token refresh.

2. Register a webhook and subscriptions

X delivers events through the X Activity API. Set this up once, in the X developer console, which handles the auth for you:

1. Register your webhook URL (https://your-domain.com/api/webhooks/x). It must be publicly reachable over HTTPS and cannot include a port. X sends a CRC challenge immediately and revalidates hourly; the adapter answers both automatically.
2. Create subscriptions for the events the adapter consumes: post.mention.create, dm.received, and dm.sent. These are private events, so the bot user must have authorized your app first.

Advanced

Webhook flow

• CRC challenge (GET): X sends a crc_token, answered with sha256=<base64 HMAC> keyed by the consumer secret.
• Event delivery (POST): activity events signed via x-twitter-webhooks-signature, verified against the raw request body with timing-safe comparison.

Streaming

X has no native streaming and public post edits are eligibility-gated, so the adapter buffers the entire stream and posts once on completion instead of using post+edit updates.

Reply threading

Replies target the most recent mention received in the conversation, and consecutive replies chain under the bot's previous reply. Top-level posts go through channel.post on the x:public channel.

Reactions

Likes are the only reaction X exposes. addReaction accepts emoji.heart or "like" and maps to POST /2/users/:id/likes; anything else throws a ValidationError.

Thread ID format

x:post:{conversationId}   # public post threads (channel: x:public)
x:dm:{participantUserId}  # direct message with a single user

Examples: 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 both replies and inbound events for that conversation share the same thread. Sends route to the by-participant endpoint (POST /2/dm_conversations/with/{id}/messages).

Automation policy

X enforces automation rules: get explicit consent before automated replies or DMs, honor opt-outs immediately, disclose the bot identity in the account profile, and never send bulk or duplicate automated content.

Feature support