Add Presences API announcement, docs, and changelog by adityaoberai · Pull Request #3010 · appwrite/website

adityaoberai · 2026-05-19T14:26:16Z

What does this PR do?

(Provide a description of what this PR does.)

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work.)

Related PRs and Issues

(If this PR is related to any other PR or resolves any issue or related to any issue link all related PR and issues here.)

Have you read the Contributing Guidelines on issues?

(Write your answer here.)

appwrite · 2026-05-19T14:26:25Z

Appwrite Website

Project ID: 69d7efb00023389e8d27

Sites (1)

Site	Status	Logs	Preview	QR
website `69d7f2670014e24571ca`	Ready	View Logs	Preview URL

Website (appwrite/website)

Project ID: 684969cb000a2f6c0a02

Sites (1)

Site	Status	Logs	Preview	QR
website `68496a17000f03d62013`	Processing	View Logs	Preview URL

Tip

Git integration provides automatic deployments with optional PR comments

greptile-apps · 2026-05-19T14:29:39Z

Greptile Summary

This PR adds the Appwrite Presences API across the full documentation surface: a blog post announcement, a changelog entry, a comprehensive reference guide under docs/apis/realtime/presences, a product guide under docs/products/auth/presences, updates to the channels reference, navigation entries in three layouts, a service description for the API reference explorer, and the static cover image.

The blog post and both doc guides correctly use presences.*.delete/upsert/update wildcard event format, seed initial state with list() before subscribing, and use presences.upsert() (not update()) in the heartbeat helper — earlier-flagged issues appear resolved in the current state of the files.
A new realtime.upsertPresence() API is documented for connection-lifetime presence management, with code samples across all SDKs.
The .optimize-cache.json entry still references the wrong path (announcing-presence-api/cover.png instead of announcing-presences-api/cover.avif), which was flagged in a prior review cycle.

Confidence Score: 4/5

Safe to merge after confirming the .optimize-cache.json path mismatch and resolving the open discussion threads; the core documentation content is substantially complete and correct.

The main content — events format, heartbeat pattern, subscribe examples — looks correct in the current state of the files. The one new finding (undefined client in the blog's Realtime queries snippet) is a doc-only concern. The .optimize-cache.json entry points to a non-existent path/extension, which was flagged in a prior cycle and remains unresolved. Several open discussion threads are still active and await author or team confirmation.

.optimize-cache.json (stale path), src/routes/blog/post/announcing-presences-api/+page.markdoc (incomplete Realtime queries snippet), and the open discussion threads on src/routes/docs/apis/realtime/presences/+page.markdoc.

Important Files Changed

Filename	Overview
src/routes/blog/post/announcing-presences-api/+page.markdoc	New blog post announcing the Presences API; subscribe examples use correct `presences.*.delete` event format and seed initial state with `list()` before subscribing. The "Pair it with Realtime queries" snippet imports `Client` but never instantiates it, leaving `client` undefined when `new Realtime(client)` is called.
src/routes/docs/apis/realtime/presences/+page.markdoc	Large new reference page for the Presences API. Current version uses correct `presences.*.upsert/update/delete` wildcard event format in subscribe examples, and properly documents `realtime.upsertPresence()` for the "while connected" pattern.
src/routes/docs/products/auth/presences/+page.markdoc	New auth product guide for Presences. Correctly uses `presences.upsert()` in the heartbeat/setStatus helper (not `update()`), seeds the "online now" list with `list()` before subscribing, and uses correct `presences.*.delete` event format throughout.
src/routes/docs/apis/realtime/channels/+page.markdoc	Adds `presences` and `presences.<ID>` channel rows. Both now include `upsert`, `update`, and `delete` event types in their descriptions, consistent with the full presences reference page.
src/routes/changelog/(entries)/2026-05-22.markdoc	New changelog entry for the Presences API launch; cover image path matches the committed `cover.avif` file.
src/lib/utils/references.ts	Adds `Presences` entry to the `Service` enum and `serviceMap`; straightforward two-line addition with no issues.
.optimize-cache.json	Cache entry added for `static/images/blog/announcing-presence-api/cover.png` (singular "presence", `.png` extension) but the actual committed image is at `static/images/blog/announcing-presences-api/cover.avif` — different folder name and extension.

_{Reviews (23): Last reviewed commit: "Add 'Presences' link to the API referenc..." | Re-trigger Greptile}

adityaoberai · 2026-05-19T15:17:08Z

@ArnabChatterjee20k I'm still working on some more updates, will ping on Discord once ready

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

…ebsite into add-presence-api-docs

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

- Rust `list` code block did not compile: `Query::equal` returns a `Query` but `list` expects `Vec<String>`, and `vec!["online".into()]` was type-ambiguous. Use `Query::equal("status", vec!["online".to_string()]).to_string()`. - Add the Presence API announcement cover image, optimized to avif.

Three errors in the upsert block surfaced by `cargo build`: - Wrong positional arg: the SDK signature is `upsert(presence_id, user_id, status, permissions, expires_at, metadata)` but the permissions vector was placed in slot 6 (metadata). - `Role::users()` requires `Option<&str>` — use `Role::users(None)`. - `Permission::read(...)` returns a `Permission`; the `permissions` parameter wants `Vec<String>`, so `.to_string()` is needed. Verified by running each Rust doc block against a local server: the fixed upsert creates a presence with `permissions: ["read(\"users\")"]` and the full get / list / update / delete lifecycle succeeds.

…ebsite into add-presence-api-docs

… and bun.lock

greptile-apps · 2026-05-25T14:42:09Z

  "static/images/blog/announcing-new-push-notifications-features/cover.png": "a0c758cf6c8a95e09a0d2ca562b0775a50d34a4d691d675cda70e44ad21805ac",
  "static/images/blog/announcing-opt-in-relationship-loading/cover.png": "e16cc16ea6d968b29af19bcd6274741141584a7efe5e1bb18be19b77c3a380c8",
  "static/images/blog/announcing-phone-OTP-pricing/cover.png": "598d55359ca4cb2b46846a8fd76b1f051be7c5f3199b50ffa92a28e84e5f3d67",
+  "static/images/blog/announcing-presence-api/cover.png": "9c3600d4014e5eecb59ea2d2e0d84c4ac52bf38357ad465f44631c9421bf5734",


The new cache entry references static/images/blog/announcing-presence-api/cover.png (singular "presence", .png extension), but the static asset committed in this PR lives at static/images/blog/announcing-presences-api/cover.avif — a different folder name and file extension. If the optimize pipeline tries to process the cached path, it will either error on a missing file or silently leave a dead entry. The entry should point to the actual file path.

Suggested change

"static/images/blog/announcing-presence-api/cover.png": "9c3600d4014e5eecb59ea2d2e0d84c4ac52bf38357ad465f44631c9421bf5734",

"static/images/blog/announcing-presences-api/cover.avif": "9c3600d4014e5eecb59ea2d2e0d84c4ac52bf38357ad465f44631c9421bf5734",

Add Presence API announcement, docs, and changelog

8fcd080

adityaoberai requested review from ArnabChatterjee20k, abnegate, atharvadeosthale and eldadfux May 19, 2026 14:26

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/blog/post/announcing-presences-api/+page.markdoc

Comment thread src/routes/changelog/(entries)/2026-05-22.markdoc Outdated

ArnabChatterjee20k reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/changelog/(entries)/2026-05-19-2.markdoc Outdated

ArnabChatterjee20k reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/changelog/(entries)/2026-05-22.markdoc Outdated

ArnabChatterjee20k reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presence/+page.markdoc Outdated

ArnabChatterjee20k reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presence/+page.markdoc Outdated

adityaoberai added 2 commits May 19, 2026 21:24

content fixes

8e021a0

add note on upsert being keyed by userid

87ef8ea

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/blog/post/announcing-presence-api/+page.markdoc Outdated

ArnabChatterjee20k approved these changes May 19, 2026

View reviewed changes

Update src/routes/blog/post/announcing-presence-api/+page.markdoc

780787b

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presence/+page.markdoc Outdated

adityaoberai added 3 commits May 19, 2026 22:21

Include Realtime queries mention

457bc52

Merge branch 'add-presence-api-docs' of https://github.com/appwrite/w…

f345036

…ebsite into add-presence-api-docs

update date to may 20

c5758a5

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presences/+page.markdoc

Comment thread src/routes/docs/apis/realtime/presences/+page.markdoc

Comment thread src/routes/docs/apis/realtime/channels/+page.markdoc Outdated

adityaoberai and others added 2 commits May 19, 2026 22:37

Update src/routes/docs/apis/realtime/presence/+page.markdoc

2ff7a1d

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Update src/routes/docs/apis/realtime/channels/+page.markdoc

5fec97e

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presence/+page.markdoc Outdated

adityaoberai and others added 2 commits May 19, 2026 22:47

Update src/routes/docs/apis/realtime/presence/+page.markdoc

9f54758

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

Update src/routes/docs/apis/realtime/presence/+page.markdoc

57da537

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

greptile-apps Bot reviewed May 19, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presence/+page.markdoc Outdated

Update src/routes/docs/apis/realtime/presence/+page.markdoc

cef477a

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

greptile-apps Bot reviewed May 22, 2026

View reviewed changes

Comment thread src/routes/docs/apis/realtime/presences/+page.markdoc

adityaoberai added 3 commits May 22, 2026 19:04

Additional examples for listing and subscribing to user presences

61ea6ba

include update events

804e334

fix .gitignore

e27b82d

greptile-apps Bot reviewed May 22, 2026

View reviewed changes

Comment thread src/routes/blog/post/announcing-presences-api/+page.markdoc

adityaoberai added 2 commits May 22, 2026 19:39

Add expiry and permissions examples

8f18c34

Update presence subscription example to include initial list rendering

9cda1a6

adityaoberai requested review from ArnabChatterjee20k and atharvadeosthale May 22, 2026 14:12

ArnabChatterjee20k approved these changes May 22, 2026

View reviewed changes

atharvadeosthale approved these changes May 22, 2026

View reviewed changes

adityaoberai added 3 commits May 22, 2026 21:33

add realtime.upsertPresence explanation

a391e28

Add Presence to sidenavs

ea1a50b

clarify default permissions

2060e68

adityaoberai force-pushed the add-presence-api-docs branch from bd1f1a9 to 2060e68 Compare May 22, 2026 18:03

adityaoberai and others added 6 commits May 23, 2026 00:06

update code examples to include permissions

c0c8d89

update cover image + add presences to API reference

f47426e

Update Presence to Presences

a5115f5

Merge branch 'add-presence-api-docs' of https://github.com/appwrite/w…

266f96a

…ebsite into add-presence-api-docs

update blog route

9f5b3fd

adityaoberai changed the title ~~Add Presence API announcement, docs, and changelog~~ Add Presences API announcement, docs, and changelog May 25, 2026

adityaoberai added 2 commits May 25, 2026 20:02

fix: remove duplicate @appwrite.io/specs dependency from package.json…

bf7745c

… and bun.lock

Merge branch 'main' into add-presence-api-docs

0f1846c

greptile-apps Bot reviewed May 25, 2026

View reviewed changes

Add 'Presences' link to the API reference navigation

0f8af1e

adityaoberai merged commit cc1e45f into main May 25, 2026
7 checks passed

adityaoberai deleted the add-presence-api-docs branch May 25, 2026 15:22

adityaoberai restored the add-presence-api-docs branch May 25, 2026 15:23

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Presences API announcement, docs, and changelog#3010

Add Presences API announcement, docs, and changelog#3010
adityaoberai merged 33 commits into
mainfrom
add-presence-api-docs

adityaoberai commented May 19, 2026

Uh oh!

appwrite Bot commented May 19, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented May 19, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adityaoberai commented May 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot May 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	"static/images/blog/announcing-presence-api/cover.png": "9c3600d4014e5eecb59ea2d2e0d84c4ac52bf38357ad465f44631c9421bf5734",
	"static/images/blog/announcing-presences-api/cover.avif": "9c3600d4014e5eecb59ea2d2e0d84c4ac52bf38357ad465f44631c9421bf5734",

Conversation

adityaoberai commented May 19, 2026

What does this PR do?

Test Plan

Related PRs and Issues

Have you read the Contributing Guidelines on issues?

Uh oh!

appwrite Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Appwrite Website

Website (appwrite/website)

Uh oh!

greptile-apps Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adityaoberai commented May 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps Bot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

appwrite Bot commented May 19, 2026 •

edited

Loading

greptile-apps Bot commented May 19, 2026 •

edited

Loading