slices.network
Auto-indexing service and GraphQL API for AT Protocol Records
quickslice.slices.network/
atproto
gleam
graphql
docs: add notifications guide
Covers the notifications query and notificationCreated subscription,
including collection filtering, pagination, and response examples.
chadtmiller.com
+179
docs/guides/notifications.md
+179
docs/guides/notifications.md
···
···
1
+
# Notifications
2
+
3
+
Notifications show records that mention the authenticated user. When someone likes your post, follows you, or references your DID in any record, it appears in your notifications.
4
+
5
+
## How It Works
6
+
7
+
The `notifications` query searches all records for your DID. It returns matches where:
8
+
- The record's JSON contains your DID (as a URI or raw DID)
9
+
- The record was authored by someone else (self-mentions excluded)
10
+
11
+
The server identifies you from your access token. Authentication is required.
12
+
13
+
## Basic Query
14
+
15
+
```graphql
16
+
query {
17
+
notifications(first: 20) {
18
+
edges {
19
+
node {
20
+
__typename
21
+
... on AppBskyFeedLike {
22
+
uri
23
+
did
24
+
createdAt
25
+
}
26
+
... on AppBskyGraphFollow {
27
+
uri
28
+
did
29
+
createdAt
30
+
}
31
+
}
32
+
cursor
33
+
}
34
+
pageInfo {
35
+
hasNextPage
36
+
endCursor
37
+
}
38
+
}
39
+
}
40
+
```
41
+
42
+
The `node` is a union type containing all record types in your schema. Use inline fragments (`... on TypeName`) to access type-specific fields.
43
+
44
+
## Response Example
45
+
46
+
When Alice likes your post and Bob follows you:
47
+
48
+
```json
49
+
{
50
+
"data": {
51
+
"notifications": {
52
+
"edges": [
53
+
{
54
+
"node": {
55
+
"__typename": "AppBskyGraphFollow",
56
+
"uri": "at://did:plc:bob/app.bsky.graph.follow/3k2yab7",
57
+
"did": "did:plc:bob",
58
+
"createdAt": "2024-01-03T12:00:00Z"
59
+
},
60
+
"cursor": "eyJ..."
61
+
},
62
+
{
63
+
"node": {
64
+
"__typename": "AppBskyFeedLike",
65
+
"uri": "at://did:plc:alice/app.bsky.feed.like/3k2xz9m",
66
+
"did": "did:plc:alice",
67
+
"createdAt": "2024-01-02T10:30:00Z"
68
+
},
69
+
"cursor": "eyJ..."
70
+
}
71
+
],
72
+
"pageInfo": {
73
+
"hasNextPage": false,
74
+
"endCursor": "eyJ..."
75
+
}
76
+
}
77
+
}
78
+
}
79
+
```
80
+
81
+
Results are sorted newest-first by rkey (TID).
82
+
83
+
## Filtering by Collection
84
+
85
+
Filter to specific record types using the `collections` argument:
86
+
87
+
```graphql
88
+
query {
89
+
notifications(collections: [APP_BSKY_FEED_LIKE], first: 20) {
90
+
edges {
91
+
node {
92
+
... on AppBskyFeedLike {
93
+
uri
94
+
did
95
+
}
96
+
}
97
+
}
98
+
}
99
+
}
100
+
```
101
+
102
+
Collection names use the enum format: `app.bsky.feed.like` becomes `APP_BSKY_FEED_LIKE`.
103
+
104
+
Filter to multiple types:
105
+
106
+
```graphql
107
+
query {
108
+
notifications(
109
+
collections: [APP_BSKY_FEED_LIKE, APP_BSKY_GRAPH_FOLLOW]
110
+
first: 20
111
+
) {
112
+
# ...
113
+
}
114
+
}
115
+
```
116
+
117
+
## Pagination
118
+
119
+
Use cursor-based pagination to fetch more results:
120
+
121
+
```graphql
122
+
query {
123
+
notifications(first: 20, after: "eyJ...") {
124
+
edges {
125
+
node { __typename }
126
+
cursor
127
+
}
128
+
pageInfo {
129
+
hasNextPage
130
+
endCursor
131
+
}
132
+
}
133
+
}
134
+
```
135
+
136
+
Pass `pageInfo.endCursor` as the `after` argument to fetch the next page.
137
+
138
+
## Real-time Updates
139
+
140
+
Subscribe to new notifications as they happen:
141
+
142
+
```graphql
143
+
subscription {
144
+
notificationCreated {
145
+
__typename
146
+
... on AppBskyFeedLike {
147
+
uri
148
+
did
149
+
createdAt
150
+
}
151
+
... on AppBskyGraphFollow {
152
+
uri
153
+
did
154
+
createdAt
155
+
}
156
+
}
157
+
}
158
+
```
159
+
160
+
Filter to specific collections:
161
+
162
+
```graphql
163
+
subscription {
164
+
notificationCreated(collections: [APP_BSKY_FEED_LIKE]) {
165
+
... on AppBskyFeedLike {
166
+
uri
167
+
did
168
+
}
169
+
}
170
+
}
171
+
```
172
+
173
+
See [Subscriptions](./subscriptions.md) for WebSocket connection details.
174
+
175
+
## Authentication Required
176
+
177
+
Notifications require authentication. Without a valid access token, the query returns an error.
178
+
179
+
Use the [Quickslice client SDK](./authentication.md#using-the-client-sdk) to handle authentication automatically.
+1
www/src/www/config.gleam
+1
www/src/www/config.gleam
···
48
#("guides/joins.md", "/guides/joins", "Joins"),
49
#("guides/mutations.md", "/guides/mutations", "Mutations"),
50
#("guides/moderation.md", "/guides/moderation", "Moderation"),
51
+
#("guides/notifications.md", "/guides/notifications", "Notifications"),
52
#("guides/viewer-state.md", "/guides/viewer-state", "Viewer State"),
53
#(
54
"guides/authentication.md",