Visual step-by-step manual

sem.chat documentation

A screenshot-backed SEMJAT manual built from the real sem.chat dashboard flow. Each guide tells you what to click, what should happen after the click, how to test it, how to troubleshoot it, and what to do next.

No matching guides found. Try a shorter keyword such as widget, API, voice, billing, webhook, WordPress, SendPulse, or scheduling.
Screenshot note: every visual in this manual was captured from the real sem.chat app using a demo workspace. Sensitive account details, customer data, API keys, payment details, and private conversation content are masked before publishing.
01

Getting Started

Create the account, finish onboarding, understand the dashboard, create the first bot, test it privately, install it, and choose the right plan.

/authSignup, trial, and first bot
Real sem.chat demo workspace screenshot of signup, onboarding, and trial setup
1Start with Sign Up or Sign In from the public site or app.
2Verify the email address before relying on notifications or billing messages.
3Use onboarding to create the first bot before opening the dashboard.
/overviewOverview after login
Real sem.chat demo workspace screenshot of the Overview dashboard
1Use quick actions to create a bot, view bots, open analytics, or manage billing.
2Review active bots, conversations, voice minutes, and satisfaction before making changes.
3Check recent activity after every setup test.
First launch

Sign up, start the trial, and understand the dashboard

What this is for: Use this workflow for a brand-new workspace or when onboarding a teammate who has never used sem.chat.

Before you start
  • Use a business email that can receive verification and billing emails.
  • Decide who should own the workspace before inviting the rest of the team.
  • Keep a safe test website or staging page ready for widget installation.
1

Open the app sign-up page

Go to app.sem.chat/auth from the website Sign In / Sign Up button.

Expected result: The authentication page shows sign-in and account creation options.
2

Create the account

Enter the business email, create the password, and submit the sign-up form.

Expected result: The app asks for verification or moves into onboarding after the account is accepted.
3

Verify the email

Open the verification email and click the confirmation link.

Expected result: The account can receive billing, invite, report, and alert messages.
4

Complete onboarding

Enter the business name, describe the assistant goal, choose a starting color, and create the first bot.

Expected result: The workspace opens with a bot draft and an active trial state.
5

Open Overview

Click Overview in the left sidebar.

Expected result: The dashboard shows usage cards, quick actions, and recent activity.
6

Choose the next action

Use Create New Bot for setup, View All Bots for management, Analytics for performance, or Billing for plan limits.

Expected result: You know where to continue based on the state of the workspace.
How to test it: Create one private test bot and send a test message before inviting teammates. Confirm the Overview activity changes after the test.
ProblemFix
Verification email does not arriveCheck spam, confirm the email spelling, then request another verification email.
Dashboard opens on BillingThe workspace may need an active trial or plan. Start the trial or choose the correct plan before setup.
A teammate cannot access the workspaceInvite them from Settings, Team instead of sharing the owner login.

What to do next: Create the first bot, test it privately, then install the widget on a staging page.

Private launch test

Create the first private bot test before going live

What this is for: Use this to verify account, bot, widget, and history tracking before customers see the assistant.

Before you start
  • Have one sample customer question ready.
  • Have a staging page or local HTML test page ready.
  • Do not use real customer data in the first test.
1

Open My Bots

Click My Bots in the sidebar or use View All Bots from Overview.

Expected result: You can see the bot created during onboarding or an empty state with a New Bot button.
2

Open the bot builder

Click New Bot or Edit on the existing bot.

Expected result: The Bot Builder opens with Basics, Widget, Knowledge, Voice, and integration controls.
3

Save the bot once

Fill the required bot name and first message, then click Save.

Expected result: The bot receives a valid ID and can generate embed code.
4

Preview privately

Use the preview panel and ask your sample question.

Expected result: The answer should match your instructions or reveal what knowledge is missing.
5

Install on staging

Open Embed, copy the HTML snippet, and paste it before the closing body tag on the staging page.

Expected result: The widget appears in the configured corner on desktop and mobile.
6

Confirm tracking

Open Inbox or Chat History after the test conversation.

Expected result: The test conversation appears with the correct bot, channel, and message history.
How to test it: Send one text message and one voice test if voice is enabled. Confirm both appear in Chat History.
ProblemFix
Embed code is unavailableSave the bot first. If voice sync is still pending, wait for sync or save again after required fields are complete.
The widget shows the wrong botConfirm the data-bot-id in the snippet matches the bot ID from the Embed modal.
No conversation appears in historyRefresh Chat History, confirm the bot is active, and make sure the test happened on the installed widget, not a stale page.

What to do next: Move on to Bot Builder setup and knowledge training.

02

Create And Configure A Bot

Build, edit, preview, activate, transfer, or remove bots from My Bots and Bot Builder.

/dashboardMy Bots control center
Real sem.chat demo workspace screenshot of the My Bots page
1Click New Bot to start a new assistant.
2Use Edit, Embed, Transfer, Activate, or Delete on each bot card.
3Check active state and last updated time before testing.
/bots/:id/editBot Builder basics tab
Real sem.chat demo workspace screenshot of Bot Builder basics
1Fill bot name, avatar, first message, and system instructions.
2Use Preview to test before publishing.
3Save and sync before copying embed code.
Create bot

Create a new bot from My Bots

What this is for: Use this workflow when a new brand, website, support queue, or campaign needs its own assistant.

Before you start
  • Prepare the bot name, goal, first message, and two or three sample questions.
  • Collect the public website URL if you plan to import content.
  • Confirm the plan allows the number of bots and voice/avatar features you need.
1

Open My Bots

Click My Bots in the sidebar.

Expected result: Existing bots and the New Bot button are visible.
2

Click New Bot

Start a new bot from the My Bots page.

Expected result: Bot Builder opens with a draft assistant.
3

Set bot identity

Enter Bot Name, upload or choose an avatar, and write the first message visitors will see.

Expected result: The preview panel reflects the assistant name, avatar, and greeting.
4

Write system instructions

Describe what the bot should do, how it should speak, what it should avoid, and when it should ask for human help.

Expected result: The assistant has clear behavior rules before knowledge is added.
5

Add basic knowledge

Paste essential company, product, support, pricing, and contact information into the knowledge area.

Expected result: The bot can answer common questions without needing website import yet.
6

Save the bot

Click Save and wait for the saved or synced confirmation.

Expected result: The bot has a stable ID, preview can be tested, and embed options become available.
7

Preview the result

Ask the prepared sample questions in Preview.

Expected result: Answers should follow the instructions and use the knowledge you entered.
8

Activate only when ready

Turn the bot active after the private test passes.

Expected result: The bot is ready for widget or channel traffic.
How to test it: Ask at least five realistic questions. Check whether the answer is correct, whether it stays on brand, and whether it asks for human help when needed.
ProblemFix
The answer is too genericAdd more specific knowledge and rewrite instructions with examples of good answers.
The bot refuses questions it should answerRemove overly strict instructions and add trusted knowledge for that topic.
Save does not generate embed codeCheck required fields and save again after the voice provider sync finishes.

What to do next: Configure widget settings, add website knowledge, then install the bot.

Manage bots

Edit, clone workflow, transfer, deactivate, or delete a bot

What this is for: Use this workflow when a bot needs updates, ownership changes, temporary pause, or permanent removal.

Before you start
  • Export any conversation or contact data you must keep before deleting a bot.
  • Confirm the bot is not embedded on a live website before deleting or transferring it.
  • Tell teammates before deactivating a production bot.
1

Open My Bots

Find the bot card by name or status.

Expected result: The card shows current state and available actions.
2

Click Edit

Open the bot builder and make the required changes.

Expected result: The editor loads the current configuration.
3

Save and retest

Click Save after every material change, then run preview questions.

Expected result: The saved configuration is used by the preview and installed widget.
4

Deactivate temporarily

Use the active toggle if the bot should stop handling visitors for now.

Expected result: The bot stops serving live traffic while preserving configuration.
5

Transfer ownership

Use Transfer, enter the recipient email, and confirm.

Expected result: The selected account receives ownership according to the app transfer flow.
6

Delete only after checks

Use Delete, read the warning, and confirm only when the bot is no longer needed.

Expected result: The bot and related configuration are removed according to the warning.
How to test it: After editing, open the installed widget and ask the exact question that motivated the change. Confirm the live answer changed.
ProblemFix
Old answer still appearsRefresh the website page, confirm you saved the correct bot, and check whether imported knowledge needs a sync.
Transfer failsConfirm the recipient email is valid and that the destination account can accept the bot.
Delete was clicked by mistakeStop before final confirmation. Deletion warnings exist because the action may remove bot data permanently.

What to do next: Review analytics and history after live changes to make sure visitor experience improved.

03

Install The Widget

Copy the correct embed code, install it in HTML, WordPress, React, or advanced SDK contexts, then verify desktop and mobile behavior.

Embed modalCopy the website install snippet
Real sem.chat demo workspace screenshot of widget embed code options
1Choose HTML, WordPress, React, or NPM/SDK based on the site stack.
2Copy the code after the bot is saved and synced.
3Paste the snippet before the closing body tag or in the framework layout.
HTML install

Install the widget on a standard HTML website

What this is for: Use this when you can edit the page template, theme footer, or global HTML layout.

Before you start
  • Save the bot first so the embed modal has a real bot ID.
  • Use a staging site before production.
  • Keep the exact script version and data-bot-id from the modal.
1

Open My Bots

Find the bot you want to install and click Embed.

Expected result: The Embed modal opens with installation tabs.
2

Select HTML

Choose the HTML tab and click Copy Code.

Expected result: The widget script is copied with the bot ID attached.
3

Open the website template

Edit the global footer or layout file that renders on every page where the widget should appear.

Expected result: You are editing the shared site shell, not a single isolated page unless that is intentional.
4

Paste before closing body

Paste the snippet immediately before the closing body tag.

Expected result: The script loads after the page content and can mount the widget container.
5

Publish or deploy

Save the template and deploy the site.

Expected result: The widget script is live on the target pages.
6

Test desktop and mobile

Open the site in a fresh browser window and on a mobile viewport.

Expected result: The widget appears in the configured position and opens without console errors.
How to test it: Send a message from the live page, then open Inbox and Chat History to confirm the conversation belongs to the correct bot.
ProblemFix
Widget is missingConfirm the code is before the closing body tag, scripts are not blocked by the site builder, and the bot is active.
Wrong bot appearsCopy the snippet again and compare the data-bot-id with the desired bot.
Widget overlaps page controlsChange position or size in Widget Settings and test again on mobile.

What to do next: Tune the widget settings and lead capture after installation.

HTML embed
<!-- sem.chat Voice & Text Widget -->
<script
  src="https://app.sem.chat/widget-v2.js?v=16"
  data-bot-id="YOUR_BOT_ID"
></script>
Platform install

Install in WordPress, React, or advanced voice SDK flows

What this is for: Use this when the website is managed by a CMS, React app, or custom voice integration.

Before you start
  • Know which stack owns the shared layout.
  • Use the exact snippet shown in sem.chat for the selected bot.
  • For advanced SDK use, confirm you have the required Vapi public key and assistant ID.
1

WordPress option

Use Appearance, Theme Editor, footer.php or a trusted headers-and-footers plugin.

Expected result: The snippet is loaded on public WordPress pages.
2

React option

Create a small ChatWidget component, append the script in useEffect, and render it in the root layout.

Expected result: The widget loads once and cleans up if the layout unmounts.
3

Advanced SDK option

Use the NPM/SDK tab only when you need custom voice-call controls beyond the default widget.

Expected result: Your app controls the voice session while sem.chat remains the configured assistant source.
4

Verify bot ID

Confirm the installed code references the bot ID from the Embed modal.

Expected result: The live widget connects to the intended assistant.
5

Check console

Open browser developer tools and reload.

Expected result: There are no blocked-script, duplicate-container, or network errors.
How to test it: Complete one test message from the installed site, then confirm it appears in Inbox with the expected page URL.
ProblemFix
React loads duplicate widgetsGuard script insertion with a ref or render the component only in the root layout.
WordPress strips script tagsUse a footer injection plugin or theme file that allows scripts.
SDK call cannot startCheck the public key, assistant ID, browser permissions, and plan access for voice.

What to do next: Move to Widget Settings to control behavior, branding, and lead capture.

WordPress footer snippet
<!-- sem.chat Widget (WordPress Compatible) -->
<script>
window.SEMCHAT_CONFIG = { botId: "YOUR_BOT_ID" };
</script>
<script src="https://app.sem.chat/widget-v2.js?v=16"></script>
React component
import { useEffect, useRef } from 'react';

export function ChatWidget() {
  const loaded = useRef(false);

  useEffect(() => {
    if (loaded.current) return;
    loaded.current = true;

    const script = document.createElement('script');
    script.src = 'https://app.sem.chat/widget-v2.js?v=16';
    script.setAttribute('data-bot-id', 'YOUR_BOT_ID');
    script.async = true;
    document.body.appendChild(script);

    return () => {
      const container = document.getElementById('semchat-widget-container');
      if (container) container.remove();
      script.remove();
    };
  }, []);

  return null;
}
Advanced voice SDK
npm install @vapi-ai/web

import Vapi from '@vapi-ai/web';

const vapi = new Vapi('YOUR_VAPI_PUBLIC_KEY');
await vapi.start('YOUR_ASSISTANT_ID');

vapi.on('call-start', () => console.log('Call started'));
vapi.on('call-end', () => console.log('Call ended'));
04

Widget Settings

Configure mode, theme, size, position, color, branding, reactions, sound, consent, lead capture, ratings, follow-up email, and activation state.

Bot Builder / WidgetWidget appearance and visitor behavior
Real sem.chat demo workspace screenshot of widget settings
1Choose chat, voice, or hybrid mode.
2Set theme, color, position, size, branding, consent, and sound.
3Configure lead capture, ratings, reactions, and follow-up behavior.
Widget behavior

Configure visitor-facing widget behavior

What this is for: Use this after the first install or anytime the widget needs to match the website and capture better leads.

Before you start
  • Install the widget on a staging page.
  • Know whether visitors should start with chat, voice, or both.
  • Prepare consent and lead-capture copy if required for the region.
1

Open the bot builder

Open My Bots, click Edit, then choose the Widget tab.

Expected result: Widget controls appear for the selected bot.
2

Choose the mode

Select Chat, Voice, or Hybrid based on the visitor experience you want.

Expected result: The preview changes to show the chosen mode.
3

Set appearance

Choose theme, color, size, button position, and branding options.

Expected result: The widget matches the site without covering important content.
4

Enable visitor controls

Turn reactions, sound, ratings, and consent prompts on or off.

Expected result: Visitors see only the controls you want them to use.
5

Configure lead capture

Choose required fields, optional description field, and when the form appears.

Expected result: Contacts are collected before or during conversations according to your setup.
6

Set follow-up email

Configure the follow-up email behavior if your plan includes it.

Expected result: Visitors can receive follow-up messages after resolved conversations.
7

Save and test

Click Save, reload the staging page, and open the widget.

Expected result: The live widget matches the saved settings.
How to test it: Open the widget on desktop and mobile, submit a lead form, leave a rating, and confirm the contact and conversation are recorded.
ProblemFix
Color did not updateSave the bot, hard-refresh the website, and confirm the installed widget uses the same bot ID.
Lead fields are missingConfirm lead capture is enabled and the selected trigger condition is met.
Visitors cannot use voiceCheck Voice settings, browser microphone permission, plan access, and voice-minute limits.

What to do next: Add voice/avatar settings and knowledge sources before production launch.

05

Voice And Avatars

Select stock voices, configure voice mode and limits, read transcripts, clone voices, assign cloned voices, and manage stock or custom avatars.

Bot Builder / VoiceVoice, limits, transcripts, and avatars
Real sem.chat demo workspace screenshot of voice and avatar settings
1Choose a stock voice or a saved cloned voice.
2Set voice-minute limits and transcript saving.
3Choose stock avatars or upload a custom avatar if the plan allows it.
Voice setup

Set up voice calls and transcripts

What this is for: Use this when visitors should talk to the bot instead of only typing.

Before you start
  • Confirm the plan includes voice minutes and the desired voice/avatar options.
  • Use a quiet browser environment for testing.
  • Prepare one realistic support or sales question to test by voice.
1

Open Voice settings

Open the bot builder and select the Voice or Voice and Avatars area.

Expected result: Voice controls and current voice selection are visible.
2

Select a stock voice

Preview available voices, choose the best fit, and save the selection.

Expected result: The bot uses the chosen voice for calls.
3

Configure voice mode

Use Widget Settings to choose Voice or Hybrid when voice should be available to visitors.

Expected result: Visitors see a voice option in the widget.
4

Set voice limits

Define per-user or workspace limits if available.

Expected result: Long or repeated calls cannot consume more minutes than intended.
5

Enable transcripts

Turn on transcript saving if you need call review in history.

Expected result: Voice calls create readable transcripts after the session.
6

Test a call

Open the widget, allow microphone access, start a call, and ask the prepared question.

Expected result: The bot responds by voice and the call ends cleanly.
7

Read the transcript

Open Chat History and find the voice conversation.

Expected result: The transcript shows what the visitor and bot said.
How to test it: Complete one short call and confirm voice minutes, transcript, and conversation mode are recorded.
ProblemFix
Browser blocks microphoneAllow microphone permission in the browser and reload the page.
Voice option is lockedOpen Billing and confirm the workspace plan includes voice features.
Transcript is emptyConfirm transcript saving is enabled and the call ended normally.

What to do next: Add or refine knowledge so voice answers are accurate.

Voice clone and avatar

Clone a voice and assign a custom avatar

What this is for: Use this when the assistant needs a branded voice or talking avatar experience.

Before you start
  • Use only audio and images you have permission to use.
  • Record clean voice samples with low background noise.
  • Confirm plan limits for cloned voices and custom avatars.
1

Open Voice Cloning

Click Clone Voice from the Voice area.

Expected result: The upload dialog shows accepted sample requirements.
2

Upload samples

Upload one to five clear recordings and submit the clone request.

Expected result: The cloned voice appears after processing or the dialog shows the next requirement.
3

Assign the cloned voice

Select the cloned voice in the voice selector and save.

Expected result: Future calls use the cloned voice.
4

Choose a stock avatar

Pick an included avatar if custom avatar upload is not needed.

Expected result: The voice experience has a visual identity.
5

Upload custom avatar

Upload a clear face image or short video if your plan supports it.

Expected result: The avatar is processed and becomes available for selection.
6

Run a full preview

Start a voice call and confirm voice, avatar, and transcript behavior together.

Expected result: The visitor experience matches the configured brand.
How to test it: Ask a short question with the cloned voice selected and confirm the call uses the expected voice/avatar.
ProblemFix
Clone quality is poorRecord cleaner samples with one speaker, stable volume, and no music.
Custom avatar upload is unavailableCheck Billing for plan-gated avatar limits.
Old voice still playsSave the bot after selecting the new voice and reload the widget page.

What to do next: Proceed to Knowledge and Data so the voice experience has accurate answers.

06

Knowledge And Data

Add manual knowledge, import website content, apply crawl results, sync imported content, add product feed URLs, refresh or remove feeds, and verify answers with test questions.

Bot Builder / KnowledgeKnowledge sources and answer testing
Real sem.chat demo workspace screenshot of knowledge and data settings
1Add manual knowledge for policy, pricing, and brand rules.
2Import website pages and apply crawl results.
3Add product feeds and sync them when inventory changes.
Knowledge sources

Train the bot with manual knowledge, website import, and product feeds

What this is for: Use this whenever the assistant gives incomplete answers or needs fresh product, policy, or website information.

Before you start
  • Prepare source URLs and product feed URLs.
  • Decide which pages should not be imported, such as admin or private pages.
  • Create test questions for each topic you add.
1

Open Knowledge

Open Bot Builder and choose the Knowledge or Data tab.

Expected result: Manual knowledge, website import, and product feed tools are visible.
2

Add manual knowledge

Paste concise facts, policies, pricing, contact details, and answer style notes.

Expected result: The bot has an immediate trusted source for high-priority answers.
3

Import website content

Paste the public website URL and start the crawl/import.

Expected result: Crawl results show discovered pages or import status.
4

Review and apply results

Keep useful pages, remove irrelevant pages, then apply the selected content.

Expected result: Only approved website content enters the knowledge base.
5

Add product feed URLs

Paste Google Merchant Center or supported feed URLs and import.

Expected result: Products, prices, availability, and attributes become available to the bot.
6

Refresh or remove feeds

Use refresh when catalog data changes and remove feeds no longer used.

Expected result: The bot avoids stale or duplicate product data.
7

Save and sync

Save the bot and wait for sync to complete.

Expected result: The latest knowledge is used by preview and live widget answers.
8

Ask verification questions

Ask one test question per source you added.

Expected result: The answer cites or reflects the updated content accurately.
How to test it: Ask questions about pricing, returns, availability, company info, and unsupported topics. Confirm the bot answers known topics and does not invent unknown details.
ProblemFix
Crawler imports irrelevant pagesRemove those pages from selected results and add clearer manual instructions.
Product prices are staleRefresh the feed and confirm the feed URL itself contains current values.
Bot makes up answersAdd a rule that the bot should say it is not sure and offer human support when knowledge is missing.

What to do next: Return to Preview, test again, then install or update the widget.

07

Inbox, Live Support, History, Contacts

Handle daily conversations, claim live-support requests, hand control back to AI, export history, manage contacts, and sync contacts to SendPulse.

/inboxInbox conversation workflow
Real sem.chat demo workspace screenshot of Inbox conversations
1Filter by bot or channel.
2Open a conversation and reply as a human when needed.
3Use translate, resolve, and handoff controls carefully.
/live-supportLive-support handoff control
Real sem.chat demo workspace screenshot of Live Support
1Claim waiting handoffs quickly.
2Reply as an agent or hand the conversation back to AI.
3Resolve when the visitor no longer needs human help.
/chat-historyConversation history and exports
Real sem.chat demo workspace screenshot of chat history
1Search by visitor, bot, channel, or date.
2Open full transcripts for text and voice sessions.
3Export CSV or JSON when needed.
/contactsContacts and SendPulse export
Real sem.chat demo workspace screenshot of Contacts
1Filter contacts by bot or source.
2Open contact details and conversation context.
3Export or sync selected contacts to SendPulse.
Inbox reply

Open a conversation and send a human reply

What this is for: Use this when an operator needs to respond to a customer from sem.chat instead of letting AI continue alone.

Before you start
  • Confirm the operator has access to the bot or workspace.
  • Read the conversation before replying.
  • Know whether the visitor expects the same language.
1

Open Inbox

Click Inbox in the sidebar.

Expected result: Recent conversations appear with bot, channel, visitor, status, and time.
2

Filter if needed

Use channel, bot, unread, or status filters to find the conversation.

Expected result: The list narrows to the conversation set you need.
3

Open the conversation

Click the visitor row.

Expected result: The full thread, visitor info, and reply controls are visible.
4

Translate if needed

Use translation controls when the visitor language differs from the agent language.

Expected result: The agent can understand and reply appropriately.
5

Send a reply

Write the human response and send it.

Expected result: The message is added to the thread as an agent/human reply.
6

Resolve or keep open

Resolve the conversation if complete, or leave it open for follow-up.

Expected result: The inbox status matches the real customer state.
How to test it: Send a safe test reply to a test conversation and confirm it appears in the visitor widget and Chat History.
ProblemFix
Reply fails to sendCheck network state, conversation status, and whether live support has been claimed.
Visitor language is wrongUse translation or update bot language settings before replying.
Conversation is not in InboxSearch Chat History and confirm the widget test used the correct bot.

What to do next: Use Live Support for active handoff queues and Chat History for audits.

Live support

Claim, reply, hand back to AI, and resolve a handoff

What this is for: Use this when AI requests a human or a visitor explicitly needs an agent.

Before you start
  • Have an agent available before enabling live support.
  • Define when AI should request handoff in bot instructions.
  • Keep notification settings enabled for handoff alerts.
1

Open Live Support

Click Live Support in the sidebar.

Expected result: Waiting and active handoff conversations are visible.
2

Claim the request

Click Claim on the waiting conversation.

Expected result: Other agents can see the conversation is actively handled.
3

Read context

Open messages and visitor details before replying.

Expected result: The agent understands why the handoff happened.
4

Send the human reply

Respond clearly and keep the thread updated.

Expected result: The visitor receives a human response.
5

Hand back to AI if appropriate

Use hand back when the issue is answered and AI can continue.

Expected result: AI resumes handling the conversation.
6

Resolve when done

Click Resolve after the visitor no longer needs help.

Expected result: The handoff is closed and removed from the active queue.
How to test it: Create a test handoff, claim it, reply once, hand it back, and confirm the status changes in Live Support and Chat History.
ProblemFix
Agents miss requestsEnable browser/email/push notifications and add a process for queue ownership.
AI keeps taking over too soonAdjust instructions and handoff rules so human control stays active until resolved or handed back.
External CRM is out of syncUse webhooks or polling from the Developer Recipes section.

What to do next: Connect CRM/webhooks if support teams work outside sem.chat.

History and contacts

Search, export, and use conversation/contact records

What this is for: Use this for audits, lead review, CSV export, and SendPulse syncing.

Before you start
  • Decide whether you need conversations, contacts, or both.
  • Apply the correct date range before exporting.
  • Do not export more personal data than needed.
1

Open Chat History

Click Chat History in the sidebar.

Expected result: Conversation filters, stats, and the transcript list are visible.
2

Search and filter

Filter by bot, channel, mode, visitor, or date range.

Expected result: Only matching conversations remain visible.
3

Open a transcript

Click a conversation to read the full message thread.

Expected result: The full context, contact details, and conversation metadata are visible.
4

Export conversations

Click Export and choose the required format if available.

Expected result: The export contains the filtered conversation data.
5

Open Contacts

Click Contacts in the sidebar.

Expected result: Lead/contact records appear with source, bot, and status.
6

Filter and export contacts

Search contacts, select the desired records, then export or sync to SendPulse.

Expected result: The selected contacts are available outside sem.chat according to the chosen action.
How to test it: Export a small filtered CSV and open it locally to confirm columns and date range are correct.
ProblemFix
Contact missing from ContactsConfirm lead capture is enabled and the visitor submitted the form.
Export is too largeNarrow the date range or bot filter before exporting.
SendPulse sync unavailableConnect SendPulse in Integrations first, then return to Contacts.

What to do next: Review Analytics to understand performance trends after operations are running.

08

Channels And Integrations

Connect Slack, Facebook, Instagram, WhatsApp, Telegram through BotFather, manual credentials, alternative chat links, SendPulse, and CRM integrations.

/integrationsChannels, CRM, and email connections
Real sem.chat demo workspace screenshot of Integrations
1Choose the channel or CRM integration card.
2Follow OAuth or credential steps for each provider.
3Disconnect or retest integrations from the same page.
Connect channels

Connect a messaging channel or CRM integration

What this is for: Use this when sem.chat should receive conversations outside the website widget or send contacts to other tools.

Before you start
  • Have admin access to the external platform.
  • Know which bot should receive channel messages.
  • Use test channels before connecting production accounts.
1

Open Integrations

Click Integrations in the sidebar.

Expected result: Available channels, CRM tools, SendPulse, and website widget options are visible.
2

Choose the integration

Click Connect on Slack, Meta channels, Telegram, SendPulse, CRM, or manual credentials.

Expected result: The setup dialog or OAuth flow opens.
3

Complete provider setup

For OAuth channels, approve the requested permissions. For manual channels, paste the required token, secret, account ID, or webhook URL.

Expected result: sem.chat stores the connection and shows the integration as connected.
4

Assign the bot

Choose which bot should handle messages from that channel when the dialog asks.

Expected result: Incoming messages route to the correct assistant.
5

Test the channel

Send a test message from the external channel.

Expected result: The message appears in Inbox or Chat History under the correct channel.
6

Disconnect if needed

Use Disconnect from the integration card when the channel should stop.

Expected result: sem.chat stops receiving or sending through that integration.
How to test it: Send one test message through the connected channel and confirm the bot reply, Inbox row, and history record.
ProblemFix
Telegram token failsCreate or reset the token in BotFather and paste it again.
Slack messages do not arriveCheck app scopes, event subscription URL, bot token, signing secret, and channel membership.
Meta channel connection failsConfirm the Facebook/Instagram/WhatsApp account has admin permissions and required business access.
SendPulse sync failsReconnect SendPulse and confirm contact fields are mapped.

What to do next: Document channel ownership for the team and monitor Inbox after launch.

09

Scheduling

Create event types, configure availability, connect calendars, manage bookings, create one-off links, configure booking emails, review analytics, set paid events, and test public booking links.

/schedulingScheduling workspace
Real sem.chat demo workspace screenshot of Scheduling
1Use tabs for Event Types, Bookings, Analytics, One-off Links, Calendars, Emails, and Settings.
2Edit, copy, embed, activate, or pause event types.
3Copy the public link and run a private booking test.
Event editorEvent type configuration
Real sem.chat demo workspace screenshot of scheduling event editor
1Enter name, description, duration, location, and buffers.
2Set availability, booking windows, questions, paid-event options, and cancellation rules.
3Save the event before sharing the link.
/book/:username/:eventSlugPublic booking page
Real sem.chat demo workspace screenshot of the public booking page
1Visitors choose a date from the public booking page.
2Visitors choose an available time slot.
3Visitors confirm the booking and receive confirmation emails.
Event type

Create an event type and publish a booking link

What this is for: Use this when visitors should book demos, consultations, sales calls, onboarding, or support sessions.

Before you start
  • Choose event name, duration, meeting type, and owner.
  • Set the timezone and availability before sharing links.
  • Connect calendars if double-booking matters.
1

Open Scheduling

Click Scheduling in the sidebar.

Expected result: The scheduling workspace shows tabs for event types, bookings, analytics, one-off links, calendars, emails, and settings.
2

Create an event type

Click Create, then add name, description, duration, location, buffer, and booking rules.

Expected result: The event has enough public information for visitors to understand it.
3

Set availability

Configure weekly hours, date overrides, notice windows, and booking window.

Expected result: Visitors only see times you are willing to offer.
4

Add questions

Add required questions such as phone, company, website, or meeting goal.

Expected result: Bookings collect the context your team needs before the call.
5

Connect calendars

Open Calendars and connect Google, Outlook, or iCal if available.

Expected result: Busy times can be blocked and confirmed bookings can be written to calendar.
6

Set emails and reminders

Open Emails and configure confirmation, reminder, cancellation, and reschedule messages.

Expected result: Visitors receive correct booking communication.
7

Share and test the public link

Copy the event link, open it in a private window, choose a slot, and complete a test booking.

Expected result: The booking appears in the Bookings tab and confirmation messages are sent.
How to test it: Complete one test booking, one reschedule, and one cancellation. Confirm each event appears in Scheduling and connected calendars.
ProblemFix
No times appear on public pageCheck timezone, weekly availability, date overrides, notice window, and connected calendar conflicts.
Booking email missingCheck email settings and spam folder, then send another test booking.
Payment fails on paid eventConfirm billing/payment integration settings and currency are valid before publishing.

What to do next: Embed booking links in the bot, website, or follow-up emails.

Advanced scheduling

Use one-off links, analytics, embeds, and paid events

What this is for: Use this when scheduling needs temporary availability, reporting, embedded booking, or payment.

Before you start
  • Create at least one event type first.
  • Connect calendars before using one-off links heavily.
  • Define refund/cancellation policy before enabling paid events.
1

Create a one-off link

Open One-off Links, select the offered slots or rules, then generate the link.

Expected result: The recipient can book from only the selected availability.
2

Embed scheduling

Use the event card embed option if the booking flow should appear on your website.

Expected result: The booking UI can be placed in the page where visitors convert.
3

Review scheduling analytics

Open Analytics inside Scheduling.

Expected result: You can see bookings, completion trends, and event-type performance.
4

Enable paid events

Open the event editor, set price, currency, and payment behavior.

Expected result: Visitors must complete the payment step according to the event setup.
5

Audit bookings

Open Bookings and review upcoming, completed, canceled, and rescheduled entries.

Expected result: The team can manage attendance and follow-up.
How to test it: Book through the public page and through an embedded page if used. Confirm both create the same type of booking record.
ProblemFix
One-off link exposes wrong slotsRegenerate the link with a smaller slot set or stricter date range.
Embedded booking is too narrowPlace the embed in a wider content container and check mobile layout.
Analytics look emptyCreate or wait for real bookings; analytics depend on booking records.

What to do next: Connect scheduling outcomes to Reports and Analytics.

10

Analytics And Reports

Pick date ranges, use custom dates, read core metrics, export CSV, review satisfaction and conversation trends, configure email reports, and verify delivery.

/analyticsAnalytics dashboard
Real sem.chat demo workspace screenshot of Analytics
1Choose date ranges or custom dates.
2Read conversation, satisfaction, language, channel, and conversion metrics.
3Export CSV for offline analysis.
Settings / ReportsEmail report setup
Real sem.chat demo workspace screenshot of report settings
1Choose daily, weekly, or monthly report cadence.
2Add report recipients.
3Send an instant report to test delivery.
Analytics review

Read analytics and export performance data

What this is for: Use this for weekly reviews, launch checks, support quality review, and conversion analysis.

Before you start
  • Choose the date range before reading metrics.
  • Know which bot or channel you are evaluating.
  • Exclude private test dates when reporting production performance.
1

Open Analytics

Click Analytics in the sidebar.

Expected result: Dashboard metrics and chart panels are visible.
2

Choose date range

Select today, 7 days, 30 days, or custom dates.

Expected result: All charts update to the selected period.
3

Read core metrics

Review conversations, voice minutes, satisfaction, conversion, and channel mix.

Expected result: You understand the volume and quality of customer interactions.
4

Review trends

Look at conversation trends, satisfaction changes, top questions, and language/channel patterns.

Expected result: You can identify where to improve bot instructions or staffing.
5

Export CSV

Use Export CSV when the team needs spreadsheet analysis.

Expected result: The CSV contains the selected date range and metrics.
6

Turn findings into changes

Update bot instructions, knowledge, widget settings, or support coverage based on the data.

Expected result: Analytics lead to concrete product improvements.
How to test it: Export a small custom-date CSV and verify the date range and metrics match what the dashboard shows.
ProblemFix
Metrics seem too highCheck whether staging/test conversations are included in the selected date range.
Satisfaction is emptyEnable ratings in Widget Settings and wait for visitors to leave ratings.
Voice minutes do not match expectationsConfirm voice mode is enabled only on the intended bots.

What to do next: Schedule email reports for recurring visibility.

Reports

Configure recurring email reports and test delivery

What this is for: Use this when owners, managers, or clients need automatic performance summaries.

Before you start
  • Decide who should receive reports.
  • Use verified email addresses.
  • Pick a cadence that matches business review rhythms.
1

Open Settings, then Reports

Go to Settings and select the Reports tab, or use the Reports redirect if available.

Expected result: Report cadence, recipients, and history are visible.
2

Choose cadence

Enable daily, weekly, or monthly reports.

Expected result: The report schedule is stored for the workspace.
3

Add recipients

Enter the email addresses that should receive reports.

Expected result: Reports are sent to the correct stakeholders.
4

Send instant report

Click Send Now or equivalent instant report action.

Expected result: A report email is sent immediately for verification.
5

Review report history

Check the history panel after reports are sent.

Expected result: You can confirm delivery status and timing.
How to test it: Send an instant report to a test recipient and confirm receipt and formatting.
ProblemFix
Report email does not arriveCheck recipient spelling, spam folder, and report history status.
Wrong people receive reportsUpdate recipients and save before the next scheduled send.
Report content feels noisyAdjust date range expectations and use Analytics for deeper manual review.

What to do next: Use the report cadence as an operating rhythm for bot improvements.

11

Billing, Team, Security, Settings, Affiliate

Start or upgrade plans, manage billing portal, invite teammates, set roles, edit profile/language, configure notifications, enable 2FA, use danger-zone actions, and run the affiliate workflow.

/billingPlan and billing controls
Real sem.chat demo workspace screenshot of Billing
1Review current plan, trial state, and usage limits.
2Compare plan features before upgrading.
3Open the billing portal for invoices, payment methods, cancellation, or reactivation.
/settingsSettings, team, and security
Real sem.chat demo workspace screenshot of Settings, Team, and Security
1Use General for profile and language.
2Use Team for invites and roles.
3Use Security for 2FA, API keys, and danger-zone actions.
/affiliateAffiliate program controls
Real sem.chat demo workspace screenshot of Affiliate
1Join the program to create a referral link.
2Copy the referral link for campaigns.
3Set payout email and request eligible payouts.
Billing

Start, upgrade, cancel, or reactivate a plan

What this is for: Use this when the workspace needs trial activation, more limits, invoices, payment updates, or subscription changes.

Before you start
  • The account owner or billing admin should perform billing actions.
  • Confirm which features are plan-gated: voice, cloned voices, custom avatars, API, team, CRM, and channels.
  • Use the secure billing portal for payment method and invoice changes.
1

Open Billing

Click Billing in the sidebar.

Expected result: Current plan, trial state, usage limits, and plan cards are visible.
2

Compare plans

Review chat, voice, team, API, avatar, integration, scheduling, and support limits.

Expected result: You know which plan unlocks the needed feature.
3

Choose billing interval

Select monthly or yearly if the toggle is available.

Expected result: Pricing and savings update for the selected interval.
4

Upgrade or start checkout

Choose the desired plan and complete checkout.

Expected result: The subscription becomes active after payment confirmation.
5

Open customer portal

Use the billing portal for payment method, invoices, cancellation, or reactivation.

Expected result: Sensitive billing actions happen in the secure provider portal.
6

Verify feature access

Return to the feature that was locked and reload the app.

Expected result: The unlocked feature is now available if the plan includes it.
How to test it: After upgrading, open the previously locked feature, such as voice clone or API keys, and confirm the lock is gone.
ProblemFix
Feature remains locked after upgradeRefresh the app, wait a moment for subscription sync, then check Billing again.
Checkout was cancelledReturn to Billing and start checkout again; no plan changes happen after a cancelled checkout.
Need invoice or card changeOpen the customer portal instead of editing payment details inside the app.

What to do next: Invite teammates and secure the owner account.

Team and security

Invite teammates, set roles, edit profile, enable 2FA, and manage settings

What this is for: Use this when the workspace moves from solo setup to team operation.

Before you start
  • Know each teammate role before sending invites.
  • Use least-privilege access: Owner, Admin, Editor, Viewer.
  • Have an authenticator app ready for 2FA.
1

Open Settings

Click Settings in the sidebar.

Expected result: General, notifications, team, reports, developers, security, and related tabs are visible.
2

Edit profile and language

Update display name, profile information, and preferred language in General.

Expected result: The app identifies the user correctly and uses the chosen language where available.
3

Invite team members

Open Team, enter an email, choose a role, and send the invite.

Expected result: The teammate receives an invite link and appears as pending until accepted.
4

Set role permissions

Use Owner for full control, Admin for management, Editor for content changes, and Viewer for read-only access.

Expected result: Each user has access appropriate to their responsibility.
5

Configure notifications

Choose email, browser, push, live-support, billing, and report notifications.

Expected result: The right people get alerts without unnecessary noise.
6

Enable 2FA

Open Security, enable two-factor authentication, scan the code, and store recovery details.

Expected result: The account requires a second factor after password login.
7

Use danger-zone actions carefully

Export needed data and confirm active widgets/integrations before destructive account actions.

Expected result: The workspace avoids accidental data loss.
How to test it: Invite a test teammate, accept the invite in a separate browser, and confirm the role only exposes intended features.
ProblemFix
Invite email missingCheck spam, resend the invite, and verify the address.
Teammate sees too muchLower their role and review bot access settings.
2FA setup failsCheck device time, rescan the QR code, and store recovery details before relying on it.

What to do next: Configure API keys only for users and services that need them.

Affiliate

Join affiliate, copy referral link, set payout email, and request payout

What this is for: Use this when a partner or customer wants to refer new sem.chat users and track commission activity.

Before you start
  • Use the account that should own referral attribution.
  • Prepare the payout email before requesting payout.
  • Check program rules before publishing referral campaigns.
1

Open Affiliate

Click Affiliate in the sidebar or open the affiliate tab from Settings if linked there.

Expected result: The affiliate program page shows join, referral, payout, and history areas.
2

Join the program

Click Join if the account has not joined yet.

Expected result: A referral code and referral link are created.
3

Copy referral link

Copy the unique link and use it in content, campaigns, or partner messages.

Expected result: Sign-ups through the link can be attributed to the affiliate account.
4

Set payout email

Enter the payout email and save it.

Expected result: Eligible payouts can be routed correctly.
5

Review referrals and commissions

Check referral list, commission status, and payout history.

Expected result: You know what is pending, eligible, or already paid.
6

Request payout

Click Request Payout when the program rules and minimums are met.

Expected result: The payout request is recorded for processing.
How to test it: Open the referral link in a private browser and confirm it lands on the expected signup flow with referral tracking.
ProblemFix
Referral link is missingJoin the program first or refresh the affiliate page after joining.
Payout request unavailableCheck minimum payout threshold, eligible commission state, and payout email.
Referral not attributedConfirm the visitor used the exact referral link and did not strip tracking parameters.

What to do next: Use Analytics and Reports to monitor referred customer impact if applicable.

12

Notifications And App Updates

Review alerts, mark notifications read, filter important events, and use app updates to understand new product changes.

/notificationsNotification center
Real sem.chat demo workspace screenshot of Notifications
1Use Mark all read after reviewing unread alerts.
2Filter by unread, billing, live support, or system events.
3Open the related feature after reading the alert.
/app-updatesApp updates feed
Real sem.chat demo workspace screenshot of App Updates
1Read release notes for new features and fixes.
2Use details to train teammates before workflow changes.
3Check updates after noticing UI or behavior changes.
Notifications

Review notifications and act on alerts

What this is for: Use this when the app reports handoffs, billing state, system events, report delivery, or important workspace activity.

Before you start
  • Make sure notification preferences are set in Settings.
  • Have live-support coverage if handoff alerts are enabled.
  • Review unread alerts before marking them read.
1

Open Notifications

Click Notifications in the sidebar or app header notification entry.

Expected result: The notification center lists recent alerts.
2

Filter alerts

Use unread or category filters to focus on billing, live support, bot, report, or system events.

Expected result: Only matching alerts remain visible.
3

Open the related page

Click the alert or use its context to open Billing, Live Support, Reports, or the relevant bot.

Expected result: You act on the notification rather than just reading it.
4

Mark read

Mark a single alert read or use Mark all read after review.

Expected result: Unread count drops and reviewed items are no longer highlighted.
5

Adjust preferences

Open Settings, Notifications if too many or too few alerts arrive.

Expected result: The notification stream matches team needs.
How to test it: Create a safe test event such as a live-support request or instant report, then confirm the notification appears and can be marked read.
ProblemFix
No notification arrivesCheck Settings notification preferences, browser permission, and whether the event actually happened.
Too many alertsDisable noisy categories or send them only to the responsible team members.
Unread count seems stuckRefresh the app after marking all read and confirm filters are not hiding unread items.

What to do next: Review App Updates when behavior changes or new controls appear.

App updates

Use app updates to understand product changes

What this is for: Use this when teammates need to learn what changed before using a new feature.

Before you start
  • Open updates after major releases or when the UI changes.
  • Share relevant update notes with support and sales users.
  • Retest critical workflows after major changes.
1

Open App Updates

Click App Updates in the sidebar.

Expected result: The update feed shows new features, fixes, and release notes.
2

Read the latest update

Open the most recent update card or detail view.

Expected result: You see what changed and which workflow it affects.
3

Map the change to your workflow

Identify whether the update affects bots, widget, support, scheduling, billing, or developers.

Expected result: The right team members know what to check.
4

Retest critical paths

If the update affects a production workflow, repeat the relevant manual steps from this documentation.

Expected result: The team confirms the changed workflow still works.
5

Share internally

Send the update summary to users who own the affected area.

Expected result: Team adoption is smoother and support questions drop.
How to test it: After a relevant update, repeat the guide for the affected feature and confirm screenshots or step names still match.
ProblemFix
Update mentions a locked featureOpen Billing to confirm whether the current plan includes it.
Team missed a changeAdd App Updates review to release or weekly operations routines.
Documentation looks stale after an updateUse the Engineer Guide to update screenshots and steps.

What to do next: Keep the public documentation current as features evolve.

13

Developer Recipes

Generate API keys, use x-api-key authentication, call action-based endpoints, bridge live support to a CRM, register webhooks, verify signatures, and embed the widget in code.

Settings / DevelopersAPI keys, quick start, and usage tabs
Real sem.chat demo workspace screenshot of developer API key settings
1Generate and revoke API keys from the API Keys tab.
2Use Quick Start for first curl examples.
3Review Usage before enabling high-volume automation.
API quick start

Generate an API key and make the first API calls

What this is for: Use this for reporting scripts, custom apps, CRM bridges, external live support, or automation.

Before you start
  • Use a server-side environment. Do not expose API keys in browser JavaScript.
  • Generate a separate key for each integration.
  • Copy the key immediately because secrets are shown once.
1

Open Developers

Open Settings and select Developers, or use the Developers redirect if available.

Expected result: API Keys, Quick Start, Documentation, and Usage tabs are visible.
2

Generate a key

Click Generate Key, give it a clear label, and copy it immediately.

Expected result: The key starts with sk_live_ and is available for server-side requests.
3

Send x-api-key header

Include x-api-key on every public API request.

Expected result: The public API can authenticate the request and scope it to the owner.
4

List bots

Call action=list-bots to find the bot ID you need.

Expected result: The response returns bot IDs, names, active state, and configuration summary.
5

Send a chat message

POST action chat with botId and message.

Expected result: The response returns reply, model, and usage information.
6

Check usage

Call action=usage before running high-volume jobs.

Expected result: You know current plan and usage state before automation runs.
7

Rotate keys when needed

Revoke unused keys and generate new ones for changed vendors or services.

Expected result: Old services cannot continue using stale credentials.
How to test it: Run list-bots and chat from a local terminal or server environment, then confirm the conversation appears in Chat History if chat was sent.
ProblemFix
401 or unauthorized responseCheck x-api-key spelling, copy the full key, and confirm it has not been revoked.
Bot not foundUse list-bots again and confirm the bot belongs to the API key owner.
Browser CORS issueMove the API call to your backend; API keys are intended for server-side use.

What to do next: Use /api-docs for focused endpoint reference and keep this page as workflow guidance.

List bots
curl -X GET "https://akhsrklbijflesmcqxur.supabase.co/functions/v1/public-api?action=list-bots" \
  -H "x-api-key: sk_live_your_key_here"
Send a chat message
curl -X POST "https://akhsrklbijflesmcqxur.supabase.co/functions/v1/public-api" \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "chat",
    "botId": "YOUR_BOT_ID",
    "message": "What can you help me with?"
  }'
Live-support CRM bridge

Poll or push live-support requests into a CRM

What this is for: Use this when agents work in another system but sem.chat receives the visitor conversation.

Before you start
  • Create a dedicated API key named for the CRM bridge.
  • Decide whether polling or webhooks fit your infrastructure.
  • Make sure the CRM stores conversation IDs for future replies/resolution.
1

List waiting handoffs

GET action=live-support-list with status=requested or status=all.

Expected result: The CRM receives open conversations requiring human attention.
2

Fetch messages

GET action=live-support-messages with conversationId.

Expected result: The CRM has full thread context and visitor details.
3

Claim before replying

POST action=live-support-claim.

Expected result: sem.chat marks the conversation as actively handled.
4

Send agent reply

POST action=live-support-reply with conversationId, message, and agentName.

Expected result: The visitor receives the human reply and the thread updates.
5

Resolve or hand back

POST action=live-support-resolve with resolution resolve or hand-back.

Expected result: The conversation leaves the waiting queue or AI resumes control.
6

Log status in CRM

Store the latest handoff status, message ID, and timestamps.

Expected result: CRM and sem.chat remain auditable.
How to test it: Create a safe handoff, mirror it to the CRM, reply from the bridge, and confirm the visitor thread updates.
ProblemFix
Duplicate CRM ticketsUse conversationId as the idempotency key in your CRM bridge.
Replies arrive out of orderStore message timestamps and avoid concurrent replies from multiple systems.
AI replies while agent is workingClaim the handoff first and only hand back when the agent is done.

What to do next: Register webhooks if polling is too slow or too expensive.

Webhooks

Register webhooks and verify X-SemChat-Signature

What this is for: Use this when your system needs real-time events for handoffs, messages, and resolution updates.

Before you start
  • Webhook URL must be HTTPS and reachable from the public internet.
  • Store the webhook secret immediately; it is shown once.
  • Verify signatures before processing events.
1

Register the webhook

POST action webhook-register with url and events.

Expected result: The response includes webhook details and a one-time signing secret.
2

Store the secret

Save the secret in your server environment or secret manager.

Expected result: Future deliveries can be verified.
3

Verify signature

Read X-SemChat-Signature and compare it to an HMAC SHA-256 over the raw request body.

Expected result: Only genuine sem.chat deliveries are accepted.
4

Handle retries idempotently

Use event ID or conversation/message ID to avoid duplicate processing.

Expected result: Retries do not create duplicate CRM records.
5

List webhooks

GET action webhook-list to audit configured endpoints.

Expected result: You can see URLs, events, enabled state, and recent delivery state.
6

Delete stale webhooks

POST action webhook-delete with webhook ID.

Expected result: Old endpoints stop receiving events.
How to test it: Register a test endpoint, trigger a live-support event, verify the signature, and confirm your handler returns 2xx.
ProblemFix
Signature does not matchUse the raw body, not parsed JSON, and confirm the correct webhook secret.
Webhook receives no eventsConfirm the event list includes the event you are testing and the endpoint is HTTPS.
Webhook times outAcknowledge quickly and process long work asynchronously.

What to do next: Link engineers to /api-docs for endpoint details and examples.

Register webhook
curl -X POST "https://akhsrklbijflesmcqxur.supabase.co/functions/v1/public-api" \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "webhook-register",
    "url": "https://your-crm.example.com/semchat/webhook",
    "events": ["handoff.requested", "message.user", "handoff.resolved"]
  }'
Verify webhook signature
import crypto from 'node:crypto';

function verifySemChatSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature || ''),
    Buffer.from(expected)
  );
}
Endpoint map

Use the action-based public API correctly

What this is for: Use this when choosing the right action for a feature.

Before you start
  • Every request uses the same public-api function URL.
  • GET actions use query parameters. POST actions use JSON body.
  • Send x-api-key on all requests.
How to test it: Call usage and list-bots as a smoke test after any API key or endpoint change.
ProblemFix
Method mismatchUse the method shown in the endpoint table. Some actions are GET-only or POST-only.
Missing required valueCheck botId, conversationId, webhook id, and action spelling.

What to do next: Use Quick Start for first requests, then /api-docs for the full reference.

MethodActionPurpose
GETlist-botsList all bots available to the API key owner.
GETget-botFetch one bot configuration by bot ID.
POSTchatSend a visitor message to a bot and return the AI reply.
GETconversationsList recent conversations for a bot, up to 100 records.
GETusageReturn plan, credits, bot count, conversations, and API key usage.
GETlive-support-listList conversations waiting for or handled by a human agent.
GETlive-support-messagesFetch a handoff thread with messages and visitor info.
POSTlive-support-replySend a human-agent reply from an external system.
POSTlive-support-claimClaim a waiting handoff conversation.
POSTlive-support-resolveResolve the handoff or return control to AI.
POSTwebhook-registerRegister an HTTPS webhook endpoint.
GETwebhook-listList webhook registrations without returning secrets.
POSTwebhook-deleteDelete a webhook registration by ID.
14

Engineer Guide: Add Features

Add routes, dashboard navigation, bot-builder settings, Supabase tables/functions/migrations, API docs, public documentation, SEO checks, and local verification.

App feature workflow

Add an app route, page, navigation item, and docs entry

What this is for: Use this when adding a new customer-facing dashboard feature.

Before you start
  • Create a branch before editing.
  • Identify whether the feature belongs in the app repo or public sem.chat frontend repo.
  • Inspect existing route, sidebar, i18n, and settings patterns before adding new structure.
1

Add the route

Update src/App.tsx with a protected route for customer pages, or a public route only when the page must be public.

Expected result: The URL resolves in the app without hitting NotFound.
2

Create or update the page component

Use existing page patterns, data loading, empty states, loading states, and permissions.

Expected result: The feature behaves consistently with the dashboard.
3

Add dashboard navigation

Update the sidebar/nav source with label, icon, route, and plan gates if required.

Expected result: Users can discover the new page from the app shell.
4

Add bot-builder tab or setting

If the feature belongs to a bot, add it inside Bot Builder tabs and persist it through existing save flows.

Expected result: Bot-specific configuration is saved with the bot, not stranded in local state.
5

Add Supabase schema/function changes

Create migrations for tables/policies and edge functions for server-side work.

Expected result: Database and server behavior can be deployed repeatably.
6

Update API shape if public

Add or extend action handling in supabase/functions/public-api/index.ts and document x-api-key behavior.

Expected result: Integrations can use the feature safely.
7

Update app docs and public documentation

Update in-app developer docs and this /documentation page with screenshots and click-by-click steps.

Expected result: Users and engineers see the feature in both places.
8

Run checks

Run app tests/build, SEO optimizer in the public site, sitemap checks, and browser verification.

Expected result: The feature works locally and the public site remains crawlable.
How to test it: Open the new route, use the feature end to end, inspect console/network errors, and verify any database changes from the UI.
ProblemFix
Route works but nav does not highlightCheck sidebar route matching and redirect paths.
Data works locally but not deployedConfirm migration, RLS policies, and edge function environment variables.
Public docs missing from sitemapRun the SEO optimizer and inspect sitemap.xml for the canonical URL.

What to do next: Capture real documentation screenshots whenever the UI changes.

Docs maintenance workflow

Update this public documentation page after product changes

What this is for: Use this when screenshots, workflows, API behavior, or navigation changes.

Before you start
  • Use safe demo data only.
  • Never expose real customers, emails, payment details, API keys, or private conversations.
  • Update the English manual first, then refresh every localized documentation page before SEO checks.
1

Audit the changed route

Open the app route and identify what changed visually and procedurally.

Expected result: You know which guide, screenshot, and troubleshooting rows need edits.
2

Capture a real sanitized screenshot

Use a demo workspace, capture the actual app route, and mask secrets before saving WebP assets under assets/documentation.

Expected result: The screenshot comes from the real UI and is safe to publish.
3

Update the guide

Edit the relevant What this is for, Before you start, Steps, Expected results, Test, Troubleshooting, and Next sections.

Expected result: The guide tells users what to click and what should happen after each click.
4

Update navigation if needed

Add the section to the sticky TOC, mobile section picker, and visual index if it is a major page.

Expected result: Readers can find the new content quickly.
5

Run SEO tooling

Run node tools/seo-optimize-static-pages.js and node tools/seo-optimize-static-pages.js --check.

Expected result: Canonical, metadata, sitemap, and robots output stay correct.
6

Run cleanup and diff checks

Run node tools/static-translation-cleanup.js --audit and git diff --check.

Expected result: Static translations and whitespace are clean.
7

Browser verify

Serve the site locally and test /documentation on desktop and mobile.

Expected result: Images load, search works, copy buttons work, TOC highlights, and layout does not overlap the cookie banner.
How to test it: Search for the changed feature name on /documentation and confirm the correct guide block appears.
ProblemFix
Screenshot markers drift on mobileKeep markers inside the screenshot image or use responsive marker coordinates.
Search misses the new guideAdd useful keywords to data-title and include the exact product terms users search for.
Localized docs become staleAfter editing the English manual, refresh each localized documentation page, rerun the SEO optimizer, and confirm sitemap.xml includes every documentation URL.

What to do next: Commit the docs page, assets, header/footer links, .htaccess, and sitemap changes together.

Need the focused API reference?

The older /api-docs page remains available for endpoint-level API details.

Open API Docs