app.bsky.notification

Overview

The app.bsky.notification namespace provides lexicons for managing notifications about social interactions and activity.

Key Concepts

Notifications: Events about interactions with your content (likes, replies, follows, etc.)
Notification Reasons: Different types of notification events
Read State: Whether notifications have been seen
Preferences: Settings for which notifications to receive
Activity Subscriptions: Subscribe to posts from specific users

Queries

listNotifications

List notifications for the authenticated user. Endpoint: app.bsky.notification.listNotifications Authentication: Required

array

Filter by specific notification reasons

integer

Max notifications (1-100, default 50)

boolean

Whether to show priority notifications

string

Pagination cursor

string

ISO 8601 timestamp of when notifications were last seen

Response:

string

Next page cursor

array

required

Array of notification objects

boolean

Whether these are priority notifications

string

When notifications were last seen

Example:

const response = await agent.listNotifications({
  limit: 25
})

for (const notif of response.data.notifications) {
  console.log(`${notif.reason}: ${notif.author.handle}`)
  
  if (notif.reason === 'like') {
    console.log('Liked your post:', notif.reasonSubject)
  } else if (notif.reason === 'follow') {
    console.log('New follower!')
  } else if (notif.reason === 'reply') {
    console.log('Reply:', notif.record.text)
  }
}

curl -H "Authorization: Bearer $ACCESS_JWT" \
  "https://bsky.social/xrpc/app.bsky.notification.listNotifications?limit=10"

getUnreadCount

Get count of unread notifications. Endpoint: app.bsky.notification.getUnreadCount Authentication: Required

boolean

Only count priority notifications

string

ISO 8601 timestamp to check unread count since

Response:

integer

required

Number of unread notifications

Example:

const response = await agent.app.bsky.notification.getUnreadCount()
console.log('Unread notifications:', response.data.count)

Procedures

updateSeen

Update the seen timestamp for notifications. Endpoint: app.bsky.notification.updateSeen Authentication: Required

string

required

ISO 8601 timestamp

Example:

// Mark all current notifications as seen
await agent.app.bsky.notification.updateSeen({
  seenAt: new Date().toISOString()
})

registerPush

Register a device for push notifications. Endpoint: app.bsky.notification.registerPush Authentication: Required

string

required

DID of the push notification service

string

required

Push notification token

string

required

Platform: ios, android, or web

string

required

Application identifier

Example:

// iOS example
await agent.app.bsky.notification.registerPush({
  serviceDid: 'did:web:push.bsky.app',
  token: deviceToken,
  platform: 'ios',
  appId: 'xyz.blueskyweb.app'
})

unregisterPush

Unregister a device from push notifications. Endpoint: app.bsky.notification.unregisterPush Authentication: Required

string

required

DID of the push notification service

string

required

Push notification token to unregister

Preferences

getPreferences

Get notification preferences. Endpoint: app.bsky.notification.getPreferences Authentication: Required Response: Notification preferences object Example:

const response = await agent.app.bsky.notification.getPreferences()
const prefs = response.data

console.log('Like notifications:', prefs.like.push)
console.log('Follow notifications:', prefs.follow.list)

putPreferences

Update notification preferences. Endpoint: app.bsky.notification.putPreferences Authentication: Required

object

required

Notification preferences object

Example:

await agent.app.bsky.notification.putPreferences({
  preferences: {
    chat: {
      include: 'all',
      push: true
    },
    follow: {
      include: 'all',
      list: true,
      push: true
    },
    like: {
      include: 'follows',
      list: true,
      push: false
    },
    mention: {
      include: 'all',
      list: true,
      push: true
    },
    reply: {
      include: 'all',
      list: true,
      push: true
    },
    repost: {
      include: 'follows',
      list: true,
      push: false
    },
    quote: {
      include: 'all',
      list: true,
      push: true
    },
    likeViaRepost: {
      include: 'all',
      list: false,
      push: false
    },
    repostViaRepost: {
      include: 'all',
      list: false,
      push: false
    },
    starterpackJoined: {
      list: true,
      push: true
    },
    subscribedPost: {
      list: true,
      push: true
    },
    unverified: {
      list: true,
      push: false
    },
    verified: {
      list: true,
      push: true
    }
  }
})

Activity Subscriptions

putActivitySubscription

Subscribe to activity from a user (get notified of their posts). Endpoint: app.bsky.notification.putActivitySubscription Authentication: Required

string

required

DID of the user to subscribe to

object

required

Subscription settings (post, reply)

Example:

// Subscribe to all posts and replies from a user
await agent.app.bsky.notification.putActivitySubscription({
  subject: 'did:plc:z72i7hdynmk6r22z27h6tvur',
  activitySubscription: {
    post: true,
    reply: true
  }
})

// Subscribe to posts only
await agent.app.bsky.notification.putActivitySubscription({
  subject: 'did:plc:z72i7hdynmk6r22z27h6tvur',
  activitySubscription: {
    post: true,
    reply: false
  }
})

// Unsubscribe
await agent.app.bsky.notification.putActivitySubscription({
  subject: 'did:plc:z72i7hdynmk6r22z27h6tvur',
  activitySubscription: {
    post: false,
    reply: false
  }
})

listActivitySubscriptions

List activity subscriptions. Endpoint: app.bsky.notification.listActivitySubscriptions Authentication: Required

integer

Max subscriptions (1-100, default 50)

string

Pagination cursor

Response: Array of activity subscription objects

Notification Types

notification

Notification object structure.

string

required

AT-URI of the notification record

string

required

CID of the notification record

object

required

Profile of the actor who triggered the notification

string

required

Notification reason (see below)

string

AT-URI of the subject (e.g., the post that was liked)

object

required

The notification record data

boolean

required

Whether notification has been read

string

required

When notification was created

array

Content labels

Notification Reasons

Possible values for the reason field:

like: Someone liked your post
repost: Someone reposted your post
follow: Someone followed you
mention: Someone mentioned you in a post
reply: Someone replied to your post
quote: Someone quoted your post
starterpack-joined: Someone joined via your starter pack
verified: You received verification
unverified: Verification was removed
like-via-repost: Someone liked a post via your repost
repost-via-repost: Someone reposted a post via your repost
subscribed-post: New post from someone you’re subscribed to
contact-match: Contact match found

Type Definitions

preferences

Notification preferences for all notification types.

object

required

Chat notification settings

object

required

Follow notification settings

object

required

Like notification settings

object

required

Like-via-repost notification settings

object

required

Mention notification settings

object

required

Quote notification settings

object

required

Reply notification settings

object

required

Repost notification settings

object

required

Repost-via-repost notification settings

object

required

Starter pack join notification settings

object

required

Subscribed post notification settings

object

required

Unverified notification settings

object

required

Verified notification settings

filterablePreference

Settings for filterable notification types.

string

required

Who to include: all or follows

boolean

required

Show in notification list

boolean

required

Send push notification

activitySubscription

Activity subscription settings.

boolean

required

Notify for new posts

boolean

required

Notify for new replies

Common Use Cases

Display Notification Feed

const { data } = await agent.listNotifications({ limit: 20 })

for (const notif of data.notifications) {
  switch (notif.reason) {
    case 'like':
      console.log(`${notif.author.displayName} liked your post`)
      break
    case 'follow':
      console.log(`${notif.author.displayName} followed you`)
      break
    case 'reply':
      console.log(`${notif.author.displayName} replied: ${notif.record.text}`)
      break
    case 'mention':
      console.log(`${notif.author.displayName} mentioned you: ${notif.record.text}`)
      break
    case 'quote':
      console.log(`${notif.author.displayName} quoted your post`)
      break
    case 'repost':
      console.log(`${notif.author.displayName} reposted your post`)
      break
  }
}

// Mark as seen
await agent.app.bsky.notification.updateSeen({
  seenAt: new Date().toISOString()
})

Notification Badge

// Get unread count for badge
const { data } = await agent.app.bsky.notification.getUnreadCount()
setBadgeCount(data.count)

// When user opens notifications
await agent.app.bsky.notification.updateSeen({
  seenAt: new Date().toISOString()
})
setBadgeCount(0)

// Subscribe to a user's posts
await agent.app.bsky.notification.putActivitySubscription({
  subject: userDid,
  activitySubscription: {
    post: true,
    reply: false  // Don't notify for their replies
  }
})

// You'll now get 'subscribed-post' notifications when they post

Configure Notification Preferences

// Get current preferences
const { data } = await agent.app.bsky.notification.getPreferences()

// Disable push for likes, only show in list
data.like.push = false
data.like.list = true

// Only show follows from people you follow
data.follow.include = 'follows'

// Update preferences
await agent.app.bsky.notification.putPreferences({
  preferences: data
})

app.bsky.actor - User profiles and preferences
app.bsky.feed - Posts and interactions
app.bsky.graph - Social relationships

Overview

com.atproto

app.bsky

app.bsky.notification

Overview

Key Concepts

Queries

listNotifications

getUnreadCount

Procedures

updateSeen

registerPush

unregisterPush

Preferences

getPreferences

putPreferences

Activity Subscriptions

putActivitySubscription

listActivitySubscriptions

Notification Types

notification

Notification Reasons

Type Definitions

preferences

filterablePreference

activitySubscription

Common Use Cases

Display Notification Feed

Notification Badge

Configure Notification Preferences

Resources

​Overview

​Key Concepts

​Queries

​listNotifications

​getUnreadCount

​Procedures

​updateSeen

​registerPush

​unregisterPush

​Preferences

​getPreferences

​putPreferences

​Activity Subscriptions

​putActivitySubscription

​listActivitySubscriptions

​Notification Types

​notification

​Notification Reasons

​Type Definitions

​preferences

​filterablePreference

​activitySubscription

​Common Use Cases

​Display Notification Feed

​Notification Badge

​Subscribe to User Updates

​Configure Notification Preferences

​Related Lexicons

​Resources

Overview

Key Concepts

Queries

listNotifications

getUnreadCount

Procedures

updateSeen

registerPush

unregisterPush

Preferences

getPreferences

putPreferences

Activity Subscriptions

putActivitySubscription

listActivitySubscriptions

Notification Types

notification

Notification Reasons

Type Definitions

preferences

filterablePreference

activitySubscription

Common Use Cases

Display Notification Feed

Notification Badge

Subscribe to User Updates

Configure Notification Preferences

Related Lexicons

Resources