Chat guide: task-oriented chats #2892

vladvelici · 2025-10-16T11:10:31Z

Description

Chats linked to something else, like a meeting or call, delivery, document like google docs, or a support ticket. Typically small groups or 1:1.

https://ably.atlassian.net/browse/CHA-900

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 · 2025-10-16T11:10:43Z

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.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch task-oriented-chat

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.}

AndyTWF · 2025-10-24T10:03:58Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+![Ably Architecture Overview Diagram](../../../../images/content/diagrams/architecture-overview.png)
+
+Delivering chat messages in realtime is key to an engaging experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.


"engaging experience" I think is probably more fitting the livestream case - there are many cases of task-oriented chat where engagement in the enjoyment sense isn't really top-of-mind

"a smooth online experience"?

I imagine for support, deliveries, etc. the goal is to not frustrate further (assuming if everything is ok to start with people don't use the chat)

For games it can be a way of increasing engagement

src/pages/docs/guides/chat/build-task-oriented.mdx

AndyTWF · 2025-10-24T10:18:55Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+Each room includes all task participants: customers and agents in support, buyers and sellers in marketplaces, players in games, team members in projects. Participants can join and leave as the task evolves. Access to message history and other features can be granted to all or select participants via capabilities.
+
+### Pricing flexibility


Probably more of a @m-hulbert question - but do we want to be calling out billing dimensions explicitly in the guide because if they ever change we have to go and update everywhere?

I would avoid talking about pricing explicitly. We can add a link to the pricing price, or to the future chat-specific pricing documentation.

I won't talk about pricing here. Maybe a link to the pricing page.

src/pages/docs/guides/chat/build-task-oriented.mdx

AndyTWF · 2025-10-24T10:45:19Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+## Push notifications
+
+Ably Pub/Sub channels can be used for push notifications. See the [Push notifications](/docs/push/publish) documentation for more details. Since Ably Chat rooms are backed by a single Ably Pub/Sub channel, you can use the same channel for push notifications to notify all participants in the room when something happens.


We need to check the implications on mutable messages of using the same channel for push notifications

I've had a go with this and found it difficult to use actually:

chat channels require identified publishes so servers will have to set a clientId for sending push notifications

I found setting up push notifications to be very confusing and difficult to just reset and start over (I'm probably missing something here)

maybe we should just suggest to use another channel, or I can dig some more into this?

Regarding identified client, the web UI in the dashboard also fails to send notifications for chat channels, greeting users with this

Yeah the Web UI is a known issue that I've raised. Having to set a clientId for push notifications isn't the end of the world - but im thinking like will they be in the channel history etc

they show in history, but they show in history anyway if you have history enabled (not just on chat channel or mutable messages channel)

on mutable channels they can also be edited and deleted

Given that they show in history if you enable persistence, is this a problem?

src/pages/docs/guides/chat/build-task-oriented.mdx

david-hernandez-ably · 2025-10-30T10:40:09Z

src/pages/docs/guides/chat/build-task-oriented.mdx

@@ -0,0 +1,406 @@
+---
+title: "Guide: Building task-oriented chat experiences with Ably"


I find "1:1 or small group" chat experience more understandable than "task-oriented".

david-hernandez-ably · 2025-10-30T11:00:49Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+Delivering chat messages in realtime is key to a smooth online experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.
+
+Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable.


I would not talk about pricing in the guide.

We've done that in the livestream guide - and I think it does have a place here. But I think it should be limited to "consumption based helps if your app is like ABC, MAU helps if your app is like XYZ" - so much more of highlighting a decision point and showing how Ably works for you, rather than breaking down the pricing in detail.

david-hernandez-ably · 2025-10-30T11:12:26Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+Each room includes all task participants: customers and agents in support, buyers and sellers in marketplaces, players in games, team members in projects. Participants can join and leave as the task evolves. Access to message history and other features can be granted to all or select participants via capabilities.
+
+### Pricing flexibility


I would avoid talking about pricing explicitly. We can add a link to the pricing price, or to the future chat-specific pricing documentation.

david-hernandez-ably · 2025-10-30T11:25:17Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+Chat rooms scale horizontally. Ably allows you to have as many rooms as you need running in parallel.
+
+* **Proven at scale:** Ably delivers over 500 million messages per day for customers.
+* **Rate limiting:** Prevent spam and maintain conversation quality with global or per-user throttling appropriate for your use case.


Do we actually offer "per-user throttling"? Understanding user here as a clientId.

david-hernandez-ably · 2025-10-31T08:02:53Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+Each room includes all task participants: customers and agents in support, buyers and sellers in marketplaces, players in games, team members in projects. Participants can join and leave as the task evolves. Access to message history and other features can be granted to all or select participants via capabilities.
+
+### Pricing flexibility


I won't talk about pricing here. Maybe a link to the pricing page.

david-hernandez-ably · 2025-10-31T08:21:10Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+Ably's comprehensive platform enables you to combine chat with other realtime features to create rich, interactive task experiences.
+
+**Pub/Sub channels** add interactive elements:
+- **Live polls:** Quick feedback during collaborative decisions


Wouldn't be better using LiveObjects for Polls and other things, instead of a channel?

I think they're probably best via a message that gets annotations for votes, but I guess it depends.

As far as I know LO are good if the state you want to track is per-room/channel and you want to keep it synched. Topic, room reactions type of thing, pinned messages, etc.

For task-oriented it can be things like the actual listing in a marketplace can be a live object if it's something that gets updated live. Or if you do a live fundraiser and you count and show how many donated and total amount raised.

I guess the status updates/progress indicator it s good one in this list

david-hernandez-ably · 2025-10-31T08:22:51Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+     * **Hate speech and harassment:** Detecting discriminatory language, threats, or targeted abuse.
+     * **Discrimination:** Detecting discriminatory language, threats, or targeted abuse.
+     * **Inappropriate content:** Flagging adult content, violence, or graphic material.
+     * **Toxicity:** Measuring overall message sentiment and hostility


End sentence with "."

david-hernandez-ably · 2025-10-31T08:23:05Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+2. **Technical integration**
+   * **Latency impact:** AI moderation adds up to 100ms to message delivery.
+   * **Integration options:** Choose from pre-built integrations or connect your existing moderation systems via webhooks, serverless functions, or queues


End sentence with "."

david-hernandez-ably · 2025-10-31T08:30:23Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+Ably's [fault tolerance guide](/docs/platform/architecture/fault-tolerance) describes how we do this and that, even if an entire region
+goes down, it has little-to-no impact on the global service and your application.
+
+## Priced for task-oriented efficiency


Nice pricing explanation here.

Keep or drop?

If we want to avoid pricing info on this page, maybe it needs to go?

david-hernandez-ably · 2025-10-31T08:31:33Z

src/pages/docs/guides/chat/build-task-oriented.mdx

+
+### Aggressive connection management
+
+When a client abruptly disconnects from Ably, there is a 2 minute delay before the connection is cleaned up on the server, to enable the client to resume the connection from where it left off. When you're finished with an Ably connection, be sure to call the `close()` method to gracefully shut down the connection.


Maybe explain this is good for pricing, as there won't be opened connections forever.

added a line about this - mentioning to detach the room and drop connections

Co-authored-by: Andy Ford <[email protected]>

…inute pricing

vladvelici · 2025-11-07T13:46:10Z

Last things to decide:

Entirely drop pricing section or keep it? I've removed a few mentions of pricing but there was some duplication.
Push notifications thread
"Engaging experience" wording

cc @AndyTWF @david-hernandez-ably

vladvelici marked this pull request as draft October 16, 2025 11:10

AndyTWF added the review-app Create a Heroku review app label Oct 21, 2025

ably-ci temporarily deployed to ably-docs-task-oriented-ohslsf October 21, 2025 08:40 Inactive

AndyTWF reviewed Oct 24, 2025

View reviewed changes

vladvelici force-pushed the task-oriented-chat branch from a25e7bc to 6e2d614 Compare October 29, 2025 10:00

vladvelici requested a review from AndyTWF October 29, 2025 10:00

vladvelici changed the title ~~Chat guide: task-oriented chats draft~~ Chat guide: task-oriented chats Oct 29, 2025

vladvelici marked this pull request as ready for review October 29, 2025 10:05

david-hernandez-ably reviewed Oct 31, 2025

View reviewed changes

vladvelici and others added 9 commits November 7, 2025 12:14

task oriented chat draft

4505948

Update src/pages/docs/guides/chat/build-task-oriented.mdx

b489c49

Co-authored-by: Andy Ford <[email protected]>

one round of fixes based on comments

6a10c15

livestream chat doc: typos and small fixes

06fe800

task-oriented chat: add ai section and more small fixes

bf0d8eb

task-oriented chat: add per connect in chargeable items list in per-m…

cb24d9a

…inute pricing

task-oriented chat: change wording on push notifications

f0a0732

remove one of the pricing sections

9357624

fixes based on reivew comments

fcb7b39

vladvelici force-pushed the task-oriented-chat branch from 6e2d614 to fcb7b39 Compare November 7, 2025 13:40

vladvelici requested a review from david-hernandez-ably November 7, 2025 13:40

vladvelici added 2 commits November 7, 2025 13:41

ably queue bullet point

5d4b571

close connections and detach for pricing paragraph

c632b45


		![Ably Architecture Overview Diagram](../../../../images/content/diagrams/architecture-overview.png)

		Delivering chat messages in realtime is key to an engaging experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.


		Each room includes all task participants: customers and agents in support, buyers and sellers in marketplaces, players in games, team members in projects. Participants can join and leave as the task evolves. Access to message history and other features can be granted to all or select participants via capabilities.

		### Pricing flexibility


		## Push notifications

		Ably Pub/Sub channels can be used for push notifications. See the [Push notifications](/docs/push/publish) documentation for more details. Since Ably Chat rooms are backed by a single Ably Pub/Sub channel, you can use the same channel for push notifications to notify all participants in the room when something happens.

		@@ -0,0 +1,406 @@
		---
		title: "Guide: Building task-oriented chat experiences with Ably"


		Delivering chat messages in realtime is key to a smooth online experience. Ably's [serverless architecture](/docs/platform/architecture) eliminates the need for you to manage websocket servers. It automatically scales to handle millions of concurrent connections without provisioning or maintenance. Ably also handles all of the edge-cases around delivery, failover and scaling.

		Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable.


		### Aggressive connection management

		When a client abruptly disconnects from Ably, there is a 2 minute delay before the connection is cleaned up on the server, to enable the client to resume the connection from where it left off. When you're finished with an Ably connection, be sure to call the `close()` method to gracefully shut down the connection.

Chat guide: task-oriented chats #2892

Are you sure you want to change the base?

Chat guide: task-oriented chats #2892

Uh oh!

Conversation

vladvelici commented Oct 16, 2025

Description

Checklist

Uh oh!

coderabbitai bot commented Oct 16, 2025

Review skipped

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

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!

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!

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!

vladvelici commented Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

5 participants

vladvelici commented Nov 7, 2025 •

edited

Loading