Skip to content

Chat guide: task-oriented chats#2892

Open
vladvelici wants to merge 16 commits into
mainfrom
task-oriented-chat
Open

Chat guide: task-oriented chats#2892
vladvelici wants to merge 16 commits into
mainfrom
task-oriented-chat

Conversation

@vladvelici
Copy link
Copy Markdown
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
Copy Markdown

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
Comment thread src/pages/docs/guides/chat/build-task-oriented.mdx Outdated
Comment thread src/pages/docs/guides/chat/build-task-oriented.mdx Outdated
Comment thread src/pages/docs/guides/chat/build-task-oriented.mdx Outdated

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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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.

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

## 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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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?

Comment thread src/pages/docs/guides/chat/build-task-oriented.mdx Outdated
@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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Comment thread src/data/nav/chat.ts Outdated
link: '/docs/guides/chat/build-livestream',
},
{
name: 'Task-oriented chat',
Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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

Comment thread src/pages/docs/guides/chat/build-small-group.mdx Outdated
- 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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copy link
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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
Copy Markdown
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 24, 2025 06:24 Inactive
@vladvelici vladvelici requested review from a team and AndyTWF November 24, 2025 12:06
Copy link
Copy Markdown
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.

Just some opportunities to really hit home on the scale front and I think we'll be there :)

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

Choose a reason for hiding this comment

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

This 404's for me, but presume that's because we need to rebase.


Despite the challenges of delivering these guarantees, Ably is designed to keep costs predictable. You can choose between MAU-based (more predictable for a known number of users) or per-minute pricing (consumption-based, pay for what you use), depending on your needs. Both pricing models are designed to be cost-effective and scalable. Features such as efficient connection management are available to help you reduce costs.

## Architecting your chat: UX first, scale always
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could we use a subset of UI kit components to do a quick mockup or two of what a chat could look like? A visual here might help to get the point across.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

If we want some visual for this should I ask design if they're happy to make a mockup instead? I can spend the time to mess with the UI Kit and CSS and make something, it might look sort of acceptable but not the kind of graphic we'd want in the header of a guide?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Added in-game chat example screenshot at the top of the article.


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

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

Choose a reason for hiding this comment

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

I think we could drive home some hard numbers in this section to really hit the scale part, I'm thinking:

  • 2B devices every month
  • 600B message every month
  • 6.5s message delivery latency

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

e.g.

"Ably routinely handles 600 billion messages every month globally, across 2 billion devices with median delivery latencies under 6.5ms even during peak traffic."

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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


## Architecting your chat: UX first, scale always

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

Choose a reason for hiding this comment

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

In our section heading we promise scale, but don't then deliver on it with hard numbers. Perhaps we can add something like this to bring scale back to the front (perhaps as a summing-up sentence at the end)?

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
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

added, thanks!

Authentication is best achieved using JSON Web Tokens (JWTs). These are tied to a particular `clientId` and come with a set of [capabilities](/docs/chat/setup#authentication) that control what a client can and cannot do - for example whether they can send messages, join a certain room or moderate. Ably's SDKs handle the timing and process of requesting a new token for you, refreshing it when it expires. All you need to do is provide a server-side endpoint that can generate the JWT for the client. This enables clients to use your existing authentication systems or user sessions to generate their Ably token.

## Presence: Know who's available in the room

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Opportunity to call out scale here, e.g.

Using server-side batching (link), Ably effortlessly handles thousands of presence participants per room without impacting performance.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

added, thanks!

Copy link
Copy Markdown
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
Copy Markdown
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 temporarily deployed to ably-docs-task-oriented-sl31zl December 1, 2025 09:52 Inactive
Copy link
Copy Markdown
Contributor

@m-hulbert m-hulbert left a comment

Choose a reason for hiding this comment

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

Thanks for this Vlad - I think the info in here is really good.

Where I think we need to pivot though, is revisiting why this is a single guide. I think we're struggling on terminology between 'embedded' and 'contextual chat' and that's diluting from giving strong opinions on problems/solutions that I've raised throughout.

Even if there's a certain level of duplication between the 2 guides, I'd like us to consider whether it would make the messaging clearer. Both of these can be embedded, sure. But 1:1 is likely to be the main focus of importance to a user, whereas a small group chat is sort of ancilliary to whatever it's being embedded into in most cases.

@@ -0,0 +1,414 @@
---
title: "Guide: Building embedded chat experiences with Ably"
meta_description: "Architecting embedded, contextual chat with Ably for 1:1 and small group conversations linked to a specific context. Performance, reliability, and cost optimization for support tickets, deliveries, gaming sessions, and more."
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We're using "contextual chat" throughout this guide, and I just wonder if that's the right term. I think with the rise of LLMs it means something quite different to what we're intending to get across here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

i've changed it to be "embedded chats" everywhere


Ably Chat is purpose-built for all types of 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
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'd suggest listing these out as bullet points to break up the text and make the use cases more visible. Also, "support tickets" makes it sound more CRM-based whereas I think you're intending to mean 1:1 support agent : customer chats, right?

Copy link
Copy Markdown
Contributor Author

@vladvelici vladvelici Dec 19, 2025

Choose a reason for hiding this comment

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

changed to "support chats", but now it's mentioned a lot less


Building with Ably means that you no longer need to worry about managing websocket servers, handling failover, network disruptions, or keeping latency low. Ably handles all of this for you, leaving you free to focus on creating engaging experiences.

This guide explains the architectural decisions, technical challenges, and unique benefits of building embedded or contextual chat experiences with Ably, focusing on 1:1 and small group chats. It will help you design contextual, efficient chat solutions for scenarios like customer support, delivery tracking, gaming sessions, collaborative work, marketplace transactions, and more - all with performance, user experience, and cost optimization in mind.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I don't think you need to re-list all the use cases here as you've done so above.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

changed the intro to have less repetition


This guide explains the architectural decisions, technical challenges, and unique benefits of building embedded or contextual chat experiences with Ably, focusing on 1:1 and small group chats. It will help you design contextual, efficient chat solutions for scenarios like customer support, delivery tracking, gaming sessions, collaborative work, marketplace transactions, and more - all with performance, user experience, and cost optimization in mind.

**What are embedded or contextual chats?** Any chat that serves as a companion to a specific activity or workflow: resolving a support ticket, coordinating a delivery, discussing a chess game, collaborating on a project, or facilitating a marketplace transaction. They can be 1:1 or group conversations.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

As above. It feels a little bit like we're repeating the same thing 3 times. I'd also hope we'd be in a position with terminology that we don't need to explain what it is.


**What are embedded or contextual chats?** Any chat that serves as a companion to a specific activity or workflow: resolving a support ticket, coordinating a delivery, discussing a chess game, collaborating on a project, or facilitating a marketplace transaction. They can be 1:1 or group conversations.

## Why Ably for embedded chats?
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Not to belabour the point (sorry), but we're switching between "contextual and embedded chats" to just "embedded chats" here, so I think we need to really nail the terminology throughout.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

went with embedded everywhere


Read more about push notifications with Ably in the [Push notifications](/docs/push/publish) documentation, and about [integrations](/docs/platform/integrations) for more details.

## AI Integrations
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We've dropped the titles revolving around problem spaces again here, but I also feel this section could be a lot more targeted and include some code examples were these guides separate. E.g. sentiment analysis isn't something you'd use in 1:1 scenarios.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Sentiment analysis even in 1:1 is useful but not in the sense that one of the participants sees it. It's useful for monitoring at scale: "our users are happy", or "our users are frustrated when [feature X] is mentioned".

Since this is embedded chat companies might be able to find correlations between certain sentiments and out-of-chat events, like something happening in a game, frames being dropped in a call, bugs, or when a delivery is delayed beyond a certain threshold.


For example, you could set up an integration that sends all messages from each chat room to an AI service for sentiment analysis, which then automatically flags detected negative customer sentiments for review, to ensure they are handled appropriately, which could increase overall customer satisfaction. Or route messages to a language model to generate contextual responses to common questions, or to pull relevant information for your agent to increase their effectiveness in handling support queries.

## Room reactions
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Where is this useful? 1:1s wouldn't use it, and it isn't something you often see in small group chats as a feature.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This is for embedded chats, so things like in-game reactions and they're common during calls (think zoom chat).

```
</Code>

## Handling network disruption
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should this form part of a section that includes history - so it's context and positional relevance combined. Just because we handle those things differently in a technical manner, to a customer it's all about ensuring users receive their messages essentially.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I see the connection between the two. I moved them next to each other like in the livestream chat guide and kept the content of both unchanged. wdyt?


If you have participants that engage consistently, for example teams collaborating regularly on tasks or gaming communities that maintain ongoing sessions, Ably also offers a competitive MAU pricing model in addition to the traditional consumption-based model for these scenarios.

A full breakdown of Ably's pricing can be found on the [pricing page](/pricing).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Links to ably.com need to be fully qualified.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

done


A full breakdown of Ably's pricing can be found on the [pricing page](/pricing).

### Aggressive connection management
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is this something you'd want to do in a 1:1 or even small group chat use case? Aggressively closing connections in support chats seems really poor UX for example.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Initially I thought I'd just drop this section, but now I think it still has value. Imagine a game. Not chess or board games, but a multiplayer game where you're a character and move around. Let's say depending on where you are you join and exit different chat rooms (perfect use case for Ably Chat) where you chat with the people that are nearby in the game. Each in-game location has a chat room, and players join and leave (attach and detach) as they move around.

Even if each room is small the whole system is big, so it's important to be careful about attachments and detachments for billing, as there will be many rooms and you don't want to keep them active for longer than they need to be or pay for messages people won't see.

I'll change the title to "Efficient connection and attachment management". If I'm looking at this wrong way, I'm happy to drop the section instead.

@vladvelici vladvelici requested a review from m-hulbert December 19, 2025 13:15
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