Skip to main content

​
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
​
reasons
array
Filter by specific notification reasons
​
limit
integer
Max notifications (1-100, default 50)
​
priority
boolean
Whether to show priority notifications
​
cursor
string
Pagination cursor
​
seenAt
string
ISO 8601 timestamp of when notifications were last seen
Response:
​
cursor
string
Next page cursor
​
notifications
array
required
Array of notification objects
​
priority
boolean
Whether these are priority notifications
​
seenAt
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
​
priority
boolean
Only count priority notifications
​
seenAt
string
ISO 8601 timestamp to check unread count since
Response:
​
count
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
​
seenAt
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
​
serviceDid
string
required
DID of the push notification service
​
token
string
required
Push notification token
​
platform
string
required
Platform: ios, android, or web
​
appId
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
​
serviceDid
string
required
DID of the push notification service
​
token
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
​
preferences
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
​
subject
string
required
DID of the user to subscribe to
​
activitySubscription
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
​
limit
integer
Max subscriptions (1-100, default 50)
​
cursor
string
Pagination cursor
Response: Array of activity subscription objects

​
Notification Types

​
notification

Notification object structure.
​
uri
string
required
AT-URI of the notification record
​
cid
string
required
CID of the notification record
​
author
object
required
Profile of the actor who triggered the notification
​
reason
string
required
Notification reason (see below)
​
reasonSubject
string
AT-URI of the subject (e.g., the post that was liked)
​
record
object
required
The notification record data
​
isRead
boolean
required
Whether notification has been read
​
indexedAt
string
required
When notification was created
​
labels
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.
​
chat
object
required
Chat notification settings
​
follow
object
required
Follow notification settings
​
like
object
required
Like notification settings
​
likeViaRepost
object
required
Like-via-repost notification settings
​
mention
object
required
Mention notification settings
​
quote
object
required
Quote notification settings
​
reply
object
required
Reply notification settings
​
repost
object
required
Repost notification settings
​
repostViaRepost
object
required
Repost-via-repost notification settings
​
starterpackJoined
object
required
Starter pack join notification settings
​
subscribedPost
object
required
Subscribed post notification settings
​
unverified
object
required
Unverified notification settings
​
verified
object
required
Verified notification settings

​
filterablePreference

Settings for filterable notification types.
​
include
string
required
Who to include: all or follows
​
list
boolean
required
Show in notification list
​
push
boolean
required
Send push notification

​
activitySubscription

Activity subscription settings.
​
post
boolean
required
Notify for new posts
​
reply
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 User Updates

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

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us