[DX-883] Addresses message billing docs gap by umair-ably · Pull Request #3234 · ably/docs

umair-ably · 2026-03-02T09:47:47Z

Description

Addresses message billing docs gap as per llm-eval docs audit

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-03-02T09:47:55Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 04944b08-0eb1-4f34-8fb7-cca5eaefb762

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch DX-883-message-billing

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

umair-ably · 2026-03-02T13:37:39Z

@m-hulbert couple of questions for this one:

Do we think a separate page for message billing is appropriate when we already have a billing page at the same menu level?
We touch on both Chat and Pub/Sub... do we think that justifies breaking this up into dedicated pages for each product? (My thoughts were not which is why I didn't do it - seems right to leave all the pricing in 1 section imo, but happy to change if you feel that's the right thing to do)

AndyTWF · 2026-03-02T16:22:42Z

src/pages/docs/platform/pricing/message-billing.mdx

+Every message sent through Ably is counted for both publishing and delivery:
+
+* 1 publish = 1 inbound message
+* Each subscriber delivery = 1 outbound message per subscriber


+1 for each delivery to integrations (also applies to messages from log/stats metachannels)

AndyTWF · 2026-03-02T16:33:12Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+## Message size <a id="message-size"/>
+
+Message size is calculated as the sum of the `name`, `clientId`, `data`, and `extras` [properties](/docs/api/realtime-sdk/messages#properties) before any compression or expansion occurs in the serialization process.


LiveObjects and Annotations have different schemes

AndyTWF · 2026-03-02T16:33:59Z

src/pages/docs/platform/pricing/message-billing.mdx

+| --- | --- | --- |
+| Publish to channel | 1 inbound + 1 per subscriber outbound | Base cost for all messaging |
+| Persisted message storage | +1 per message stored | Enable via [channel rules](/docs/storage-history/storage) |
+| History retrieval | +1 per message retrieved | Each call to the [history API](/docs/storage-history/history) |


The wording on the last column may introduce confusion

AndyTWF · 2026-03-02T16:34:32Z

src/pages/docs/platform/pricing/message-billing.mdx

+| Persisted message storage | +1 per message stored | Enable via [channel rules](/docs/storage-history/storage) |
+| History retrieval | +1 per message retrieved | Each call to the [history API](/docs/storage-history/history) |
+| Presence enter/leave/update | 1 inbound + 1 per presence subscriber outbound | Same counting as regular messages |
+| Typing indicator heartbeat | 1 inbound + 1 per room member outbound | Controlled by `heartbeatThrottleMs` |


It feels weird to randomly throw in a Chat principle amid general platform pricing. Should there be a dedicated page for Chat pricing?

AndyTWF · 2026-03-02T16:35:24Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+Retrieving persisted messages via the [history API](/docs/storage-history/history) also counts: each message returned in a history response = 1 additional message.
+
+To avoid persistence costs on messages that don't need history, mark them as [ephemeral](/docs/pub-sub/advanced#ephemeral).


But also don't need rewind, integrations and other functions - it's not just history

AndyTWF · 2026-03-02T16:35:58Z

src/pages/docs/platform/pricing/message-billing.mdx

+* Subscribe to presence updates only on channels where you need member-level detail.
+
+## Chat-specific billing <a id="chat"/>
+


Worth a chat-specific page?

AndyTWF · 2026-03-02T16:36:21Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+Each chat message published to a room = 1 inbound + 1 per subscriber outbound.
+
+Each typing indicator heartbeat event = 1 inbound + 1 per subscriber outbound. At the default 10-second heartbeat, one active typer generates approximately six events per minute. In a room with 50 subscribers, this is approximately **306 messages per minute** per active typer.


+1 for explicit stop

AndyTWF · 2026-03-04T15:11:20Z

src/data/nav/chat.ts

      ],
    },
+    {
+      name: 'Message billing',


Is this the right level for this particular page, it feels a bit odd sitting here but maybe that's just me.

@m-hulbert WDYT?

m-hulbert · 2026-03-11T08:54:55Z

I think my view on this is that we should have a page that covers all products (i.e. every operation that counts as a message) under the pricing section in Platform. Then from that we can create dedicated 'Pricing' pages under each product that cover 'what counts as a message' as well as a recap on channel and connection minutes (e.g. note that channels = rooms) and a section on cost optimisation for each product there.

…ific pricing pages

m-hulbert

This is moving in the right direction Umair - just a few things to tidy up in terms of organisation and we're also only covering Pub/Sub and Chat in both places and not the other products?

This also seems quite dated, but we should make sure it's covered: https://faqs.ably.com/how-does-ably-count-messages

m-hulbert · 2026-03-12T08:48:16Z

src/data/nav/chat.ts

      ],
    },
+    {
+      name: 'Pricing',


I think it wouldn't hurt to prefix these with the product name in the nav, so "Chat pricing".

m-hulbert · 2026-03-12T08:48:35Z

src/data/nav/platform.ts

        },
+        {
+          link: '/docs/platform/pricing/message-billing',
+          name: 'Message billing',


Suggested change

name: 'Message billing',

name: 'Message counting',

m-hulbert · 2026-03-12T08:48:49Z

src/pages/docs/platform/pricing/message-billing.mdx

@@ -0,0 +1,111 @@
+---
+title: "Message billing"


Suggested change

title: "Message billing"

title: "Message counting"

m-hulbert · 2026-03-12T08:49:08Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+All Ably products count messages for billing purposes. The following sections explain how operations across Pub/Sub, Chat, LiveObjects, and Annotations contribute to your message count.
+
+<Aside data-type="further-reading">


I'd delete this, as we're redirecting people as soon as they land on the page.

m-hulbert · 2026-03-12T08:50:14Z

src/pages/docs/platform/pricing/message-billing.mdx

+intro: "How operations across all Ably products contribute to your message count."
+---
+
+All Ably products count messages for billing purposes. The following sections explain how operations across Pub/Sub, Chat, LiveObjects, and Annotations contribute to your message count.


I think we should reword this around messages are a unit of consumption that we charge for and it's important to understand which operations count as messages.

m-hulbert · 2026-03-12T08:58:10Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+For Chat-specific cost optimization strategies, see [Chat pricing](/docs/chat/pricing).
+
+## LiveObjects operations <a id="liveobjects-operations"/>


We should keep the table format going throughout for consistency.

m-hulbert · 2026-03-12T08:59:09Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+| Operation | Messages counted | Notes |
+| --- | --- | --- |
+| Chat message | 1 inbound + 1 per subscriber outbound | Same as a standard publish |


I think we need to cover every possible operation on this page - e.g. edits/updates/deletes, moderation etc.

m-hulbert · 2026-03-12T08:59:44Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+## Annotations <a id="annotations"/>
+
+[Annotations](/docs/messages/annotations) have a different billing scheme from standard messages. See the [Annotations](/docs/messages/annotations) page for details on how annotation operations are counted.


I'm not sure why annotations are at the product level, nor why we're saying they are charged differently and linking to the annotations page which doesn't cover costs.

m-hulbert · 2026-03-12T09:00:39Z

src/pages/docs/platform/pricing/message-billing.mdx

+
+[Annotations](/docs/messages/annotations) have a different billing scheme from standard messages. See the [Annotations](/docs/messages/annotations) page for details on how annotation operations are counted.
+
+## Persistence billing <a id="persistence"/>


These 2 sections should be covered in the tables really. I think we should review whether we need to have them dealt with separately. Reducing costs is something we should be handling on individual product pages.

m-hulbert · 2026-03-12T09:06:49Z

src/pages/docs/pub-sub/pricing.mdx

@@ -0,0 +1,41 @@
+---


For these types of pages I think we should be able to lift and shift the product table from the 'main' page for how we count messages (integrations we may have to think about as it'll probably be a separate table... maybe link to that one?)

We should then have a section for channels (or rooms etc.) and connections that just states how they are charged. This will obviously be very light for Pub/Sub and connections in general, but the info already exists in the pricing page. For other products like Chat we obviously need to state that a channel = a room for billing purposes.

For the cost optimisation I really like this idea to include it, but would recommend that we have a short paragraph per item that briefly describes it and links out (rather than the table format), and would also say in this instance that we're missing the presence optimisations that you've initially covered on the main page (which occupancy would fall under as 1 option).

…perations

…mization strategies

umair-ably changed the title ~~Addresses message billing docs gap~~ [DX-883] Addresses message billing docs gap Mar 2, 2026

umair-ably force-pushed the DX-883-message-billing branch from e85cf45 to de53456 Compare March 2, 2026 13:37

umair-ably marked this pull request as ready for review March 2, 2026 13:37

umair-ably requested review from AndyTWF, GregHolmes and m-hulbert March 2, 2026 13:38

AndyTWF reviewed Mar 2, 2026

View reviewed changes

umair-ably requested a review from AndyTWF March 3, 2026 12:20

AndyTWF reviewed Mar 4, 2026

View reviewed changes

umair-ably added 3 commits March 11, 2026 17:19

Addresses message billing docs gap

4a0cdaa

separates Chat and pubsub billing concerns

8740f05

Centralise message billing into platform pricing and add product-spec…

5e125be

…ific pricing pages

umair-ably force-pushed the DX-883-message-billing branch from 031b0df to 5e125be Compare March 11, 2026 17:19

m-hulbert deployed to ably-docs-dx-883-messag-9cnjng March 12, 2026 08:30 View deployment

m-hulbert reviewed Mar 12, 2026

View reviewed changes

umair-ably added 4 commits March 12, 2026 11:54

Expand central message-counting page with all products and detailed o…

5e025c1

…perations

Add product-specific pricing pages for Spaces and LiveObjects

a3095e9

Expand Chat and Pub/Sub pricing pages with operations tables and opti…

77a4251

…mization strategies

Update navigation to include product pricing pages

3119aa2

umair-ably requested a review from m-hulbert March 12, 2026 12:07


		## Message size <a id="message-size"/>

		Message size is calculated as the sum of the `name`, `clientId`, `data`, and `extras` [properties](/docs/api/realtime-sdk/messages#properties) before any compression or expansion occurs in the serialization process.


		Retrieving persisted messages via the [history API](/docs/storage-history/history) also counts: each message returned in a history response = 1 additional message.

		To avoid persistence costs on messages that don't need history, mark them as [ephemeral](/docs/pub-sub/advanced#ephemeral).

		* Subscribe to presence updates only on channels where you need member-level detail.

		## Chat-specific billing <a id="chat"/>


		Each chat message published to a room = 1 inbound + 1 per subscriber outbound.

		Each typing indicator heartbeat event = 1 inbound + 1 per subscriber outbound. At the default 10-second heartbeat, one active typer generates approximately six events per minute. In a room with 50 subscribers, this is approximately 306 messages per minute per active typer.


		All Ably products count messages for billing purposes. The following sections explain how operations across Pub/Sub, Chat, LiveObjects, and Annotations contribute to your message count.

		<Aside data-type="further-reading">


		For Chat-specific cost optimization strategies, see [Chat pricing](/docs/chat/pricing).

		## LiveObjects operations <a id="liveobjects-operations"/>


		## Annotations <a id="annotations"/>

		[Annotations](/docs/messages/annotations) have a different billing scheme from standard messages. See the [Annotations](/docs/messages/annotations) page for details on how annotation operations are counted.


		[Annotations](/docs/messages/annotations) have a different billing scheme from standard messages. See the [Annotations](/docs/messages/annotations) page for details on how annotation operations are counted.

		## Persistence billing <a id="persistence"/>

Conversation

umair-ably commented Mar 2, 2026

Description

Checklist

Uh oh!

coderabbitai bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

umair-ably commented Mar 2, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

m-hulbert commented Mar 11, 2026

Uh oh!

m-hulbert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

coderabbitai bot commented Mar 2, 2026 •

edited

Loading