Ably
Ably is a real-time data streaming platform for building live applications. It provides pub/sub messaging,
presence tracking, push notifications to mobile/web devices, and usage analytics.
Data Model & Hierarchy
- Channel — A named message stream. Channels are created implicitly when first published to or subscribed on. Channel names are case-sensitive strings (e.g. 'chat:room-1', 'events:user-updates'). Namespace prefixes separated by ':' enable rule-based configuration.
- Message — A unit of data published to a channel. Has a name (event type), data (payload), timestamp, unique id, and optional clientId. Messages are ephemeral by default — persistence depends on channel rules.
- Presence — Tracks which clients are currently connected to a channel. Each presence member has a clientId, connectionId, and optional data payload. Presence history records enter/leave/update events over time.
- Push Device Registration — A mobile or web device registered to receive push notifications. Has id, platform (ios/android/browser), formFactor, push.recipient (transport-specific token), clientId, and metadata.
- Push Channel Subscription — Links a registered device (or all devices for a clientId) to a channel for push notification delivery. When a message is published to the channel, subscribed devices receive a push notification.
- Stats — Aggregated usage metrics across the application: messages published/received, connections, channels, API requests, push notifications, and data transferred. Available at minute/hour/day/month granularity.
- Token — A short-lived Ably credential issued from a long-lived API key. Tokens can be scoped to specific channels and operations, and optionally bound to a client ID. Used for client-side authentication where exposing the long-lived key is not acceptable.
Entity Relationships
App ─┬─ Channels (many, named streams)
│ ├─ Messages (per channel, time-ordered)
│ └─ Presence members (per channel, live set + history)
├─ Push Device Registrations (per app)
│ └─ Push Channel Subscriptions (device → channel)
└─ Stats (aggregated usage over time)
Key Workflows
- Channel discovery: List active channels → get metadata for a specific channel (occupancy, status).
- Messaging: Publish messages to a channel → retrieve message history with time-range filtering.
- Presence monitoring: Get current members on a channel → query presence history for enter/leave events.
- Push notification setup: Register a device → subscribe it to channels → send direct push or publish to channel.
- Push management: List subscriptions → unsubscribe devices → unregister devices.
- Usage monitoring: Get stats by minute/hour/day/month → analyze message volume, connections, API usage.
- Token management: Request scoped tokens for client-side apps — limit capabilities, set TTL, bind to client IDs.
Gotchas
- Channel names are IDs: The channel name string IS the identifier used everywhere — messages, presence, subscriptions, metadata lookups. There is no separate numeric ID.
- Namespace prefixes: Channel names use ':' as namespace separators (e.g. 'chat:room-1'). Namespace rules in the dashboard control persistence, encryption, and push behavior per prefix.
- Message persistence: Messages are NOT persisted by default. Only channels with persistence enabled (via channel rules) retain message history. Querying history on non-persisted channels returns empty.
- Presence vs push: Presence tracks who is currently connected via WebSocket/SSE. Push notifications go to registered mobile/web devices even when the user isn't connected. They serve different use cases.
- Push requires device registration: Before subscribing to push channels, the device must be registered via the device registrations endpoint with valid platform-specific transport details (APNs token, FCM token, or web push endpoint).
- Stats aggregation delay: Stats are aggregated asynchronously. Minute-level stats may have a few seconds of delay; hourly and daily stats update at interval boundaries.
- Time is in milliseconds: Both message timestamps and the server time endpoint return Unix epoch in milliseconds, not seconds.
