diff --git a/quill/channels/assets/discord-bot_channel-box.png b/quill/channels/assets/discord-bot_channel-box.png index fddbe6f2c0..5c0a0fa929 100644 Binary files a/quill/channels/assets/discord-bot_channel-box.png and b/quill/channels/assets/discord-bot_channel-box.png differ diff --git a/quill/channels/assets/discord-bot_new-channel.png b/quill/channels/assets/discord-bot_new-channel.png index 60a4ec9c20..d3a1254f21 100644 Binary files a/quill/channels/assets/discord-bot_new-channel.png and b/quill/channels/assets/discord-bot_new-channel.png differ diff --git a/quill/channels/assets/slack-bot_new-channel.png b/quill/channels/assets/slack-bot_new-channel.png index 8364c64230..6b24f2ede9 100644 Binary files a/quill/channels/assets/slack-bot_new-channel.png and b/quill/channels/assets/slack-bot_new-channel.png differ diff --git a/quill/channels/assets/snagit/discord-bot_new-channel.snagx b/quill/channels/assets/snagit/discord-bot_new-channel.snagx index dbbe082ffc..14f08372af 100644 Binary files a/quill/channels/assets/snagit/discord-bot_new-channel.snagx and b/quill/channels/assets/snagit/discord-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/slack-bot_new-channel.snagx b/quill/channels/assets/snagit/slack-bot_new-channel.snagx index 9d4a60496c..13cfb38861 100644 Binary files a/quill/channels/assets/snagit/slack-bot_new-channel.snagx and b/quill/channels/assets/snagit/slack-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/telegram-bot_new-channel.snagx b/quill/channels/assets/snagit/telegram-bot_new-channel.snagx index 3932878a47..d4d146ec38 100644 Binary files a/quill/channels/assets/snagit/telegram-bot_new-channel.snagx and b/quill/channels/assets/snagit/telegram-bot_new-channel.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_active-links.snagx b/quill/channels/assets/snagit/web-widget_active-links.snagx new file mode 100644 index 0000000000..9b11cf5628 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_active-links.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_add-channel-menu.snagx b/quill/channels/assets/snagit/web-widget_add-channel-menu.snagx new file mode 100644 index 0000000000..8112b77d2a Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_add-channel-menu.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_channel-box.snagx b/quill/channels/assets/snagit/web-widget_channel-box.snagx new file mode 100644 index 0000000000..a31694cd52 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_channel-box.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_channels-view.snagx b/quill/channels/assets/snagit/web-widget_channels-view.snagx new file mode 100644 index 0000000000..f0fa5504c5 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_channels-view.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_customize-appearance.snagx b/quill/channels/assets/snagit/web-widget_customize-appearance.snagx new file mode 100644 index 0000000000..f46c34dcc2 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_customize-appearance.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_details-view_header-and-tabs.snagx b/quill/channels/assets/snagit/web-widget_details-view_header-and-tabs.snagx new file mode 100644 index 0000000000..2d195fc48e Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_details-view_header-and-tabs.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_edit-channel.snagx b/quill/channels/assets/snagit/web-widget_edit-channel.snagx new file mode 100644 index 0000000000..c06bab147f Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_edit-channel.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_embed-tab.snagx b/quill/channels/assets/snagit/web-widget_embed-tab.snagx new file mode 100644 index 0000000000..8fa1e9a566 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_embed-tab.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_embed-tab_request-languages.snagx b/quill/channels/assets/snagit/web-widget_embed-tab_request-languages.snagx new file mode 100644 index 0000000000..8d47171ad7 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_embed-tab_request-languages.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_embed-tab_snippet-platforms.snagx b/quill/channels/assets/snagit/web-widget_embed-tab_snippet-platforms.snagx new file mode 100644 index 0000000000..bb0dd1c810 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_embed-tab_snippet-platforms.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_generate-link.snagx b/quill/channels/assets/snagit/web-widget_generate-link.snagx new file mode 100644 index 0000000000..bdad77535c Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_generate-link.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_generate-link_parameter.snagx b/quill/channels/assets/snagit/web-widget_generate-link_parameter.snagx new file mode 100644 index 0000000000..d5ca599710 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_generate-link_parameter.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_link-generated.snagx b/quill/channels/assets/snagit/web-widget_link-generated.snagx new file mode 100644 index 0000000000..3f4420e8b4 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_link-generated.snagx differ diff --git a/quill/channels/assets/snagit/web-widget_new-channel.snagx b/quill/channels/assets/snagit/web-widget_new-channel.snagx new file mode 100644 index 0000000000..3e1276bb41 Binary files /dev/null and b/quill/channels/assets/snagit/web-widget_new-channel.snagx differ diff --git a/quill/channels/assets/telegram-bot_channel-box.png b/quill/channels/assets/telegram-bot_channel-box.png index 6576da7b15..65592520a0 100644 Binary files a/quill/channels/assets/telegram-bot_channel-box.png and b/quill/channels/assets/telegram-bot_channel-box.png differ diff --git a/quill/channels/assets/telegram-bot_new-channel.png b/quill/channels/assets/telegram-bot_new-channel.png index 32bca36ea9..d795b3f098 100644 Binary files a/quill/channels/assets/telegram-bot_new-channel.png and b/quill/channels/assets/telegram-bot_new-channel.png differ diff --git a/quill/channels/assets/web-widget_active-links.png b/quill/channels/assets/web-widget_active-links.png new file mode 100644 index 0000000000..3dbe27b8e5 Binary files /dev/null and b/quill/channels/assets/web-widget_active-links.png differ diff --git a/quill/channels/assets/web-widget_active-links_limit-reached.png b/quill/channels/assets/web-widget_active-links_limit-reached.png new file mode 100644 index 0000000000..cc90dd2a8d Binary files /dev/null and b/quill/channels/assets/web-widget_active-links_limit-reached.png differ diff --git a/quill/channels/assets/web-widget_add-channel-menu.png b/quill/channels/assets/web-widget_add-channel-menu.png new file mode 100644 index 0000000000..c20f73ae1b Binary files /dev/null and b/quill/channels/assets/web-widget_add-channel-menu.png differ diff --git a/quill/channels/assets/web-widget_channel-box.png b/quill/channels/assets/web-widget_channel-box.png new file mode 100644 index 0000000000..115ec82ffd Binary files /dev/null and b/quill/channels/assets/web-widget_channel-box.png differ diff --git a/quill/channels/assets/web-widget_channel-menu.png b/quill/channels/assets/web-widget_channel-menu.png new file mode 100644 index 0000000000..cab3c077d6 Binary files /dev/null and b/quill/channels/assets/web-widget_channel-menu.png differ diff --git a/quill/channels/assets/web-widget_channels-view.png b/quill/channels/assets/web-widget_channels-view.png new file mode 100644 index 0000000000..8ded89cdf3 Binary files /dev/null and b/quill/channels/assets/web-widget_channels-view.png differ diff --git a/quill/getting-started/assets/adding-a-chat-widget_widget-in-page.png b/quill/channels/assets/web-widget_chat-box-on-page.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_widget-in-page.png rename to quill/channels/assets/web-widget_chat-box-on-page.png diff --git a/quill/channels/assets/web-widget_conversation-ended.png b/quill/channels/assets/web-widget_conversation-ended.png new file mode 100644 index 0000000000..79922ce286 Binary files /dev/null and b/quill/channels/assets/web-widget_conversation-ended.png differ diff --git a/quill/channels/assets/web-widget_conversation-not-available.png b/quill/channels/assets/web-widget_conversation-not-available.png new file mode 100644 index 0000000000..d5b7e20c0f Binary files /dev/null and b/quill/channels/assets/web-widget_conversation-not-available.png differ diff --git a/quill/channels/assets/web-widget_conversations-per-visitor.svg b/quill/channels/assets/web-widget_conversations-per-visitor.svg new file mode 100644 index 0000000000..95aebbc81a --- /dev/null +++ b/quill/channels/assets/web-widget_conversations-per-visitor.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + Your website page + + + + + Visitor 1 + + + Chat box + Embed link 1 + + + + + Visitor 2 + + + Chat box + Embed link 2 + + + + + Visitor 3 + + + Chat box + Embed link 3 + + Each page visitor gets a separate + chat box and conversation + + + + + + Quill + + + + Web widget channel + + + + Agent + Answers all conversations + + + + Internal database + + + Queries + + + + + + + Conversation 1 + Conversation 2 + Conversation 3 + + + + + + + + + + + + diff --git a/quill/channels/assets/web-widget_conversations.svg b/quill/channels/assets/web-widget_conversations.svg new file mode 100644 index 0000000000..350eab4b00 --- /dev/null +++ b/quill/channels/assets/web-widget_conversations.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + Your website page + + + + + + + + + + + Chat box + Embed link + + All page visitors share the chat box + and the conversation + + + + + Quill + + + + Web widget channel + + + + Agent + Answers all conversations + + + + Internal database + + + Queries + + + + + Conversation + + + + + + + + diff --git a/quill/channels/assets/web-widget_customize-appearance.png b/quill/channels/assets/web-widget_customize-appearance.png new file mode 100644 index 0000000000..0b39d17896 Binary files /dev/null and b/quill/channels/assets/web-widget_customize-appearance.png differ diff --git a/quill/channels/assets/web-widget_details-view_header-and-tabs.png b/quill/channels/assets/web-widget_details-view_header-and-tabs.png new file mode 100644 index 0000000000..f98c18f9bc Binary files /dev/null and b/quill/channels/assets/web-widget_details-view_header-and-tabs.png differ diff --git a/quill/channels/assets/web-widget_edit-channel.png b/quill/channels/assets/web-widget_edit-channel.png new file mode 100644 index 0000000000..7df038f396 Binary files /dev/null and b/quill/channels/assets/web-widget_edit-channel.png differ diff --git a/quill/channels/assets/web-widget_embed-tab.png b/quill/channels/assets/web-widget_embed-tab.png new file mode 100644 index 0000000000..f7a83aa4e7 Binary files /dev/null and b/quill/channels/assets/web-widget_embed-tab.png differ diff --git a/quill/channels/assets/web-widget_embed-tab_request-languages.png b/quill/channels/assets/web-widget_embed-tab_request-languages.png new file mode 100644 index 0000000000..724b6423c2 Binary files /dev/null and b/quill/channels/assets/web-widget_embed-tab_request-languages.png differ diff --git a/quill/channels/assets/web-widget_embed-tab_snippet-platforms.png b/quill/channels/assets/web-widget_embed-tab_snippet-platforms.png new file mode 100644 index 0000000000..1ce170aac8 Binary files /dev/null and b/quill/channels/assets/web-widget_embed-tab_snippet-platforms.png differ diff --git a/quill/channels/assets/web-widget_generate-link.png b/quill/channels/assets/web-widget_generate-link.png new file mode 100644 index 0000000000..a7dcbf4b3d Binary files /dev/null and b/quill/channels/assets/web-widget_generate-link.png differ diff --git a/quill/channels/assets/web-widget_generate-link_parameter.png b/quill/channels/assets/web-widget_generate-link_parameter.png new file mode 100644 index 0000000000..ac6aaaa4c5 Binary files /dev/null and b/quill/channels/assets/web-widget_generate-link_parameter.png differ diff --git a/quill/channels/assets/web-widget_link-generated.png b/quill/channels/assets/web-widget_link-generated.png new file mode 100644 index 0000000000..ec5b9aafda Binary files /dev/null and b/quill/channels/assets/web-widget_link-generated.png differ diff --git a/quill/channels/assets/web-widget_link-no-longer-active.png b/quill/channels/assets/web-widget_link-no-longer-active.png new file mode 100644 index 0000000000..03f190132e Binary files /dev/null and b/quill/channels/assets/web-widget_link-no-longer-active.png differ diff --git a/quill/channels/assets/web-widget_new-channel.png b/quill/channels/assets/web-widget_new-channel.png new file mode 100644 index 0000000000..85c42f9545 Binary files /dev/null and b/quill/channels/assets/web-widget_new-channel.png differ diff --git a/quill/channels/assets/web-widget_revoke-link.png b/quill/channels/assets/web-widget_revoke-link.png new file mode 100644 index 0000000000..74495a366e Binary files /dev/null and b/quill/channels/assets/web-widget_revoke-link.png differ diff --git a/quill/channels/assets/web-widget_usage-limit-notice.png b/quill/channels/assets/web-widget_usage-limit-notice.png new file mode 100644 index 0000000000..6f6040e16d Binary files /dev/null and b/quill/channels/assets/web-widget_usage-limit-notice.png differ diff --git a/quill/channels/discord-bot.mdx b/quill/channels/discord-bot.mdx index b06f41201f..69c87ffedf 100644 --- a/quill/channels/discord-bot.mdx +++ b/quill/channels/discord-bot.mdx @@ -1,7 +1,7 @@ --- title: "Channels: Discord bot" sidebar_label: Discord bot -sidebar_position: 3 +sidebar_position: 4 description: "A Discord bot channel for a Quill app: creating the bot in the Discord Developer Portal, connecting it to the app and inviting it to your server, what its users meet in a direct message with the bot, binding agent parameters, managing the channel, and the limitations of a Discord bot." --- @@ -22,7 +22,7 @@ import ContentFrame from "@site/src/components/ContentFrame"; public address or open inbound port. * The channel is added from Quill's management dashboard, using one short form that asks you to select one of the agents you - created and provide the bot token and an optional channel name. + created and provide the bot token and a channel name. * If the selected agent has parameters, the form also asks you to settle each parameter's value. You can either provide a fixed value, or take the value from the Discord user the bot is chatting with: the user's Discord ID or username. @@ -157,8 +157,9 @@ Selecting **Discord** opens the **New Discord channel** form. 3. **Bot token** Paste the token you copied from the Bot page. The field shows the token as dots; click the eye icon to reveal it. Quill validates the token with Discord when the channel is added, and never displays it again afterwards. -4. **Channel name** (optional) - If you leave this field empty, Quill will name the channel after the bot's username, e.g., `Northwind Traders Catalog`. +4. **Channel name** + Enter a name for the channel (e.g., `Community Discord`). + The name will be displayed on the channel's box in the [Channels view](../dashboard/manage-an-app/channels-view.mdx). 5. **Connect bot** Click to add the channel. If Discord rejects the token, or the bot is already connected to another channel, the form will report the error and no channel will be added. diff --git a/quill/channels/overview.mdx b/quill/channels/overview.mdx index c6f0dbec2d..221ad9fb07 100644 --- a/quill/channels/overview.mdx +++ b/quill/channels/overview.mdx @@ -14,8 +14,8 @@ import ContentFrame from "@site/src/components/ContentFrame"; * A **channel** carries the conversations between your users and an [agent](../overview.mdx#ai-agent) of your app: user messages reach the agent through the channel, and replies return the same way. - 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. + Quill offers four channel types: a web widget channel with a chat box embedded in your website or app, 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 the channel's users encounter. This article covers what applies to channels of every type. @@ -36,9 +36,9 @@ Quill offers four channel types, each carrying the conversations through a diffe 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 - [embed link](../getting-started/adding-a-chat-widget.mdx#generating-an-embed-link) placed on the page. - See [Getting started: Adding a chat widget](../getting-started/adding-a-chat-widget.mdx). + A channel that opens to a [chat box](../overview.mdx#web-widget) on your website page, which your users reach through an + [embed link](../channels/web-widget.mdx#generating-an-embed-link) placed on the page. + See [Channels: Web widget](../channels/web-widget.mdx). * **Telegram bot** A bot that your users chat with on Telegram, created using @BotFather. See [Channels: Telegram bot](../channels/telegram-bot.mdx). @@ -52,7 +52,7 @@ A channel's type is selected in the **Add channel** menu, described in [Adding a | Channel type | Where your users chat | What you set up outside Quill | Quill reachable from the internet | |---|---|---|---| -| Chat widget | On a page of your site | The embed snippet, in the page's HTML | Not required | +| Web widget | In a chat box on your website page | The embed snippet, in the page's HTML | Required, so your visitors' browsers can reach the chat box | | Telegram bot | In Telegram | A bot, using @BotFather | Not required | | Slack bot | In the Slack client | A Slack app, from Quill's manifest | Required | | Discord bot | In Discord | A bot, in the Discord Developer Portal | Not required | @@ -66,7 +66,7 @@ conversations to this agent alone. The following holds for channels of every type: * **An agent can serve several channels at once.** - e.g., a chat widget on your site and a Telegram bot, both answered by the same agent. + e.g., a web widget channel and a Telegram bot, both answered by the same agent. * **A channel serves the agent it was added for.** The agent cannot be changed afterwards. To serve another agent, add a new channel for this agent. * **A bot serves one channel.** @@ -107,8 +107,8 @@ Agent parameters are bound by the channel, and the source of a parameter's value A parameter left unbound, e.g., a parameter added to the agent after the channel was added, stops the bot from answering until the parameter is bound in the **Parameters** tab of the [channel's details view](../dashboard/manage-an-app/channels-view.mdx#the-channel-s-details-view). -* 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 +* A **web widget** binds the parameters into each embed link + [when the link is generated](../channels/web-widget.mdx#binding-agent-parameters), and a link cannot be generated until every parameter has a value. @@ -117,20 +117,20 @@ Agent parameters are bound by the channel, and the source of a parameter's value * **Users need no account with Quill.** Who can reach a channel depends on the channel type: - * A chat widget is reached by whoever opens the page that holds its embed link. - * A Telegram bot is reached by any Telegram user who finds it. + * A web widget channel is reached by any visitor to a website page that holds one of the channel's embed links. + * A Telegram bot is reached by any Telegram user who finds the bot. * A Slack bot is reached by the members of the workspace the bot is installed in. * A Discord bot is reached by the members of a server the bot is in. * **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. + In a chat box the whole answer appears in a single reply. * **Quill keeps the conversation's context, so a follow-up question is understood against the earlier exchange.** The duration of a conversation depends on the channel type: | Channel type | The conversation lasts | A user can end it sooner | |---|---|---| - | Chat widget | As long as the embed link that opened the widget | No | + | Web widget | As long as the embed link that opened the chat box | No | | Telegram bot | Until midnight UTC | Yes, by sending `/clear` | | Slack bot | Until midnight UTC | No | | Discord bot | Until midnight UTC | No | @@ -139,9 +139,9 @@ Agent parameters are bound by the channel, and the source of a parameter's value the earlier exchange, and the next message is answered without the earlier context. The messages themselves remain in the chat. A Telegram user can make the agent forget sooner by sending `/clear`; Slack and Discord users cannot. - * In a chat widget, the conversation belongs to the embed link that opened the widget, and lasts as long as the link does: - everyone who opens the widget through the same link shares one conversation, and the conversation ends when the link - [expires, reaches its usage cap, or is revoked](../getting-started/adding-a-chat-widget.mdx#setting-the-link-limits). + * In a web widget channel, the conversation belongs to the embed link that opened the chat box, and lasts as long as the link is valid: + all website visitors who open the chat box through the same link share the same conversation, which ends when + the link [expires, reaches its chat limit, or is revoked](../channels/web-widget.mdx#invalid-links). * **Messages sent faster than the bot answers may go unanswered.** On Telegram, Slack, and Discord, a message a user sends while the bot is still answering waits in a queue that Quill keeps for this user. When the queue is full, further messages are not taken, and the bot sends one notice asking the user to send the @@ -158,7 +158,7 @@ Agent parameters are bound by the channel, and the source of a parameter's value What each action means for the channel's users, and for a bot on its platform, depends on the channel type and is described in the type's article. * **The messages a channel sends on its own have a default text set by Quill.** - The notices a chat widget shows when its embed link no longer works, and the replies a Slack or Discord bot sends on its own, like + The notices a chat box shows when its embed link no longer works, and the replies a Slack or Discord bot sends on its own, like "I can only read text messages right now.", cannot be changed. A Telegram bot's own messages can be replaced with texts of yours in the **Bot messages** tab of the channel's details view. @@ -177,13 +177,13 @@ The bots' messages are quoted in their default form; a Telegram bot with customi carry a file, like an image or a document. A Telegram bot gives such a message no reply; a Slack or Discord bot answers with the quoted notice. What to do: advise the user to send the question as text. - A chat widget takes text only, so its users do not meet this symptom. + A chat box takes text only, so its users do not meet this symptom. * **The bot replies "I'm still working through your earlier messages, so that one didn't make it. Please resend it once I've replied."** Likely cause: the user may have sent more messages than the bot's queue can hold while an answer was still being composed, as stated in [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels). What to do: advise the user to wait for the bot's reply, and then send the message again. - A chat widget takes no new message while the agent is still answering, so its users do not meet this symptom. + A chat box takes no new message while the agent is still answering, so its users do not meet this symptom. **In a channel of any type** @@ -201,7 +201,7 @@ The bots' messages are quoted in their default form; a Telegram bot with customi Symptoms specific to a channel type, including those seen in Quill's management dashboard and on the bot's platform, are listed in the Troubleshooting section of the type's article: [Telegram bot](../channels/telegram-bot.mdx#troubleshooting), [Slack bot](../channels/slack-bot.mdx#troubleshooting), and [Discord bot](../channels/discord-bot.mdx#troubleshooting). -The notices a chat widget shows when its embed link cannot be used are listed in -[Embed the Chat Widget](../developer-access/embed-the-chat-widget.mdx#when-a-link-or-widget-cannot-be-used). +The notices a chat box shows when its embed link cannot be used are listed in +[Invalid links](../channels/web-widget.mdx#invalid-links). diff --git a/quill/channels/slack-bot.mdx b/quill/channels/slack-bot.mdx index a6256d4628..8dea43e5a6 100644 --- a/quill/channels/slack-bot.mdx +++ b/quill/channels/slack-bot.mdx @@ -1,7 +1,7 @@ --- title: "Channels: Slack bot" sidebar_label: Slack bot -sidebar_position: 4 +sidebar_position: 5 description: "A Slack bot channel for a Quill app: creating a Slack bot from Quill's manifest, connecting it to the app and finishing the event subscription on Slack, what its users meet in a direct message with the bot, binding agent parameters, managing the channel, and the limitations of a Slack bot." --- @@ -261,8 +261,9 @@ Selecting **Slack** opens the **New Slack channel** form. Paste the signing secret you collected on Slack. The field shows the secret as dots; click the eye icon to reveal it. Quill uses the secret to verify that every message delivered to the channel really comes from Slack, and never displays the secret again afterwards. -5. **Channel name** (optional) - If you leave this field empty, Quill will name the channel after the bot's username on Slack, e.g., `quill`. +5. **Channel name** + Enter a name for the channel (e.g., `Support Slack`). + The name will be displayed on the channel's box in the [Channels view](../dashboard/manage-an-app/channels-view.mdx). 6. **Connect bot** Click to add the channel. If Slack rejects the token, or the bot is already connected to another channel, the form will report the error and no channel will be added. diff --git a/quill/channels/telegram-bot.mdx b/quill/channels/telegram-bot.mdx index ea929ea92d..6b40412c7c 100644 --- a/quill/channels/telegram-bot.mdx +++ b/quill/channels/telegram-bot.mdx @@ -1,7 +1,7 @@ --- title: "Channels: Telegram bot" sidebar_label: Telegram bot -sidebar_position: 2 +sidebar_position: 3 description: "A Telegram bot channel for a Quill app: creating the bot with @BotFather, connecting it to the app, what its users meet in the chat, binding agent parameters to the Telegram user, managing the channel, and the limitations of a Telegram bot." --- @@ -21,7 +21,7 @@ import ContentFrame from "@site/src/components/ContentFrame"; Quill collects the incoming messages from Telegram, so the deployment needs no public address or open inbound port. * The channel is added from Quill's management dashboard, using one short form that asks you to select one of the agents you - created and provide the bot token and an optional channel name. + created and provide the bot token and a channel name. * If the selected agent has parameters, the form also asks you to settle each parameter's value. You can either provide a fixed value, or take the value from the Telegram user the bot is chatting with, e.g., the user's phone number. @@ -149,7 +149,8 @@ Selecting **Telegram bot** opens the **New Telegram bot channel** form. Paste the token you received from @BotFather. The field shows the token as dots; click the eye icon to reveal it. Quill validates the token with Telegram when the channel is added, and never displays it again afterwards. 3. **Channel name** - This field is optional. If you leave it empty, Quill will name the channel after the bot's username, e.g., `@NorthwindCatalogBot`. + Enter a name for the channel (e.g., `Support Telegram`). + The name will be displayed on the channel's box in the [Channels view](../dashboard/manage-an-app/channels-view.mdx). 4. **Connect bot** Click to add the channel. If Telegram rejects the token, or the bot is already connected to another channel, the form will report the error and no channel will be added. diff --git a/quill/channels/web-widget.mdx b/quill/channels/web-widget.mdx new file mode 100644 index 0000000000..662d8a0f7d --- /dev/null +++ b/quill/channels/web-widget.mdx @@ -0,0 +1,765 @@ +--- +title: "Channels: Web widget" +sidebar_label: Web widget +sidebar_position: 2 +description: "A web widget channel for a Quill app: adding the channel, generating the embed links that open the chat box, what the chat box's users encounter, binding agent parameters into a link, managing the channel, its links and its appearance, and the limitations of a web widget." +--- + +import Admonition from '@theme/Admonition'; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; + +# Channels: Web widget + + +* A **web widget** is a Quill app [channel](../overview.mdx#channels) that opens to a chat box on your website page. + When a visitor to your page uses the chat box to ask a question, the channel carries the question to + an [agent](../overview.mdx#ai-agent) of your Quill app. + The agent then queries the app's internal database, and answers the visitor through the channel, in the chat box. + +* A visitor to the website needs no Quill account or any knowledge of Quill to use the chat box. + +* The chat box is embedded in your website page using an **embed link** generated by Quill. + Add the web widget channel and generate the embed link for the chat box using Quill's management dashboard, as explained below. + +* The chat box can also be embedded in a phone app, in a component that displays web pages as a browser does. + This article follows the website case. + +* A chat box embed link is valid for a period and a number of chats of your choice. + +* Each chat box opens a single conversation thread over the web widget channel. All page visitors that use the same + chat box take part in the same conversation; users of a different chat box participate in a different conversation. + +* In this article: + * [Prerequisites](#prerequisites) + * [Adding the channel](#adding-the-channel) + * [Opening the Add channel menu](#opening-the-add-channel-menu) + * [Filling in the channel form](#filling-in-the-channel-form) + * [Checking the new channel](#checking-the-new-channel) + * [Generating an embed link](#generating-an-embed-link) + * [Two ways to generate the link](#two-ways-to-generate-the-link) + * [Setting the link limits](#setting-the-link-limits) + * [Copying the link](#copying-the-link) + * [Placing the embed snippet on your page](#placing-the-embed-snippet-on-your-page) + * [Chatting through the channel](#chatting-through-the-channel) + * [Starting a conversation](#starting-a-conversation) + * [Invalid links](#invalid-links) + * [Binding agent parameters](#binding-agent-parameters) + * [Query tools](#query-tools) + * [Query parameters](#query-parameters) + * [Managing the channel](#managing-the-channel) + * [Opening the channel's details view](#opening-the-channels-details-view) + * [Pausing and deleting the channel](#pausing-and-deleting-the-channel) + * [Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins) + * [The management tabs](#the-management-tabs) + * [Web widget limitations](#web-widget-limitations) + * [Troubleshooting](#troubleshooting) + + + + + +Before adding a web widget channel, make sure you have: + +* **An agent to answer the chat box's users.** + The web widget channel is added for a specific agent, and the conversation is then carried over the channel + between the chat box users and the agent. + Learn to add an agent in [Getting started: Adding an AI agent](../getting-started/adding-an-ai-agent.mdx). +* **Editing rights on the website page you want to add the chat box to.** + You need these rights so you can edit the page's HTML and add to it the embed link that opens the chat box. +* **A Quill deployment with a public address that your visitors' browsers can reach.** + The chat box is served by your Quill deployment, not by your website. + A deployment running in an environment isolated from the internet, like your own machine or a private + company network, will be able to serve only browsers with access to this environment, e.g., your own browser. + + + + + +A web widget channel is added using Quill's management dashboard, in a short form that asks you to: +* Select the agent that will answer the chat box's users. +* Give the channel a name. +* Specify the websites that are allowed to embed the chat box. + + + +### Opening the Add channel menu + +Enter your app's [Channels view](../dashboard/manage-an-app/channels-view.mdx#opening-the-channels-view) by opening +**My apps** in the management dashboard, selecting your app, and clicking the sidebar **Channels** option. +To add a new web widget channel, click the **New channel** button and select **Web widget** in the channel types menu. + +![The New channel menu](./assets/web-widget_add-channel-menu.png) + + +Additional entry points to the **Add channel** menu: +* You can open the same menu using the **Add channel** button in the [app overview](../dashboard/manage-an-app/overview.mdx#channels) **Channels** section. +* The [Add agent wizard](../getting-started/adding-an-ai-agent.mdx#saving-the-agent) ends on an **Add a channel** stage carrying + the same **Add channel** button, so a channel can be added for the new agent right after creating it. + + + + + + + +### Filling in the channel form + +Selecting **Web widget** opens the **New web widget channel** form: + +![New web widget channel](./assets/web-widget_new-channel.png) + +1. **Agent** + Select the agent that will answer the chat box's users. + + + When the form opens while running the **Add agent** wizard, the newly created agent + is selected automatically and the **Agent** field is omitted. + +2. **Channel name** + Enter a name for the channel (e.g., `Catalog chat`). + - The name will be displayed on the channel's box in the [Channels view](../dashboard/manage-an-app/channels-view.mdx). +3. **Allowed origins** + Choose the websites permitted to embed the chat box. + Click **Add origin** and enter the website's address with no page path, one entry per website (e.g., `https://shop.example.com`). + - While the list is empty, **any website** is permitted to embed the chat box. + + + Listing your own websites here is recommended, so no other websites can embed the chat box. + + - The list can be edited later, see [Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins). +4. **Create channel** + Click to add the channel to the app. + + + + + +### Checking the new channel + +Once created, the new channel is listed in the Channels view, under the **Web widgets** group. + +![The new channel's box](./assets/web-widget_channel-box.png) + +1. **Customize default appearance** + Set the default appearance of the app's chat boxes. + See [The Customize appearance tab](#the-customize-appearance-tab). +2. **Active links** + The number of embed links that were generated for the channel and can still be used. +3. **Generate link** + Generate an embed link for the channel. + See [Generating an embed link](#generating-an-embed-link). + +The channel box also shows the channel's status (**Active** in the depicted box), the agent the channel was added for, +and the date the channel was added. +The pencil and trash icons are used to edit or delete the channel, see [Managing the channel](#managing-the-channel). + + + + + + + +* A **web widget channel** can carry multiple conversations between your users and the agent that you added the channel for. +* An **embed link** is the address of a single conversation carried over the web widget channel. + When placed on your website page, an embed link opens a **chat box** to the conversation. +* Joining a conversation through a chat box requires no sign-in or any other procedure. +* The conversation ends when the embed link expires, reaches its chat limit, or is revoked. + When the chat box's users send their next message, they will be notified that the conversation has ended + and further messaging will be disabled. + A new conversation requires a new embed link. + + + +### Two ways to generate the link + +#### Having your backend generate the link: + +Embed links are normally generated by your backend, which automatically serves each page visitor or app user a unique link. +This way different visitors and users conduct their own conversations with Quill agents. +When a visitor's conversation ends, the backend can automatically replace the link with a fresh one that opens a new conversation. + +![Each page visitor with a separate chat box and conversation](./assets/web-widget_conversations-per-visitor.svg) + + +To learn more about generating embed links automatically, see: +- The [Embed tab](#the-embed-tab) section below. +- The dedicated [Embed the Chat Widget](../developer-access/embed-the-chat-widget.mdx#mint-links-from-your-own-backend) article. + + +--- + +#### Generating the link manually: + +You can also generate an embed link yourself, using the dashboard, to test the agent, the chat box, +and the behavior of the conversation. +Be aware that all the users of a chat box opened using the same embed link participate in the same +conversation and see its common history, and that when the conversation ends no mechanism replaces +the link automatically. + +![All page visitors sharing one chat box and one conversation](./assets/web-widget_conversations.svg) + + + +--- + +Generate an embed link manually using the **Generate embed link** dialog. +To open the dialog: +- either click the chain icon on the channel's box in the Channels view (see [Checking the new channel](#checking-the-new-channel)), +- or click **Generate link** in the **Active links** tab of the channel's details view (see [The Active links tab](#the-active-links-tab)). + + + +### Setting the link limits + +The **Generate embed link** dialog has two panels. +The first panel is used to set the embed link limits, provide values for agent parameters (if the agent has any +parameters), and generate the embed link. + +![Generate embed link](./assets/web-widget_generate-link.png) + +1. **Link expires after** + Select the period after which the link stops working: **1 hour**, **4 hours**, **24 hours**, **7 days**, or **Custom**. +2. **Custom duration** + Shown when **Link expires after** is set to **Custom**. + Enter a number and select the time unit (seconds, minutes, hours, or days), for a period of **1 minute** to **30 days**. +3. **Max invocations** + Enter the maximum number of chats allowed through this link before it stops working (**100** by default, up to **1,000,000**). + A **chat** is a single question and its answer. +4. **Generate link** + Generate the embed link. + + +If the channel's agent has parameters, an additional field is shown for each parameter, +requiring you to provide values for all parameters before the embed link can be generated. +See [Binding agent parameters](#binding-agent-parameters). + + + + + + +### Copying the link + +Use the second dialog panel to copy and test the generated link. + +![The generated link](./assets/web-widget_link-generated.png) + +1. **Embed URL** + The embed link: the address of the chat box's conversation. + You can copy the URL and open it in a new browser tab to see and test the chat box. +2. **Embed snippet** + The same address, wrapped in an ` +``` +
+ +* When embedded, the snippet is a part of your website page and you can set its width and height + to fit the chat box to your page layout. +* The chat box itself is **not** created by your page, but served by your Quill deployment + into the ` ```
-The widget serves itself from your Quill deployment, so the page needs nothing else: no library to install, no +The chat box is served by your Quill deployment, so the page needs nothing else: no library to install, no script to add, and no styling to write. Set the `width` and `height` to suit your layout, and shape the element as you please: a `title` attribute, -a style, or any other addition that blends the widget into your site. +a style, or any other addition that blends the chat box into your website. -![The widget on a page](./assets/adding-a-chat-widget_widget-in-page.png) +![The chat box on a page](./assets/adding-a-web-widget-channel_widget-in-page.png) -A visitor types a question into the widget and is answered from your app's data, without an account and without -any dealings with Quill. +A visitor types a question into the chat box and is answered from your app's data, without an account or +any other dealings with Quill. --- @@ -265,8 +262,8 @@ Two things are left to settle before a page like this faces real visitors: * **The allowed origins of the channel.** While the [allowed origins list](#naming-the-channel-and-setting-its-allowed-origins) - is empty, your widget can be placed on any site. - Edit the channel and enter the addresses of your own pages if you want to keep the widget to them. + is empty, any website can embed the chat box. + Edit the channel and enter the addresses of your own websites if you want to keep the chat box to them. * **A link for each visitor.** A link carries one conversation and one set of limits, so everybody visiting a page that holds an embed link @@ -284,9 +281,12 @@ This concludes the Getting Started path: Quill is deployed and you can access and manage it, your source data is mirrored into your app's internal database, an agent answers from this internal database, -and your users can reach the agent through a chat widget on your website. +and your users can reach the agent through a chat box on your website. -There is much more to Quill than these pages cover, including other channels besides the chat +The channel's full documentation, including its management options and limitations, is in +[Channels: Web widget](../channels/web-widget.mdx). + +There is much more to Quill than these pages cover, including other channels besides the web widget, and actions your agents may run. The [Overview](../overview.mdx) page is a good starting point for more, and you can then navigate the documentation and, above all, experiment in your own deployment. diff --git a/quill/getting-started/adding-an-ai-agent.mdx b/quill/getting-started/adding-an-ai-agent.mdx index a0124befb4..2ef6838a01 100644 --- a/quill/getting-started/adding-an-ai-agent.mdx +++ b/quill/getting-started/adding-an-ai-agent.mdx @@ -370,7 +370,7 @@ time. See [App: Agents view](../dashboard/manage-an-app/agents-view.mdx). ![Agent listed](./assets/adding-an-ai-agent_agent-listed.png) -The next Getting Started step explains how to [add a channel](../getting-started/adding-a-chat-widget.mdx) for the new agent. +The next Getting Started step explains how to [add a channel](../getting-started/adding-a-web-widget-channel.mdx) for the new agent. diff --git a/quill/getting-started/assets/adding-a-chat-widget_new-channel.png b/quill/getting-started/assets/adding-a-chat-widget_new-channel.png deleted file mode 100644 index 91dd86533d..0000000000 Binary files a/quill/getting-started/assets/adding-a-chat-widget_new-channel.png and /dev/null differ diff --git a/quill/getting-started/assets/adding-a-chat-widget_widget-answering.png b/quill/getting-started/assets/adding-a-chat-widget_widget-answering.png deleted file mode 100644 index be917e3799..0000000000 Binary files a/quill/getting-started/assets/adding-a-chat-widget_widget-answering.png and /dev/null differ diff --git a/quill/getting-started/assets/adding-a-chat-widget_add-a-channel-stage.png b/quill/getting-started/assets/adding-a-web-widget-channel_add-a-channel-stage.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_add-a-channel-stage.png rename to quill/getting-started/assets/adding-a-web-widget-channel_add-a-channel-stage.png diff --git a/quill/getting-started/assets/adding-a-chat-widget_add-channel-menu.png b/quill/getting-started/assets/adding-a-web-widget-channel_add-channel-menu.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_add-channel-menu.png rename to quill/getting-started/assets/adding-a-web-widget-channel_add-channel-menu.png diff --git a/quill/getting-started/assets/adding-a-chat-widget_channel-created.png b/quill/getting-started/assets/adding-a-web-widget-channel_channel-created.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_channel-created.png rename to quill/getting-started/assets/adding-a-web-widget-channel_channel-created.png diff --git a/quill/getting-started/assets/adding-a-chat-widget_generate-link.png b/quill/getting-started/assets/adding-a-web-widget-channel_generate-link.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_generate-link.png rename to quill/getting-started/assets/adding-a-web-widget-channel_generate-link.png diff --git a/quill/getting-started/assets/adding-a-chat-widget_generate-link_parameter.png b/quill/getting-started/assets/adding-a-web-widget-channel_generate-link_parameter.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_generate-link_parameter.png rename to quill/getting-started/assets/adding-a-web-widget-channel_generate-link_parameter.png diff --git a/quill/getting-started/assets/adding-a-chat-widget_link-minted.png b/quill/getting-started/assets/adding-a-web-widget-channel_link-minted.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_link-minted.png rename to quill/getting-started/assets/adding-a-web-widget-channel_link-minted.png diff --git a/quill/getting-started/assets/adding-a-web-widget-channel_new-channel.png b/quill/getting-started/assets/adding-a-web-widget-channel_new-channel.png new file mode 100644 index 0000000000..f5a258d9d0 Binary files /dev/null and b/quill/getting-started/assets/adding-a-web-widget-channel_new-channel.png differ diff --git a/quill/getting-started/assets/adding-a-chat-widget_overview.png b/quill/getting-started/assets/adding-a-web-widget-channel_overview.png similarity index 100% rename from quill/getting-started/assets/adding-a-chat-widget_overview.png rename to quill/getting-started/assets/adding-a-web-widget-channel_overview.png diff --git a/quill/getting-started/assets/adding-a-web-widget-channel_widget-in-page.png b/quill/getting-started/assets/adding-a-web-widget-channel_widget-in-page.png new file mode 100644 index 0000000000..6fba63cfae Binary files /dev/null and b/quill/getting-started/assets/adding-a-web-widget-channel_widget-in-page.png differ diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_add-a-channel-stage.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_add-a-channel-stage.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_add-a-channel-stage.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_add-a-channel-stage.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_add-channel-menu.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_add-channel-menu.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_add-channel-menu.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_add-channel-menu.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_channel-created.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_channel-created.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_channel-created.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_channel-created.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_generate-link.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_generate-link.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_generate-link.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_generate-link.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_generate-link_parameter.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_generate-link_parameter.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_generate-link_parameter.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_generate-link_parameter.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_link-minted.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_link-minted.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_link-minted.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_link-minted.snagx diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_new-channel.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_new-channel.snagx similarity index 77% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_new-channel.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_new-channel.snagx index 517e79d590..29d4066d58 100644 Binary files a/quill/getting-started/assets/snagit/adding-a-chat-widget_new-channel.snagx and b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_new-channel.snagx differ diff --git a/quill/getting-started/assets/snagit/adding-a-chat-widget_overview.snagx b/quill/getting-started/assets/snagit/adding-a-web-widget-channel_overview.snagx similarity index 100% rename from quill/getting-started/assets/snagit/adding-a-chat-widget_overview.snagx rename to quill/getting-started/assets/snagit/adding-a-web-widget-channel_overview.snagx diff --git a/quill/getting-started/overview.mdx b/quill/getting-started/overview.mdx index f7da0fe499..c0606dcfed 100644 --- a/quill/getting-started/overview.mdx +++ b/quill/getting-started/overview.mdx @@ -2,7 +2,7 @@ title: "Getting started: Overview" sidebar_label: Overview sidebar_position: 1 -description: "The map of the Getting Started path: the steps from signing up for Quill to a chat widget answering your users from Quill's live copy of your SQL data, and the things to prepare before you start." +description: "The map of the Getting Started path: the steps from signing up for Quill to a chat box answering your users from Quill's live copy of your SQL data, and the things to prepare before you start." --- import Admonition from '@theme/Admonition'; @@ -12,14 +12,14 @@ import ContentFrame from "@site/src/components/ContentFrame"; # Getting started: Overview -* The **Getting Started** section takes you from signing up for Quill to a **chat widget** - on your site, where your users ask and your AI agent answers from Quill's live copy of your SQL data. +* The **Getting Started** section takes you from signing up for Quill to a **chat box** + on your website, where your users ask and your AI agent answers from Quill's live copy of your SQL data. This page presents [the Getting Started steps](#the-getting-started-steps) and [the things to prepare](#prerequisites) before you start. * The configuration steps run in wizards that save you the manual work: Quill drafts the mapping of your data, the agent, and the agent's queries, and you approve or adjust each draft. -* The chat widget is one of several channel types Quill offers, all carrying conversations between your +* The web widget is one of several channel types Quill offers, all carrying conversations between your users and an agent. You can also add a Telegram bot, a Slack app, or a Discord bot. * Terms like [mirroring](../overview.mdx#mirroring), [agents](../overview.mdx#ai-agent), and [channels](../overview.mdx#channels) are @@ -43,7 +43,7 @@ Before taking the first step, make sure you have: * **A machine that will run Quill.** * The machine needs **Docker** installed: Docker Desktop on Windows and macOS, or Docker Engine on Linux. * Port `443` must be available: the dashboard, the API, and the chat channels of your deployment are all - [served on this one port](../security-and-architecture/network-architecture.mdx#publish-only-port-443). + [served on this one port](../security-and-architecture/network-architecture.mdx#how-a-connection-is-routed). * Quill's machine needs internet access: Docker pulls Quill's image from Docker Hub, and Quill fetches the [certificate and configuration](../security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate) for your domain from `api.ravendb.net`. @@ -94,10 +94,10 @@ management dashboard. of your own, and chat with the draft agent before saving it. *Your app has an agent that answers from its internal database.* -6. **[Adding a chat widget](../getting-started/adding-a-chat-widget.mdx)** - Create a **Web widget** channel for the agent, generate an **embed link** for the channel, and place - the widget on a page of your site. - *Your users can reach the agent through a chat widget on your website.* +6. **[Adding a web widget channel](../getting-started/adding-a-web-widget-channel.mdx)** + Create a **web widget** channel for the agent, generate an **embed link** for the channel, and place + the chat box on a page of your website. + *Your users can reach the agent through a chat box on your website.* diff --git a/quill/getting-started/signing-up.mdx b/quill/getting-started/signing-up.mdx index 8e7db4ab53..d7d2de2cb5 100644 --- a/quill/getting-started/signing-up.mdx +++ b/quill/getting-started/signing-up.mdx @@ -13,7 +13,7 @@ import ContentFrame from "@site/src/components/ContentFrame"; The **[Getting Started](../getting-started/overview.mdx#the-getting-started-steps)** section takes you from the initial signing up -for Quill to an AI agent answering your users through your first channel: a chat widget on your site. **Signing up** is the first step. +for Quill to an AI agent answering your users through your first channel: a web widget channel with a chat box on your website. **Signing up** is the first step. diff --git a/quill/getting-started/starting-quill.mdx b/quill/getting-started/starting-quill.mdx index 089b86f811..3e949ce102 100644 --- a/quill/getting-started/starting-quill.mdx +++ b/quill/getting-started/starting-quill.mdx @@ -48,7 +48,7 @@ Before starting Quill, make sure you have: * Docker Desktop on Windows and macOS, or Docker Engine on Linux. * **Port 443 available** on Quill's machine. * The dashboard, the API, and the chat channels of your deployment are all - [served on this one port](../security-and-architecture/network-architecture.mdx#publish-only-port-443). + [served on this one port](../security-and-architecture/network-architecture.mdx#how-a-connection-is-routed). * **Internet access** from Quill's machine to Docker Hub and to `api.ravendb.net`. * Docker pulls [Quill's image](https://hub.docker.com/r/ravendb/quill-nightly) from Docker Hub. * Quill fetches the [certificate and configuration](../security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate) diff --git a/quill/home.mdx b/quill/home.mdx index 11e140e859..79ca1288cf 100644 --- a/quill/home.mdx +++ b/quill/home.mdx @@ -12,7 +12,7 @@ pagination_prev: null wrapperClassName: quillHomePage hide_title: true hide_table_of_contents: true -description: "Quill gives your PostgreSQL, SQL Server, or MySQL database an AI agent that answers your users from a live copy of your data, through a chat widget on your site or a Telegram, Slack, or Discord bot. Start here." +description: "Quill gives your PostgreSQL, SQL Server, or MySQL database an AI agent that answers your users from a live copy of your data, through a chat box on your website or a Telegram, Slack, or Discord bot. Start here." --- import QuillHero from "@site/src/components/Quill/QuillHero"; @@ -22,7 +22,7 @@ import CardWithIcon from "@site/src/components/Common/CardWithIcon"; } @@ -53,7 +53,7 @@ import CardWithIcon from "@site/src/components/Common/CardWithIcon"; { icon: "notifications", title: "Channels", - description: "A chat widget on your site, or a Telegram, Slack, or Discord bot, carries the conversations between your users and your agents.", + description: "A web widget channel with a chat box on your website, or a Telegram, Slack, or Discord bot, carries the conversations between your users and your agents.", url: "/quill/overview#channels", }, ]} @@ -73,7 +73,7 @@ import CardWithIcon from "@site/src/components/Common/CardWithIcon"; * Databases like PostgreSQL, SQL Server, and MySQL lack AI capabilities that could greatly improve user experience. - For example, a company that runs one of these databases may want to offer its website visitors a chat widget that answers + For example, a company that runs one of these databases may want to offer its website visitors a chat box that answers their questions using the company's live data. - To accomplish this, the company would have to either build the chat widget interface from scratch, an effort that requires + To accomplish this, the company would have to either build the chat box from scratch, an effort that requires expertise in AI, databases, and security, or migrate to a database that already offers such capabilities, a major undertaking as well. **Quill** is a ready-made alternative that spares you both efforts: it runs as a service in a Docker container beside your - database, reads your live data using access details you provide, and publishes AI interfaces (like the chat widget mentioned + database, reads your live data using access details you provide, and publishes AI interfaces (like the chat box mentioned above) that offer your users the AI experience you want to incorporate. Your data, your workflows, and your applications remain unchanged. @@ -31,7 +31,7 @@ import ContentFrame from "@site/src/components/ContentFrame"; * Getting Quill running is a [guided process](getting-started/overview.mdx), from the sign-up page, through a setup wizard, to a working AI interface for your users. Once this process is complete, day-to-day management is done using Quill's dashboard, including changes to the mirrored - data and to the user-facing side, like the chat widget, as well as usage and license tracking. + data and to the user-facing side, like the chat box, as well as usage and license tracking. * In this article: * [What Quill is](#what-quill-is) @@ -52,11 +52,11 @@ Quill is a complete AI service for your PostgreSQL, SQL Server, or MySQL databas Quill's Docker container includes everything Quill runs: -* The machinery that mirrors your source database's tables -* An internal database that holds the mirrored data -* AI agents that talk with your users, query the mirrored data, and compose the replies -* The channels that carry the conversations, like the chat widget on your site -* Quill's management dashboard +* The machinery that mirrors your source database's tables. +* An internal database that holds the mirrored data. +* AI agents that talk with your users, query the mirrored data, and compose the replies. +* The channels that carry the conversations, like a web widget channel with a chat box on your website. +* Quill's management dashboard. @@ -127,16 +127,16 @@ Parts of the Quill service and the data flow between them: * Each channel is bound to a single agent. * An agent can serve several channels at once. -#### Chat widget +#### Web widget -* A chat widget is a **Web widget** channel, embedded in a page of your site. -* Several chat widgets can serve your site, each carrying conversations to its own agent (e.g., a product assistant on +* A **web widget** is a channel that opens to a chat box on your website page. +* Several web widget channels can serve your website, each carrying conversations to its own agent (e.g., a product assistant on the catalog page, and a support assistant on the orders page). #### Your users -* Users need no account with Quill and no knowledge of it: they simply type questions into a channel, like the chat - widget on your site, and get the +* Users need no account with Quill and no knowledge of it: they simply type questions into a channel, like the chat box + on your website, and get the agent's replies in return. #### LLM @@ -153,14 +153,15 @@ Parts of the Quill service and the data flow between them: ### Answering questions -Each exchange between a user and an agent starts at a channel, like the chat widget on your site, and is answered with -data from the mirrored database, a full RavenDB database running inside the Docker container. +Each exchange between a user and an agent starts at a channel, like a web widget with a chat box on your website, +and is answered with data from the mirrored database, a full RavenDB database running inside the Docker container. -* When a user types a question in the chat widget, the agent queries Quill's internal database for the data the answer needs. -* The agent passes the query results to the LLM, and the LLM phrases the reply. -* The reply returns to the user's chat widget. - Your SQL database takes no part in answering. -* Quill keeps each chat as a conversation: the full exchange between the user and the agent is available in the dashboard. +* When a user enters a question, the channel carries the question to the agent, which forwards it to the LLM. +* While the LLM composes a reply, it may request the agent to query Quill's internal database for data the reply needs. + The agent queries the database, and passes the results to the LLM. + When the final reply is ready, the LLM returns it to the agent, which passes it to the user over the channel. +* Your SQL database takes no part in answering. +* Quill keeps all the conversations held by its agents, and you can inspect them in the dashboard's [Conversations view](dashboard/manage-an-app/conversations-view.mdx). @@ -182,13 +183,13 @@ data from the mirrored database, a full RavenDB database running inside the Dock Keeping Quill secure is part of the package: at sign-up, Quill receives its own web address and [TLS certificates](security-and-architecture/network-architecture.mdx#the-tls-front-and-the-wildcard-certificate), -so its management dashboard and the [chat widget](#chat-widget) it runs are served over HTTPS from the +so its management dashboard and the [chat boxes](#web-widget) it serves are served over HTTPS from the moment Quill first starts, with no certificate handling on your side. * Quill reaches [your SQL database](#your-sql-database) using the access details you provide; your data is only read, never modified. -* Chat widget pages are [the only public part of the service](security-and-architecture/network-architecture.mdx#what-is-public). -* A chat widget page is reached through an **embed link** you place in your page. +* Chat box pages are [the only public part of the service](security-and-architecture/network-architecture.mdx#what-is-public). +* A chat box is reached through an **embed link** you place in your page. Each link expires, serves a limited number of exchanges, and [can be revoked at any time](developer-access/embed-the-chat-widget.mdx#lifetime-usage-cap-and-revocation). * Quill's management dashboard requires the @@ -242,10 +243,10 @@ The road from sign-up to a working AI interface: 6. **Channel creation** *The agent goes live.* - You create a **channel** that carries the conversations between your users and the agent: a [chat widget](getting-started/adding-a-chat-widget.mdx) - on your site, a Telegram bot, a Slack app, or a Discord bot. - For a chat widget channel, for example, you generate an **embed link**; placed in a page of - your site, the link will display the widget, live and answering from the mirrored data. + You create a **channel** that carries the conversations between your users and the agent: a [web widget](getting-started/adding-a-web-widget-channel.mdx) channel + with a chat box on your website, a Telegram bot, a Slack app, or a Discord bot. + For a web widget channel, for example, you generate an **embed link**; placed in a page of + your website, the link will display the chat box, live and answering from the mirrored data. @@ -305,10 +306,10 @@ Developers can work with Quill using code as well as through the management dash ```
-* **[Embedding the chat widget](developer-access/embed-the-chat-widget.mdx)** +* **[Embedding the chat box](developer-access/embed-the-chat-widget.mdx)** * Quill delivers each embed link as a ready-made HTML segment. * A developer can add this segment to the code of any of your site's pages; the page will then display the chat - widget. + box. * The embed segment, as Quill delivers it: ```html diff --git a/scripts/redirects.json b/scripts/redirects.json index 620a3fd10d..e49294d400 100644 --- a/scripts/redirects.json +++ b/scripts/redirects.json @@ -1186,5 +1186,11 @@ "targetUrl": "/integrations/connection-strings/per-database/remove-connection-string", "minimumVersion": "7.2" } + }, + { + "key": "/quill/getting-started/adding-a-chat-widget", + "value": { + "targetUrl": "/quill/getting-started/adding-a-web-widget-channel" + } } ]