Notifications

Access your notification timeline, manage notification settings, and check badge counts.

notifications.timeline(opts?)

Get your notifications timeline. Uses the GraphQL NotificationsTimeline query.

Option	Type	Description
opts.count	number	Number of results (default 20)
opts.cursor	string	Pagination cursor
opts.variables	object	Additional GraphQL variables

const notifs = await client.notifications.timeline();

// Fetch more
const more = await client.notifications.timeline({ count: 50 });

// Paginate
const next = await client.notifications.timeline({ cursor: "DAABCgAB..." });

notifications.enableWebNotifications()

Enable logged-out web push notifications. Uses the GraphQL EnableLoggedOutWebNotifications mutation.

await client.notifications.enableWebNotifications();

notifications.saveSettings(params?)

Save notification settings. Uses the v1.1 notifications/settings/save endpoint.

await client.notifications.saveSettings({
  // notification setting parameters
});

notifications.loginSettings(params?)

Update notification settings on login. Uses the v1.1 notifications/settings/login endpoint.

await client.notifications.loginSettings({
  // login notification parameters
});

notifications.checkin(params?)

Check in for notification settings. Uses the v1.1 notifications/settings/checkin endpoint.

await client.notifications.checkin();

notifications.badge(params?)

Get the notification badge count (unread count). Uses the v2 badge_count/badge_count endpoint.

const badge = await client.notifications.badge();
console.log(badge);

Full example

// Check unread notification count
const badge = await client.notifications.badge();

// Fetch your notifications
const notifs = await client.notifications.timeline();

// Get more notifications with pagination
const page2 = await client.notifications.timeline({
  count: 40,
  cursor: "DAABCgAB...",
});

// Enable web push notifications
await client.notifications.enableWebNotifications();

// Save custom notification settings
await client.notifications.saveSettings({
  // your settings
});

notifications.markSeen(cursor, type?)

Mark notifications as read, the same call x.com makes when you open the notifications tab. Pass the previousCursor (the top cursor) of the notifications page you showed. After this, the timeline's unreadAfterSortIndex moves up to your newest notification and Twitter's own unread count clears on every device.

Argument	Type	Description
cursor	string	previousCursor from notifications.timeline()
type	string	"all" (default), "mentions" or "verified"

const page = await client.notifications.timeline();
await client.notifications.markSeen(page.previousCursor);

notifications.devicePosts(opts?)

New posts from accounts you turned on post notifications for (the bell on a profile). This is what the "New post notifications for ..." entry opens on x.com. Uses GET /2/notifications/device_follow.json.

const { tweetIds, cursor } = await client.notifications.devicePosts();
const older = await client.notifications.devicePosts({ cursor });

Returns { tweetIds, cursor, raw }. tweetIds are newest first and cursor pages older posts. Hydrate the ids with tweets.getMany or TweetResultsByRestIds if you want full post objects, since raw.globalObjects holds the older REST shape.

account.badgeCounts()

Get the unread counts x.com shows on the sidebar badges. Uses the GraphQL ViewerBadgeCounts query with the x-twitter-polling header, like the web app's poller.

const counts = await client.account.badgeCounts();
// { dm_unread_count: 0, ntab_unread_count: 1, xchat_unread_count: 0, total_unread_count: 1, is_from_urt: true }