Quill troubleshooting and FAQ pages

quill/channels/embedded-chat.mdx

@@ -697,68 +697,185 @@ The **Customize appearance** tab holds the chat widget's theme: its colors, styl
 
 <Panel heading="Troubleshooting">
 
-<Admonition type="note" title="">
-
 Symptoms met by the users of every channel type are listed in the channels overview, in
 [Troubleshooting](../channels/overview.mdx#troubleshooting).
 
+The symptoms below are shown by an embedded chat channel when something goes wrong, each with its likely cause and what to do about it.  
+
+---
+
+### In the dashboard
+
+<ContentFrame>
+
+##### An allowed origin is refused
+
+Creating or saving the channel fails with `is not an origin (scheme+host[:port] only)`.
+
+<Admonition type="note" title="">
+
+**Cause:** an **Allowed origins** entry carries more than the website's address, 
+e.g., a page path (`https://shop.example.com/help`).
+
 </Admonition>
 
-The symptoms below are shown by an embedded chat channel when something goes wrong, each with its likely cause and what to do about it.  
+**What to do:** enter the website's address only (`https://shop.example.com`), as described in
+[Filling in the channel form](#filling-in-the-channel-form).
+
+</ContentFrame>
 
 <ContentFrame>
 
-### In the dashboard
+##### The `*` wildcard is refused
 
-* **Creating or saving the channel fails with "is not an origin (scheme+host[:port] only)".**  
-  Likely cause: an **Allowed origins** entry carries more than the website's address, 
-  e.g., a page path (`https://shop.example.com/help`).  
-  What to do: enter the website's address only (`https://shop.example.com`), as described in
-  [Filling in the channel form](#filling-in-the-channel-form).
-* **Creating or saving the channel fails with "wildcard '*' is not an allowed origin".**  
-  Likely cause: `*` was entered in **Allowed origins** to permit every website.  
-  What to do: leave the list empty to permit every website, or list each website by its address.
-* **The `New embedded chat channel` form shows "Create an agent first" instead of its fields.**  
-  Likely cause: the app has no agent yet.  
-  What to do: add an agent, as described in [Prerequisites](#prerequisites), and then add the channel.
-* **The `Generate link` button is disabled.**  
-  Likely cause: the channel is paused.  
-  What to do: resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel).
+Creating or saving the channel fails with `wildcard '*' is not an allowed origin`.
+
+<Admonition type="note" title="">
+
+**Cause:** `*` was entered in **Allowed origins** to permit every website.
+
+</Admonition>
+
+**What to do:** leave the list empty to permit every website, or list each website by its address.
 
 </ContentFrame>
 
 <ContentFrame>
 
+##### The channel form asks to create an agent first
+
+The `New embedded chat channel` form shows `Create an agent first` instead of its fields.
+
+<Admonition type="note" title="">
+
+**Cause:** the app has no agent yet.
+
+</Admonition>
+
+**What to do:** add an agent, as described in [Prerequisites](#prerequisites), and then add the channel.
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### The `Generate link` button is disabled
+
+<Admonition type="note" title="">
+
+**Cause:** the channel is paused.
+
+</Admonition>
+
+**What to do:** resume the channel, as described in [Pausing and deleting the channel](#pausing-and-deleting-the-channel).
+
+</ContentFrame>
+
+---
+
 ### On your website page
 
-* **The chat widget does not appear: the `<iframe>` element remains empty, or shows a browser message that the page cannot be displayed.**  
-  Likely cause: the website is not in the channel's **Allowed origins** list, or is listed with a different scheme or port
-  (e.g., `http://` where the site is served over `https://`, or `http://localhost` without the port the site runs on).  
-  What to do: add the website's exact address to the list, as described in
-  [Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins).
-* **A question is answered with "Something went wrong. Please try again. (HTTP 403)".**  
-  Likely cause: the website was removed from the channel's **Allowed origins** list after the page loaded the chat widget.  
-  What to do: add the website's address back to the list, as described in
-  [Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins).
-* **The chat widget is replaced by a notice, or a question is answered with a notice, that the conversation has ended,
-  is not available, is no longer active, or has reached its usage limit.**  
-  Likely cause: the embed link is no longer valid. The cause behind each notice is given in [Invalid links](#invalid-links).  
-  What to do: generate a new embed link and place it in the page instead of the invalid link, as described in
-  [Placing the embed snippet on your page](#placing-the-embed-snippet-on-your-page); if the channel is paused, resume it.
-* **A question is answered with "Too many requests right now. Please try again in a moment."**  
-  Likely cause: more than 60 questions were sent within a minute from the user's IP address, typically because users behind 
-  a shared address, like a company network, are counted together. See [Embedded chat channel limitations](#embedded-chat-channel-limitations).  
-  What to do: advise the user to wait a moment and send the question again.
-* **A question is answered with "the value bound for parameter '...' is not a valid ...".**  
-  Likely cause: a value bound into the embed link does not match an agent parameter's type, e.g., because the type was changed in
-  the agent after the link was generated.  
-  What to do: generate a new embed link with a valid value, as described in [Binding agent parameters](#binding-agent-parameters).
-* **A question is answered with "Chat failed. See server logs for details."**  
-  Likely cause: the agent failed to produce the answer, e.g., because the LLM service or the app's database could not be reached,
-  or because the agent has a parameter that the link does not bind (a parameter added to the agent after the link was generated).  
-  What to do: verify that the LLM service behind the agent's AI connection string can be reached, as described in
-  [Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection); if the agent's
-  parameters were changed, generate a new embed link. The server logs name the exact error.
+<ContentFrame>
+
+##### The chat widget does not appear
+
+The chat widget does not appear: the `<iframe>` element remains empty, or shows a browser message that the page cannot be displayed.
+
+<Admonition type="note" title="">
+
+**Likely cause:** the website is not in the channel's **Allowed origins** list, or is listed with a different scheme or port
+(e.g., `http://` where the site is served over `https://`, or `http://localhost` without the port the site runs on).
+
+</Admonition>
+
+**What to do:** add the website's exact address to the list, as described in
+[Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins).
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### A question is answered with an HTTP 403 error
+
+A question is answered with `Something went wrong. Please try again. (HTTP 403)`.
+
+<Admonition type="note" title="">
+
+**Likely cause:** the website was removed from the channel's **Allowed origins** list after the page loaded the chat widget.
+
+</Admonition>
+
+**What to do:** add the website's address back to the list, as described in
+[Editing the channel name and allowed origins](#editing-the-channel-name-and-allowed-origins).
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### The chat widget reports that the conversation has ended
+
+The chat widget is replaced by a notice, or a question is answered with a notice, that the conversation has ended, is not available, is no longer active, or has reached its usage limit.
+
+<Admonition type="note" title="">
+
+**Cause:** the embed link is no longer valid. The cause behind each notice is given in [Invalid links](#invalid-links).
+
+</Admonition>
+
+**What to do:** generate a new embed link and place it in the page instead of the invalid link, as described in
+[Placing the embed snippet on your page](#placing-the-embed-snippet-on-your-page); if the channel is paused, resume it.
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### The chat widget reports too many requests
+
+A question is answered with `Too many requests right now. Please try again in a moment.`
+
+<Admonition type="note" title="">
+
+**Cause:** more than 60 questions were sent within a minute from the user's IP address, typically because users behind 
+a shared address, like a company network, are counted together. See [Embedded chat channel limitations](#embedded-chat-channel-limitations).
+
+</Admonition>
+
+**What to do:** advise the user to wait a moment and send the question again.
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### A bound parameter value is not valid
+
+A question is answered with `the value bound for parameter '...' is not a valid ...`.
+
+<Admonition type="note" title="">
+
+**Cause:** a value bound into the embed link does not match an agent parameter's type, e.g., because the type was changed in
+the agent after the link was generated.
+
+</Admonition>
+
+**What to do:** generate a new embed link with a valid value, as described in [Binding agent parameters](#binding-agent-parameters).
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### The chat fails
+
+A question is answered with `Chat failed. See server logs for details.`
+
+<Admonition type="note" title="">
+
+**Likely cause:** the agent failed to produce the answer, e.g., because the LLM service or the app's database could not be reached,
+or because the agent has a parameter that the link does not bind (a parameter added to the agent after the link was generated).
+
+</Admonition>
+
+**What to do:** verify that the LLM service behind the agent's AI connection string can be reached, as described in
+[Dashboard: AI connection strings](../dashboard/ai-connection-strings.mdx#test-and-save-the-connection); if the agent's
+parameters were changed, generate a new embed link. The server logs name the exact error.
 
 </ContentFrame>
 

quill/channels/overview.mdx

@@ -117,7 +117,8 @@ 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:
-   * An embedded chat channel is reached by any visitor to a website page that holds one of the channel's embed links.
+   * An embedded chat channel is reached by any website visitor or mobile app user who opens a chat widget using 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.
@@ -140,7 +141,7 @@ Agent parameters are bound by the channel, and the source of a parameter's value
      chat.  
      A Telegram user can make the agent forget sooner by sending `/clear`; Slack and Discord users cannot.
    * In an embedded chat channel, the conversation belongs to the embed link that opened the chat widget, and lasts as long as the link is valid:
-     all website visitors who open the chat widget through the same link share the same conversation, which ends when 
+     all users who open the chat widget through the same link share the same conversation, which ends when 
      the link [expires, reaches its maximum number of prompts, or is revoked](../channels/embedded-chat.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
@@ -169,34 +170,72 @@ Agent parameters are bound by the channel, and the source of a parameter's value
 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**
-
-* **The bot does not reply to a photo or a file, or replies "I can only read text messages right now."**  
-  Likely cause: the bots answer text-only messages, as stated in
-  [Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels), and the user's message may
-  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.
-* **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.
-
-**In a channel of any type**
-
-* **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](#behavior-and-limitations-common-to-all-channels).
+---
+
+### In a chat with a Telegram, Slack, or Discord bot
+
+<ContentFrame>
+
+##### The bot does not reply to a photo or a file
+
+The bot does not reply to a photo or a file, or replies `I can only read text messages right now.`
+
+<Admonition type="note" title="">
+
+**Likely cause:** the bots answer text-only messages, as stated in
+[Behavior and limitations common to all channels](#behavior-and-limitations-common-to-all-channels), and the user's message may
+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.
+
+</Admonition>
+
+**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.
+
+</ContentFrame>
+
+<ContentFrame>
+
+##### The bot asks to resend a message
+
+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.`
+
+<Admonition type="note" title="">
+
+**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).
+
+</Admonition>
+
+**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.
+
+</ContentFrame>
+
+---
+
+### In a channel of any type
+
+<ContentFrame>
+
+##### The agent answers from outdated information
+
+<Admonition type="note" title="">
+
+**Likely cause:** one of the following may have happened.
+
+</Admonition>
+
+* 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](#behavior-and-limitations-common-to-all-channels).
+
+</ContentFrame>
 
 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](../channels/telegram.mdx#troubleshooting),