[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

m-hulbert

This is looking good Umair, just a few comments for consistency and tidy up.

The comments on a few pages are applicable to them all (I think the first one I reviewed was Chat, so that has most)
Can we add a dedicated page for LiveSync and AIT for consistency?

m-hulbert · 2026-03-26T09:17:33Z

src/pages/docs/chat/pricing.mdx

+meta_keywords: "chat pricing, message counting, typing indicators, reactions, cost optimization"
+intro: "How Chat SDK features contribute to your message count and strategies to optimize costs."
+redirect_from:
+  - /docs/chat/message-billing


You don't need this as that page never existed.

m-hulbert · 2026-03-26T09:18:34Z

src/pages/docs/chat/pricing.mdx

+
+The [Chat SDK](/docs/chat) is built on top of [Pub/Sub](/docs/pub-sub). All Chat operations generate Pub/Sub messages that follow the same counting rules.
+
+<Aside data-type="further-reading">


I'd suggest putting this after the table on message counting and dropping the second sentence about package comparisons.

m-hulbert · 2026-03-26T09:25:04Z

src/pages/docs/chat/pricing.mdx

+## Rooms, channels, and connections <a id="rooms-connections"/>
+
+Each Chat room maps to underlying Pub/Sub channels. Each room feature (messages, typing, reactions, presence, occupancy) uses its own channel, contributing to your [channel count](/docs/platform/pricing#channels). Ably bills each connected client for [connection minutes](/docs/platform/pricing#connections) in the same way as Pub/Sub.


I think we should separate these out considering we charge for them independently. I also think it's worth having the explanations here rather than pushing people back to Pub/Sub to understand them.

m-hulbert · 2026-03-26T09:25:45Z

src/pages/docs/chat/pricing.mdx

+
+Increase the `heartbeatThrottleMs` [room option](/docs/chat/rooms#typing) to reduce typing indicator event frequency. The default is 10 seconds. Increase this value in rooms that tolerate delayed typing feedback.
+
+### Disable typing indicators


I'm not sure this needs to be stated, since they'd only be enabled if someone set them up.

m-hulbert · 2026-03-26T09:26:49Z

src/pages/docs/chat/pricing.mdx

+
+Each Chat room maps to underlying Pub/Sub channels. Each room feature (messages, typing, reactions, presence, occupancy) uses its own channel, contributing to your [channel count](/docs/platform/pricing#channels). Ably bills each connected client for [connection minutes](/docs/platform/pricing#connections) in the same way as Pub/Sub.
+
+## Cost optimization <a id="optimization"/>


Is it worth adding some quick info on detaching from rooms and closing connections?

m-hulbert · 2026-03-26T12:01:13Z

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

+<Aside data-type="further-reading">
+For package comparison and volume discounts, see the [pricing](https://ably.com/pricing) page. For general billing information, see [billing](/docs/platform/pricing/billing).
+</Aside>
+
+## How Ably counts messages <a id="how-messages-are-counted"/>


Can delete these I think. It's not best practice to redirect someone as soon as they land on a page.

m-hulbert · 2026-03-26T13:34:03Z

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

+| Token delivery | 1 outbound message per subscriber |
+| [Persistence](/docs/storage-history/storage) storage | 1 additional message per stored message |
+
+The total cost depends on the [token streaming pattern](/docs/ai-transport/token-streaming#token-streaming-patterns) you choose. With [message-per-response](/docs/ai-transport/token-streaming/message-per-response), [append rollup](/docs/ai-transport/token-streaming/token-rate-limits#per-response) conflates multiple tokens into fewer inbound messages. For example, 300 tokens published individually can be conflated to approximately 100 inbound messages. See the [AI support chatbot pricing example](/docs/platform/pricing/examples/ai-chatbot) for a full breakdown.


Is there anyway to distill this into the table (e.g. an entry for per token and for per response)?

Either way I don't think the pricing example is the appropriate place to link to for an explanation.

m-hulbert · 2026-03-26T13:35:59Z

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

+
+[Channels](/docs/channels) are the unit of message distribution. Each channel you use contributes to your [channel count](/docs/platform/pricing#channels). Ably bills [connection minutes](/docs/platform/pricing#connections) per minute of connection time for each connected client.
+
+## Cost optimization <a id="optimization"/>


I think we should keep this to the specific product pages like you've done as some of these are only applicable to 1 or 2 products.

m-hulbert · 2026-03-26T13:36:20Z

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

+meta_keywords: "message counting, pricing, persistence, presence, cost optimization, Pub/Sub pricing"
+intro: "How Pub/Sub operations contribute to your message count and strategies to optimize costs."
+redirect_from:
+  - /docs/pub-sub/message-billing


This didn't exist either.

m-hulbert · 2026-03-26T13:40:54Z

src/pages/docs/chat/pricing.mdx

+
+The following table shows how Chat operations contribute to your message count:
+
+| Operation | Messages counted |


I'd suggest something like this format, to make the tables more readable and have fewer repeated links:

| Operation | Messages counted | | --- | --- | | [Pub/Sub](/docs/pub-sub) || | Publish | 1 inbound message | | Message delivery | 1 outbound message per subscriber | | [Presence](/docs/presence-occupancy/presence) || | Presence enter | 1 inbound message | | Presence leave | 1 inbound message | | Presence update | 1 inbound message | | Presence event delivery | 1 outbound message per presence subscriber | | [Message persistence](/docs/storage-history/storage) || | Persistence storage | 1 additional message per stored message | | History retrieval | 1 message per retrieved message |

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 temporarily deployed to ably-docs-dx-883-messag-9cnjng March 12, 2026 08:30 Inactive

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

m-hulbert added the review-app Create a Heroku review app label Mar 24, 2026

m-hulbert deployed to ably-docs-dx-883-messag-lr3igz March 25, 2026 18:03 View deployment

m-hulbert reviewed Mar 26, 2026

View reviewed changes


		## 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"/>


		The [Chat SDK](/docs/chat) is built on top of [Pub/Sub](/docs/pub-sub). All Chat operations generate Pub/Sub messages that follow the same counting rules.

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

		## Rooms, channels, and connections <a id="rooms-connections"/>

		Each Chat room maps to underlying Pub/Sub channels. Each room feature (messages, typing, reactions, presence, occupancy) uses its own channel, contributing to your [channel count](/docs/platform/pricing#channels). Ably bills each connected client for [connection minutes](/docs/platform/pricing#connections) in the same way as Pub/Sub.


		Increase the `heartbeatThrottleMs` [room option](/docs/chat/rooms#typing) to reduce typing indicator event frequency. The default is 10 seconds. Increase this value in rooms that tolerate delayed typing feedback.

		### Disable typing indicators


		Each Chat room maps to underlying Pub/Sub channels. Each room feature (messages, typing, reactions, presence, occupancy) uses its own channel, contributing to your [channel count](/docs/platform/pricing#channels). Ably bills each connected client for [connection minutes](/docs/platform/pricing#connections) in the same way as Pub/Sub.

		## Cost optimization <a id="optimization"/>


		[Channels](/docs/channels) are the unit of message distribution. Each channel you use contributes to your [channel count](/docs/platform/pricing#channels). Ably bills [connection minutes](/docs/platform/pricing#connections) per minute of connection time for each connected client.

		## Cost optimization <a id="optimization"/>


		The following table shows how Chat operations contribute to your message count:

		\| Operation \| Messages counted \|

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!

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

coderabbitai bot commented Mar 2, 2026 •

edited

Loading