Skip to content

Conversation

@vladvelici
Copy link
Contributor

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

@coderabbitai
Copy link

coderabbitai bot commented Oct 16, 2025

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.

@vladvelici vladvelici marked this pull request as draft October 16, 2025 11:10
@AndyTWF AndyTWF added the review-app Create a Heroku review app label Oct 21, 2025
@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-ohslsf October 21, 2025 08:40 Inactive

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • 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?

@vladvelici vladvelici requested a review from AndyTWF October 29, 2025 10:00
@vladvelici vladvelici changed the title Chat guide: task-oriented chats draft Chat guide: task-oriented chats Oct 29, 2025
@vladvelici vladvelici marked this pull request as ready for review October 29, 2025 10:05
@@ -0,0 +1,406 @@
---
title: "Guide: Building task-oriented chat experiences with Ably"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would not talk about pricing in the guide.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't, no - it doesn't mean that it's not possible but requires extra work on your part.


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* **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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

End sentence with "."


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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

End sentence with "."

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice pricing explanation here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keep or drop?

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


### 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@vladvelici
Copy link
Contributor Author

vladvelici commented Nov 7, 2025

Last things to decide:

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

cc @AndyTWF @david-hernandez-ably

@AndyTWF
Copy link
Contributor

AndyTWF commented Nov 10, 2025

Last things to decide:

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

cc @AndyTWF @david-hernandez-ably

  1. I think we need to talk about how Ably's pricing works for you calling out the key wins, but just avoiding detailed breakdown.
  2. It's not currently possible to send push notifications via Chat directly (as you can't set the extras payload without Pub/Sub), so we should decide whether we tell people about how to send PN's via a correctly-formatted pubsub message on the chat channel, or as a message on a separate channel / direct publish.
  3. Suggestion works for me.

@vladvelici
Copy link
Contributor Author

@AndyTWF @david-hernandez-ably I've updated pricing and push notifications sections. Let me know what you think :)

@AndyTWF AndyTWF added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Nov 12, 2025
@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-xb6mkg November 12, 2025 10:49 Inactive
---
title: "Guide: Building task-oriented chat experiences with Ably"
meta_description: "Architecting task-oriented chat with Ably for 1:1 and small group conversations linked to specific tasks. Performance, reliability, and cost optimization for support tickets, deliveries, gaming sessions, and more."
meta_keywords: "task-oriented chat, 1:1 chat, small group chat, realtime messaging, support tickets, delivery tracking, gaming chat, Ably Chat, chat SDK, dependability, cost optimisation"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth adding use-case here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean literally the keyword use-case? Can add. To livestream too maybe?


Ably Chat is purpose-built for task-oriented chat experiences, from 1:1 conversations to small group interactions that enhance specific activities and workflows.

> If you need to deliver seamless, contextual chat experiences that enhance tasks like support tickets, deliveries, gaming sessions, collaborative work, or transactional processes, without sacrificing performance, reliability, or costs, then Ably is the proven choice.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're going to make this an explicit indent here, can we do the same for the livestream guide which has a similar paragraph

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That said, this indent doesn't appear to make a difference in the review app?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed it

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't, no - it doesn't mean that it's not possible but requires extra work on your part.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per-attachment rate limits aren't helpful for Chat in many scenarios because we publish via REST.


In task-oriented chat, each room is typically low throughput. Scaling comes by running as many rooms as you need at the same time. Ably handles everything from 1:1 conversations and small group discussions to [livestream chats](/docs/guides/chat/build-livestream) with the same reliability and scalability guarantees.

Chat rooms scale horizontally. Ably allows you to have as many rooms as you need running in parallel.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section needs to come across more as "here are some things you need to think about" rather than suggesting we have solutions right now for them (attachment rate limits aren't really helpful and the global limits aren't really the right fit).

If you look at the livestreaming guide, we've framed it more as a discussion of things you need to think about and decisions you need to make.

I guess it raises the question - is throughput / rate management the best fit for these types of chats?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've spent some time thinking of this section and in what situations it would make sense.

A potential source of spam would be bots opening many rooms. Can be mitigated with a form+captcha or similar before actually creating the task+room. I feel this is a bit out of scope though, so I'm removing the whole section. It was forced.

This contextual presence information helps participants understand not just who's online, but who's ready and able to engage with the current task.

```javascript
// subscribe to presence events
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this need an attach call after it to make the example complete?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added attach calls in examples where it makes sense


## Message history: essential task context <a id="history"/>

Message history is crucial for task-oriented chats, ensuring continuity and context even when participants join mid-task or return after interruptions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth a link somewhere in here to the BYOD guide (when it arrives) as I think audit is key for many of these use-cases


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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the wording here be "allow you to build interactive..." so we don't imply these features are out of the box?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


Ably's flexible moderation system adapts to your task requirements:

* **Per-room policies:** Different moderation rules for different task types or user roles.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's not currently a way to specify "User X is allowed to swear" except where the platform allows is (Hive Dashboard might be the only one)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changed to for different rooms.

```
</Code>

## AI Integrations
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to go deeper here and talk about AI customer service etc?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems to diverge from the main topic a bit?

Not quite sure what to cover either if to add. I can think of:

  1. describe a scenario where user creates new chat -> ends up with bot -> later gets moved to human
  2. talk about other features and AI: typing indicators, status via presence
  3. not the space to recommend anything for LLM streaming or MCP stuff; we can mention when we have other content

@vladvelici vladvelici requested a review from AndyTWF November 18, 2025 09:51
@AndyTWF AndyTWF added review-app Create a Heroku review app and removed review-app Create a Heroku review app labels Nov 21, 2025
@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-sl31zl November 21, 2025 11:57 Inactive
link: '/docs/guides/chat/build-livestream',
},
{
name: 'Task-oriented chat',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're going with the guide being titled around small-group, does this need to change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changed already

@@ -0,0 +1,408 @@
---
title: "Guide: Building small group chat experiences with Ably"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The title now doesn't quite add up with the focus of the guide - it comes across as being generic group chats, but then we launch straight into task-oriented?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

renamed to embedded chats

- Do you need any spam prevention measures applied before allowing users to join rooms?
- For example, in a support chat scenario, use a captcha or other measures before allowing users to join a room or create a new ticket.
- Do you need long-term archiving of the chat history?
- Check out the guide for [exporting chat data](/docs/guides/chat/export-chat) for an overview of your options. !!!TODO remove this if export chat not merged!!!
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aware of this TODO, just noting it so we don't forget

```
</Code>

You can use our [React UI Kit](/docs/chat/react-ui-kit) to easily create a [fully featured chat window](/docs/chat/getting-started/react-ui-kit#chat-window) that handles subscribing to messages, loading history, message updates and deletes, message reactions, and more. See the [React UI Kit](/docs/chat/react-ui-kit) for more details.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think UI kits should have their own section (in fact, I think they should on the livestream guide too). This is a major selling point for chat use-cases

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added short section, just in this one for now


Ably's comprehensive platform enables you to combine chat with other realtime features to create rich, interactive task experiences.

**Pub/Sub channels** enable you to build rich, interactive task experiences:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


Closing connections as well as detaching from rooms when no longer needed is important to ensure that you are not charged for unused resources.

## Push notifications
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would move this above room reactions - much more closely aligned with this use case

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

moved above room reactions and above AI, I think before you add AI you might want to have a way to get people re-engaged


* **Explore Ably Chat:** Dive into the [Ably Chat documentation](/docs/chat) for comprehensive API details and advanced features.
* **Try the examples:** Play around with [chat examples](/examples?product=chat) to see real implementations.
* **Get started quickly:** Follow the [JavaScript/TypeScript](/docs/chat/getting-started/javascript) or [React](/docs/chat/getting-started/react) getting started guides.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Call out UI kits

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done, and mobile SDKs too

@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-sl31zl November 21, 2025 12:45 Inactive
@vladvelici vladvelici force-pushed the task-oriented-chat branch 2 times, most recently from 8e2594c to 40d6922 Compare November 24, 2025 06:16
@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-sl31zl November 24, 2025 06:16 Inactive
@ably-ci ably-ci temporarily deployed to ably-docs-task-oriented-sl31zl November 27, 2025 17:11 Inactive
Copy link
Contributor

@AndyTWF AndyTWF left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Happy from my side once deved have approved :)


The most important decision when developing embedded chat applications is the experience you want users to have within their specific context. This will determine how chat integrates with your task flow and ultimately how effectively it enhances the user experience.

Ably has been tested to handle millions of concurrent connections and rooms. Whether you're managing 100 support conversations or 100,000 simultaneous delivery chats, the architecture remains the same - no re-engineering required as you grow.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think move this to the end of the section - as it's a nice sum-up of key USPs after the bullet points

@ably-ci ably-ci had a problem deploying to ably-docs-task-oriented-sl31zl December 1, 2025 09:52 Failure
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review-app Create a Heroku review app

Development

Successfully merging this pull request may close these issues.

5 participants