Quill channel pages + dashboard channels-view page - #2646
Conversation
…l page at quill/channels/telegram-bot RDoc-4058 - create a /quill/dashboard/channels-view page, interlink it with the telegram bot page
828acad to
b9836f5
Compare
| # Channels: Overview | ||
| <Admonition type="note" title=""> | ||
|
|
||
| * A [channel](../overview.mdx#channels) carries the conversations between your users and an [agent](../overview.mdx#ai-agent) |
There was a problem hiding this comment.
Unneeded reference back for the channel that can encourage a reader to click away from the page.
Similar for the agent. I'd remove all the links from the first paragraph
There was a problem hiding this comment.
removed the link from channel, you're right about sending the reader off and the term is explained here in any case.
agent is another story, it's not explained here or anywhere on the page.
| Quill offers four channel types: a chat widget on your site, or a bot on Telegram, Slack, or Discord, reaching your users where | ||
| they already are. | ||
|
|
||
| * Each channel type has an article of its own, describing how a channel of this type is added and what its users meet. |
There was a problem hiding this comment.
what its users meet? I don't understand this phrase. What does it mean? Whose users? Channel's?
There was a problem hiding this comment.
-->
Each channel type has an article of its own, describing how a channel of this type is added, and what the channel's users encounter.
| A channel's type is selected in the **Add channel** menu, described in [Adding and managing channels](#adding-and-managing-channels): | ||
|
|
||
| * **Web widget** | ||
| A [chat widget](../overview.mdx#chat-widget) embedded in a page of your site, which your users open through an |
There was a problem hiding this comment.
Why is this the one that has no page on its own?
There was a problem hiding this comment.
there's an "Adding a chat widget" article in the getting started section, so writing a dedicated chat-widget article in the channels folder has a lower priority now than adding articles in other subjects. it will get its own channels article soon too.
There was a problem hiding this comment.
If it is eventually provided, 👍
|
|
||
| <Panel heading="Behavior and limitations common to all channels"> | ||
|
|
||
| The behavior described below is set by Quill, and holds for channels of every type unless a point says otherwise. |
There was a problem hiding this comment.
What does it mean? Seems like a precautionary comment. If the paragraph is removed, points underneath are still valid.
| link, a Telegram bot by any Telegram user who finds it, a Slack bot by the members of the workspace the bot is installed in, and | ||
| a Discord bot by the members of a server the bot is in. | ||
| * **The reply is streamed as the agent composes it.** | ||
| On Telegram, Slack, and Discord, an answer longer than the platform's message limit is delivered in several messages. |
There was a problem hiding this comment.
How is splitting related to streaming. Maybe worth to add if in there
| On Telegram, Slack, and Discord, an answer longer than the platform's message limit is delivered in several messages. | |
| On Telegram, Slack, and Discord, if an answer is longer than the platform's message limit, it is delivered in several messages. |
There was a problem hiding this comment.
-->
- The reply is streamed into the chat as the agent composes it.
- A long answer is delivered in several messages.
On Telegram, Slack, and Discord, an answer that exceeds the platform's message limit is split across several messages.
In a chat widget the whole answer appears in a single reply.
| A chat widget binds the parameters into each embed link | ||
| [when the link is generated](../getting-started/adding-a-chat-widget.mdx#setting-the-link-limits), and a link cannot be generated | ||
| until every parameter has a value. | ||
| * **Pausing a channel takes it out of service; deleting a channel removes it, but keeps the conversations it carried.** |
There was a problem hiding this comment.
What does it mean to keep the conversations it carried? That they are accessible via Quill's dashboard?
There was a problem hiding this comment.
made the title: "Pausing a channel takes it out of service; deleting a channel removes it.",
and the explanation now includes: "The conversations a deleted channel carried remain available in the app's Conversations view."
| The symptoms below may be met by a channel's users, each with its likely cause and what to do about it. | ||
| The bots' messages are quoted in their default form; a Telegram bot with customized messages shows your texts instead. | ||
|
|
||
| **In a chat with a Telegram, Slack, or Discord bot** |
There was a problem hiding this comment.
Is it worth to separate it? When I'm troubleshooting, should I troubleshoot with consideration what channel, or do I care about the error? Should we just make the list blunt and point by point, with no sections?
There was a problem hiding this comment.
I think so. if you're concerned about a chat widget you'll know not to bother with the first answers.
|
|
||
| * **The agent answers from outdated information.** | ||
| Likely cause: the conversation may still hold earlier answers, which the agent reads along with the new question. | ||
| What to do: advise the user to ask explicitly to look the information up again. In a chat with a bot, the agent forgets the |
There was a problem hiding this comment.
This does not seem right. How a product documentation ask for "cache invalidation" by its user? I don't know how to tackle it though.
There was a problem hiding this comment.
-->
- The agent answers from outdated information.
Likely cause: one of the following may have happened.- The app's internal database may not yet hold the latest changes from the source database.
What to do: check the state of the mirroring in the app's Data source view, which shows the number of recent writes and reports any errors met while syncing. - The conversation may hold earlier replies carrying data the agent had retrieved, that the agent now reads instead of retrieving the data again.
What to do: a message that asks pointedly for the current data may make the agent retrieve it again.
In any case, the agent retrieves the data again once it forgets the earlier exchange, as described in
Behavior and limitations common to all channels.
- The app's internal database may not yet hold the latest changes from the source database.
| The **⋮** button opens the channel's menu. The same two actions are also offered on the channel's box in the Channels view, as | ||
| the pencil and trash icons: | ||
|
|
||
| | Edit/delete on the channel's menu | Edit/delete on a channel's box | |
There was a problem hiding this comment.
This grid looks weird. I'm not sure whether it's images being put in the grid or the scaling, but clearly something is off.
There was a problem hiding this comment.
left as is for now, I'll take another look later on at this and other style choices
|
|
||
| What a pause means for the channel's users depends on the channel type: | ||
|
|
||
| * A paused web widget stops answering: |
There was a problem hiding this comment.
The promise is to see the types listed, while we get a paused XYZ as the first part which makes it a bit harder to skip to the correct one. I'd go with blunt
- Slack:
- Telegram:
or similar
|
|
||
| * In this article: | ||
| * [Prerequisites](#prerequisites) | ||
| * [Creating a bot using @BotFather](#creating-a-bot-using-botfather) |
There was a problem hiding this comment.
I'd drop @Botfather from the heading. It's an internal thing.
There was a problem hiding this comment.
strange, but not internal. that's their official interface to create a bot. and to users that did it once, anywhere, the title explains a lot immediately.
| of the number the user shared. | ||
| What to do: advise the user to share the number again. See [Returning users](#returning-users). | ||
|
|
||
| Symptoms met by the users of every bot type, like the notice sent when the bot's queue is full, are listed in the channels overview, |
There was a problem hiding this comment.
What does it mean that a queue is full? What is the queue?
There was a problem hiding this comment.
explained in a fix following an earlier comment, but "queue" is also dropped from this point and the equivalent ones in other pages
| # Channels: Discord bot | ||
| <Admonition type="note" title=""> | ||
|
|
||
| * A Quill **Discord bot** [channel](../overview.mdx#channels) lets your users converse with an [agent](../overview.mdx#ai-agent) |
There was a problem hiding this comment.
Should we have the link back?
| The channel is added for one of the app's agents, and this agent will answer the users who message the bot. | ||
| To add an agent, see [Getting started: Adding an AI agent](../getting-started/adding-an-ai-agent.mdx). | ||
| * **A Discord account.** | ||
| The bot is created in the Discord Developer Portal, signed in with your [Discord account](https://discord.com/register). |
There was a problem hiding this comment.
The bot is signed in with your Discort account? Do I get this right?
There was a problem hiding this comment.
no, but it's completely my fault (o:
--> The bot is created in the Discord Developer Portal, while you are signed in with your Discord account.
|
|
||
| * A Quill **Slack bot** [channel](../overview.mdx#channels) lets your users converse with an [agent](../overview.mdx#ai-agent) | ||
| of your app in a direct message with a bot on Slack. | ||
| Users can message the bot from any Slack client, and the agent will answer from the app's data. |
There was a problem hiding this comment.
Not sure if I mentioned it in other channels, but the answer from app's data seems to be not the best way to put it. I'd rephrase it somehow.
There was a problem hiding this comment.
changed everywhere
--> will answer from the app's internal database
| If you have no Slack workspace yet, you can [create one](https://slack.com/help/articles/206845317-Create-a-Slack-workspace). | ||
| * **Permission to install the bot in the workspace.** | ||
| A workspace's admins can | ||
| [require approval](https://slack.com/help/articles/222386767-Manage-app-approval-for-your-workspace) for the Slack apps that |
There was a problem hiding this comment.
Is this a bot, or an app? I think it's worth to distinguish it and clarify that a Slack bot is called a Slack app? Do I get this right?
There was a problem hiding this comment.
you are right, and I'm using the wrong term (or more precisely, our term) deliberately everywhere to avoid the confusion between their app and ours. it is said in the very top of the page, "The bot is a Slack app installed in the Slack workspace the users belong to."
|
|
||
| <Panel heading="Creating a Slack bot from Quill's manifest"> | ||
|
|
||
| The bot is created on Slack from a **manifest**: a short text, provided by Quill, that describes the bot to Slack, including the |
There was a problem hiding this comment.
| The bot is created on Slack from a **manifest**: a short text, provided by Quill, that describes the bot to Slack, including the | |
| The bot is created on Slack as a Slack application from a **manifest**: a short text, provided by Quill, that describes the bot to Slack, including the |
| Once the bot is installed, Slack shows a page that announces the bot is ready, headed **Quill is ready!** for a bot named Quill, | ||
| with a collapsed **Your app credentials** card. Expand the card: | ||
|
|
||
|  |
There was a problem hiding this comment.
I'm a bit lost. So there's the Bot token and App token in Slack?
There was a problem hiding this comment.
-->
Copy the Bot token: this token is the first of the two credentials you need to collect.
Note that this card also shows an App token, which Quill does not use and you do not need to copy.
|
|
||
| #### Collecting the signing secret: | ||
|
|
||
| To find the **signing secret**, click **Go to App Settings** at the bottom of the Quill is ready! page. |
There was a problem hiding this comment.
If Quill is ready! is the title of the page, we should use some formatting to distinguish it.
There was a problem hiding this comment.
Also, I'm lost. It took me a while to understand that this is the page from the previous point and I should keep it open.
There was a problem hiding this comment.
clarified the instructions around this stage, and recaptured the "Quill is ready!" page to include its title, I hope these will solve the confusion here.
Scooletz
left a comment
Scooletz
left a comment
There was a problem hiding this comment.
One minor left. It's a minor so we're good to go!
|
|
||
| <Admonition type="info" title=""> | ||
|
|
||
| When the form is opened from the **Add agent** wizard, the channel is added for the new agent and this field is absent. |
There was a problem hiding this comment.
newly created ? Something like this? the new agent can be read in many ways
| The duration of a conversation depends on the channel type: | ||
|
|
||
| | Channel type | The conversation lasts | A user can end it sooner | | ||
| |---|---|---| |
There was a problem hiding this comment.
I like this table approach very much
| The **⋮** button opens the channel's menu. The same two actions are also offered on the channel's box in the Channels view, as | ||
| the pencil and trash icons: | ||
|
|
||
| | Edit/delete on the channel's menu | Edit/delete on a channel's box | |
3 participants
Issue link
RDoc-4058 dashboard channels view
RDoc-4078 telegram bot page
RDoc-4088 discord bot page
RDoc-4084 slack bot page
RDoc-4085 channels overview
Type of change
/templatesor readme)Changes in docs URLs
/scripts/redirects.jsonfile, setDocuments MovedPR label)Changes in UX/UI