SmartQueue Chat guide

This manual explains how to use SmartQueue Chat in the real product: the website widget your visitors see and the Chat portal your team uses to configure the bot, approve content, control safety rules, and review conversations.

Use this guide when you are preparing Chat for a website, updating the bot's answers, reviewing escalated conversations, or troubleshooting why the widget is not behaving as expected.

1) What SmartQueue Chat does

SmartQueue Chat is a controlled website chat assistant. It answers visitor questions from approved content, follows your workflow rules, and hands off to a person when a request is sensitive, unsupported, unclear, or outside the bot's allowed scope.

The important product rule is simple: Chat should help visitors quickly, but it should not invent policies, prices, account decisions, legal answers, or commitments that your team has not approved.

Chat is connected to the same SmartQueue organization as Email and SmartHub:

• You use the same SmartQueue account.
• Chat usage counts with the same contact allowance as Email.
• Approved replies can be shared across Email, Chat, and SmartHub.
• Escalated or imported chat conversations can be reviewed from SmartHub when sync is enabled.

2) Before you go live

Complete this checklist before adding the widget to a production website:

1. Confirm the organization is active and billing is active.
2. Open Chat from the SmartQueue portal.
3. Confirm you are in the correct organization.
4. Add the website URL that is allowed to use the widget.
5. Copy the widget code from Website Widget.
6. Add enough approved replies to cover the questions visitors will actually ask.
7. Add workflow rules for requests that must be escalated or answered with a fixed message.
8. Set the widget title, opening greeting, fallback reply, and escalation reply.
9. Test on a staging or hidden page before publishing widely.
10. Send several realistic visitor questions and verify the bot answers, escalates, or resolves correctly.

3) Access and organization selection

Typical access:

• Main login: https://app.smartq.ca
• Chat portal: https://app.smartq.ca/portal/chat

SmartQueue opens Chat through a signed launch flow from the main account. In normal customer use, you should not need a separate Chat password.

When the Chat portal opens:

1. Check the organization shown in the sidebar.
2. Confirm the workspace status is active.
3. Confirm the top links to Email, SmartHub, or Admin Hub point to the expected workspace.
4. If you manage more than one organization, select the correct organization before editing anything.

If the portal says the account is pending activation, the organization exists but is not live yet. Contact SmartQueue support or an administrator before installing the widget.

4) Portal layout

The Chat portal is organized around the real work of operating website chat:

• Overview: organization status, active/paused state, widget readiness, chat counts, escalated chats, resolved chats, and contact usage.
• Business Instructions: agent and supervisor prompts for tone and safety review.
• Website Widget: allowed website URLs, widget readiness, and copyable script code.
• Bot Settings: visitor-facing text in the chat widget.
• Workflow Rules: business rules that run before normal answer generation.
• Approved Replies: safe answers the bot is allowed to reuse.
• Conversations: recent chat threads, status, visitor details, message counts, and transcript review.

Some platform-only sections, such as channels, escalation email, filters, raw prompt layers, key inventory, retention purge, or tenant creation, may be hidden from normal customer users. If you do not see those sections, that is expected.

5) Overview

Use Overview as the first health check.

Look for:

• Name / Slug: confirms the organization you are editing.
• Status: active means Chat can run; paused means it should not serve live visitors.
• Widget: ready only when the key, channel, and website are set.
• Plan usage: Email contacts and Chat conversations share the same plan allowance.
• Open / escalated / resolved counts: helps you see whether conversations are being handled or waiting for review.

If the widget is not ready, finish Website Widget setup before publishing.

6) Business Instructions

Business Instructions control how the bot behaves beyond the approved replies.

There are two main fields:

• Agent Prompt: tone, answer style, and what the bot should or should not say.
• Supervisor Prompt: stricter review instructions used before sending or accepting an answer.

Use Business Instructions for behavior, not facts.

Good Agent Prompt examples:

• "Use a concise, friendly tone. Ask one clarifying question if the visitor's request is incomplete."
• "Answer in the same language as the visitor when possible."
• "Do not mention internal systems, ticket IDs, or implementation details."

Good Supervisor Prompt examples:

• "Escalate billing disputes, cancellation requests, legal questions, security questions, and angry complaints."
• "Reject any answer that invents prices, implementation timelines, integrations, or contractual commitments."

Do not put your full pricing table, policies, or product FAQ only in prompts. Put customer-facing facts in Approved Replies so they can be managed and audited.

7) Website Widget setup

Website Widget is where you authorize the customer website and copy the install code.

The setup status shows three checks:

• Key: the widget has an active public widget key.
• Channel: a website chat channel exists and is enabled.
• Website: at least one active website URL is allowed.

7.1 Add the website URL

1. Open Website Widget.
2. In Website URL, enter the exact website origin, for example https://www.example.com.
3. Keep Active checked.
4. Select Allow Website.
5. Confirm the website appears in the allowed website list.

Use the origin only:

• Good: https://www.example.com
• Good: https://example.com
• Avoid: https://www.example.com/contact
• Avoid: www.example.com without https://

Public websites should use HTTPS.

7.2 Copy and install the widget code

1. Select Copy Code.
2. Paste the code into the website template, normally before the closing </body> tag.
3. Put it on every page where the chat bubble should appear.
4. Publish the page.
5. Hard refresh the website and confirm the chat bubble appears.

The snippet looks like this:

<script
  src="https://YOUR_CHAT_HOST/static/widget.js"
  data-smartqueue-embed-key="YOUR_PUBLIC_EMBED_KEY"
  data-smartqueue-channel-id="YOUR_CHANNEL_ID"
  data-smartqueue-title="SmartQueue"
  defer>
</script>

Do not manually edit the embed key unless SmartQueue support tells you to. The key is public, but it should match the current code copied from the portal.

7.3 When to use Generate Key

Most customers should use Copy Code and avoid key management.

Use Generate Key only when:

• the widget has no key yet,
• SmartQueue support asks you to rotate the widget key,
• a previous key was exposed in the wrong place, or
• you are setting up a new authorized website for the same organization.

After generating a new key, copy the widget code again and update the website.

8) Bot Settings

Bot Settings controls the visitor-facing text in the widget. It does not replace Approved Replies.

Fields:

• Widget Title: the title in the chat header, such as your company name.
• Opening Greeting: first message after the visitor enters name/email. You can use {name}.
• AI Fallback Reply: message used when the system cannot produce a safe answer.
• Escalation Reply: message shown when the conversation is handed off to a human.

Recommended examples:

• Widget Title: SmartQueue
• Opening Greeting: Thanks, {name}. What can I help you with today?
• AI Fallback Reply: I can help with SmartQueue questions here. What would you like to solve?
• Escalation Reply: I am sending this conversation to the team for follow-up.

After editing, select Save Bot.

9) Approved Replies

Approved Replies are the safest way to teach Chat what it may answer.

Each reply has:

• Case Name: a unique internal name, such as EN_01_Pricing_Question.
• Folder: a category, such as Pricing, Setup, or Security.
• Language: English, Spanish, or French.
• Answer: the approved answer text.
• Active: whether the answer can be used.

9.1 Add a reply

1. Open Approved Replies.
2. Select Add New Approved Reply.
3. Enter a clear case name.
4. Choose or type a folder.
5. Choose the language.
6. Write the approved answer.
7. Keep Active checked.
8. Select Save Approved Reply.

Write approved replies as real customer-facing answers. Include exact facts, plan limits, links, policies, setup steps, or escalation instructions your team has approved.

9.2 Edit a reply

1. Find the reply in the list.
2. Select Edit.
3. Update the answer, folder, language, or active state.
4. Select Save Approved Reply.

If you change a policy, price, or process, update the approved reply first. Do not rely on a prompt to override stale approved content.

9.3 Import or export Excel

Use Download Excel to export the current Chat approved replies.

Use Upload Excel to import a prepared approved-replies spreadsheet. The expected columns are:

• source
• case_name
• language
• folder
• answer
• active

After import, test a few common questions to confirm the answers are being found.

9.4 Approved Reply Source

SmartQueue allows one active approved-response library at a time:

• Email approved responses
• Chat approved responses
• SmartHub approved responses

Only one source should be selected. This prevents the bot from mixing conflicting answer libraries.

Use Chat as the source when the website chat should have its own curated website-specific answers. Use Email or SmartHub when the organization wants one shared answer library across channels.

10) Workflow Rules

Workflow Rules run before normal answer generation. Use them for situations where the bot must follow a specific business decision.

Fields:

• Rule Key: stable lowercase identifier, such as pricing_or_contracts.
• Name: human-readable label.
• Action: what happens when the rule matches.
• Instruction: natural-language condition and handling.
• Reply Template: optional fixed response.
• Enabled: whether the rule is active.

Available actions:

• Reply With Template: send the fixed reply template.
• Escalate: hand off to a human.
• Hold For Review: do not send an answer automatically.
• Resolve: close the conversation when no visitor-facing reply is needed.
• Continue: let normal Chat generation continue.

Good uses for workflow rules:

• Escalate cancellation, refund, legal, security, billing dispute, or account-change requests.
• Reply with a fixed message for out-of-scope topics.
• Hold for review when a visitor asks for a commitment your team must verify.
• Resolve a thread when the visitor confirms the issue is solved.

Example escalation rule:

• Rule Key: billing_disputes
• Name: Billing disputes
• Action: Escalate
• Instruction: If the visitor disputes a charge, asks for a refund, threatens legal action, or asks to cancel, escalate to a human.
• Reply Template: I am sending this to the team so they can review your account and follow up.

11) Conversations

The Conversations section shows recent website chat threads.

The list includes:

• Status
• Contact name/email when available
• Visitor ID
• Channel
• Message count
• Last updated time

Open a conversation to see the transcript. Messages are shown by direction, such as visitor/user and bot.

Common statuses:

• open: active conversation or still unresolved.
• escalated: needs a human.
• resolved: marked solved.
• closed: closed/archived where available.

Actions available in the detail panel:

• Mark Open: reopen or keep a conversation active.
• Resolve: mark the conversation resolved.
• Close: close the detail panel.

Review escalated conversations regularly. If Chat escalates often for the same topic, add or improve approved replies or workflow rules.

12) What visitors experience

When the widget is installed correctly:

1. A chat bubble appears on the website.
2. The visitor opens the widget.
3. The visitor enters a name/email when prompted.
4. Chat shows the opening greeting.
5. The visitor asks a question.
6. SmartQueue checks the tenant, website origin, channel, approved replies, workflow rules, and safety review.
7. The bot replies, escalates, resolves, or asks for more information.
8. The conversation is stored for review in the portal.

If a visitor asks for a human, uses a sensitive topic, or asks something unsupported, Chat should escalate instead of guessing.

13) Billing and usage

Live Chat requires an active organization/subscription.

Usage is counted as contacts:

• One Email case counts as one contact.
• One Chat conversation counts as one contact.
• Email and Chat share the same plan allowance.

If the plan limit is reached or billing is inactive, Chat may be paused or restricted until the subscription is fixed.

14) Best practices

• Start with 20 to 40 strong approved replies covering the most common website questions.
• Put hard facts in Approved Replies, not only in prompts.
• Use Workflow Rules for topics that must always escalate.
• Keep Bot Settings short and visitor-friendly.
• Add both https://example.com and https://www.example.com if the website uses both.
• Test in English, Spanish, and French if those languages are supported by your replies.
• Review escalations weekly and turn repeated safe answers into approved replies.
• Update approved replies before publishing new prices, policies, or product commitments.

15) Troubleshooting

The chat bubble does not appear:

• Confirm the widget code is on the page.
• Confirm the page includes the script before </body>.
• Confirm the script URL loads in the browser.
• Confirm the website URL is allowed in Website Widget.
• Add both root and www origins if needed.
• Hard refresh the website or clear cache.

The bubble appears but messages fail:

• Confirm the website origin is active.
• Confirm the copied code has the current embed key and channel ID.
• Confirm the organization is active.
• Confirm the website chat channel is enabled.
• Check whether an ad blocker or security plugin is blocking the script.

The bot escalates too much:

• Add approved replies for repeated safe questions.
• Check whether a workflow rule is forcing escalation.
• Check Business Instructions for overly strict supervisor wording.
• Confirm the correct Approved Reply Source is selected.

The bot answers from old information:

• Edit the approved reply containing the old information.
• If using Excel import, upload the latest spreadsheet.
• Confirm only one approved-reply source is active.
• Test again after saving.

The bot gives the fallback reply:

• The request may not match approved content.
• The backend may not have produced a safe answer.
• Add a clearer approved reply or workflow rule for that topic.

The widget works on staging but not production:

• Add the production website origin.
• Confirm production uses HTTPS.
• Confirm the production page uses the latest script snippet.
• Check whether production has a different domain, subdomain, or www version.

Changes are not visible:

• Confirm you saved the correct section.
• Confirm you are in the correct organization.
• Reload the Chat portal.
• Hard refresh the website page where the widget is installed.

16) When to use SmartHub

Use SmartHub when a conversation needs human review, team follow-up, reporting, or operational handling beyond the Chat portal.

Chat is best for configuring the website widget and reviewing recent chat transcripts. SmartHub is best for team inbox work, escalations, notes, reports, and broader operational review.