wip: AIT push feature documentation #3180
Conversation
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
||
| Traditional AI chat interfaces require users to stay online while the agent works. This creates poor experiences for tasks that take minutes or hours: | ||
|
|
||
| * **Users can't multitask** - They must keep the app open and monitor progress |
There was a problem hiding this comment.
Please no bold in bullets like this. It's unnecessary and is an AI tell
|
|
||
| ## How push notifications work with AI Transport | ||
|
|
||
| Ably's push notification system integrates seamlessly with AI Transport patterns. When an agent completes a background task, you publish both a realtime message (for online users) and a push notification (for offline users). The platform handles delivery to the appropriate transport automatically. |
There was a problem hiding this comment.
| Ably's push notification system integrates seamlessly with AI Transport patterns. When an agent completes a background task, you publish both a realtime message (for online users) and a push notification (for offline users). The platform handles delivery to the appropriate transport automatically. | |
| Ably's push notification system integrates seamlessly with AI Transport patterns. When an agent completes a background task, you publish both a realtime message (for online users) and/or a push notification (for offline users). By supporting both transports through a unified API, Ably simplifies handling delivery via the most appropriate transport. |
(The previous wording implied that Ably will automatically use one transport or the other.)
|
|
||
| Ably's push notification system integrates seamlessly with AI Transport patterns. When an agent completes a background task, you publish both a realtime message (for online users) and a push notification (for offline users). The platform handles delivery to the appropriate transport automatically. | ||
|
|
||
| The recommended pattern is **channel publishing with push extras**: |
| 4. Ably delivers via push (FCM, APNs, or Web Push) if user is offline | ||
| 5. User receives notification and can resume session to view results | ||
|
|
||
| This approach provides a unified publishing API while automatically adapting to user connectivity state. |
There was a problem hiding this comment.
I'm not convinced that unconditionally sending both should be our recommendation.
|
|
||
| ## Publishing push notifications on task completion | ||
|
|
||
| When your agent finishes a long-running task, publish a message with push notification payload to notify offline users. |
There was a problem hiding this comment.
Should this also mention alerting the user for HITL?
| ``` | ||
| </Code> | ||
|
|
||
| The `collapseKey` ensures that multiple rapid completions replace previous notifications rather than stacking (on Android/iOS), while `data.taskId` enables precise navigation when users tap the notification. |
There was a problem hiding this comment.
Mention something about how you might address this for web push?
| </Code> | ||
|
|
||
| <Aside data-type="important"> | ||
| Avoid sending push notifications for every incremental update (like token streaming). Reserve push for meaningful milestones: task started, significant progress (>50% complete), or completion. Excessive notifications create poor user experiences and may trigger platform rate limits. |
There was a problem hiding this comment.
| Avoid sending push notifications for every incremental update (like token streaming). Reserve push for meaningful milestones: task started, significant progress (>50% complete), or completion. Excessive notifications create poor user experiences and may trigger platform rate limits. | |
| Avoid sending push notifications for every incremental update (such as every intermediate response in a longer task). Reserve push for meaningful milestones: task started, significant progress (>50% complete), or completion. Excessive notifications create poor user experiences and may trigger device rate limits. |
| updateProgressBar(message.data.progress); | ||
| }); | ||
| ``` | ||
| </Code> |
There was a problem hiding this comment.
Should there be some mention of the need to unsubscribe? For example the server could delete all subscriptions for a given channel when that conversation ends using removeWhere(params={channel:xxx})
| For high-frequency agents or users with multiple concurrent sessions, implement server-side filtering to reduce notification noise. | ||
|
|
||
| ### Presence-based notification filtering | ||
|
|
There was a problem hiding this comment.
I think this could do with an expanded introduction/motivation
| </Code> | ||
|
|
||
| <Aside data-type="note"> | ||
| Presence checks add latency (typically 50-200ms for global presence queries). For most applications, the simpler approach is to always include push extras and let client-side logic suppress notifications when the app is active. Presence-based filtering is most valuable for high-frequency updates or when minimizing notification count is critical. |
There was a problem hiding this comment.
This is wrong. Checking presence as a realtime client does not involve any network interaction.
|
|
||
| ### Required setup steps | ||
|
|
||
| 1. **Configure push credentials** in the Ably dashboard: |
paddybyers
left a comment
paddybyers
left a comment
There was a problem hiding this comment.
Some comments (I realise this is still draft)
| AblyRealtime realtime = new AblyRealtime("YOUR_API_KEY"); | ||
| realtime.options.clientId = userId; |
There was a problem hiding this comment.
I think we shouldn't update options on the running client, and never suggest sdk users to do this. This can lead to errors. realtime.options - should be readonly
| AblyRealtime realtime = new AblyRealtime("YOUR_API_KEY"); | |
| realtime.options.clientId = userId; | |
| ClientOptions options = new ClientOptions(); | |
| options.key = "YOUR_API_KEY"; | |
| options.clientId = userId; | |
| AblyRealtime realtime = new AblyRealtime(options); |
3 participants
WIP PR to add push notifications feature documentation for AIT.
Remaining work to do on this