Everything you need to know
Complete guide to building and managing your AI front desks with shamz.ai
Getting started
Sign up, finish onboarding, pick your first skill, and embed the widget. Most customers go from zero to a live AI front desk in under 30 minutes.
- An email address (we use Auth0; no credit card required for the 30-day trial)
1.1Create your account
Open shamz.ai and click Start free trial. The 7-step onboarding wizard collects your company details (name, website, industry), country and currency, your first chatbot's name and slug, your plan, your first skill, and business hours. We only ask for an email address; you sign in with Auth0 at the end.
1.2Pick your first skill
Choose one of: Appointments, Service Desk, Knowledge Base, Lead Management, or E-commerce. You can add more skills later from Dashboard → Skills. The choice mainly determines which guided wizard runs next.
1.3Configure the skill
The skill wizard walks you through everything that's specific to that skill — services and staff for Appointments, categories and SLAs for Service Desk, etc. See the dedicated section below for each skill.
1.4Test in the dashboard preview
Open Dashboard → Chatbots → your bot → Preview. Send a few test messages to confirm the welcome message, suggestions, and core flows work the way you expect.
1.5Embed the widget on your website
From Dashboard → Chatbots → Embed, copy the <script> snippet and paste it before </body> on your website. Add your production domain to the Allowed Domains list (the widget refuses to load on un-listed origins).
1.6Connect channels (optional but recommended)
Hook up WhatsApp Business and/or Instagram Direct so customers can reach the same AI front desk from messaging apps. See the WhatsApp and Instagram sections below.
- If your slug is taken, the wizard suggests alternatives in real time.
- Selecting a country auto-sets the timezone — you can override it later in Settings → Account.
Appointments skill
Lets customers book, reschedule, and cancel appointments via chat or WhatsApp. Best for clinics, salons, repair shops, and any business where a slot of time is the unit being booked.
- An active Appointments skill (created during onboarding or via Dashboard → Skills → Add)
- At least one service and one staff member
2.1Define your services
Go to Dashboard → Skills → your Appointments skill → Services. Create one entry per appointment type with name, duration in minutes, optional buffer, optional price and currency. Add an Arabic name (name_ar) so the bot can offer it in Arabic chats.
2.2Add locations (optional)
If you have more than one branch, add each as a Location with address and phone. Customers will be asked to pick a location during booking.
2.3Add staff
Under the Staff tab, add each person who can take bookings. Required: name and email. Optional: specialties, photo, and which services they can deliver. Without at least one active staff member the booking flow won't return any slots.
2.4Set work schedules
For each staff member, define the weekly schedule: working hours per day, breaks, and any time off. Schedules drive slot availability — if a customer asks for Monday at 3 PM, we look up who's working then.
2.5Configure intake fields (optional)
Add custom fields the bot should collect at booking time — patient ID, insurance number, vehicle plate, etc. They're stored on the appointment and surfaced to your team.
2.6Connect a calendar (optional)
Under Calendar Sync, link your Google or Outlook calendar so confirmed appointments sync both ways. Cancellations and reschedules in either system propagate.
2.7Enable WhatsApp confirmations and reminders
If WhatsApp is connected, toggle Appointment confirmations and Appointment reminders ON in the WhatsApp tab. The bot will then send the customer a Meta-approved confirmation when they book and a reminder before the appointment.
- Business hours must cover at least one full service duration or the bot will report 'no slots available'.
- Buffer minutes (e.g. 15 min between dental cleanings) prevent back-to-back overbooking — set them on each service, not on the staff schedule.
Service Desk skill
Captures support tickets through chat, classifies them by category and priority, tracks SLA, and routes them to the right team. Best for IT helpdesks, hotel housekeeping, hospital service requests, and any post-sale support flow.
- An active Service Desk skill
- At least one category and one agent group
3.1Create service categories
Dashboard → Skills → your Service Desk skill → Categories. Add one per ticket type — Billing, Technical, Returns, Housekeeping, Maintenance, etc. Categories drive triage and routing.
3.2Add services per category
Each category contains one or more services with their own SLA (response time and resolution time in hours, default priority). Example: 'Account locked' under Technical → 30 min response / 2 h resolution / High priority.
3.3Set up agent groups
Under Agent Groups, create teams (Tier 1, Tier 2, On-call, etc.) and assign team members. Each group can be tied to specific categories so tickets route automatically.
3.4Configure intake fields
Decide what the bot should collect before opening a ticket — order number, room number, asset ID, attachment. Mark required fields so the ticket isn't created with gaps.
3.5Set business hours and escalation
Under Business Hours, define when the team is online. SLAs pause outside business hours. Add an escalation path so tickets at risk of breaching SLA get auto-flagged to a manager.
3.6Enable WhatsApp ticket updates
In the WhatsApp tab, toggle Ticket status updates ON. Customers get a Meta-approved message every time their ticket changes state (created → in progress → resolved).
3.7Verify in the inbox
Send a test request through the widget, then open Dashboard → Inbox → Tickets. The new ticket should appear with the correct category, priority, and SLA timer.
- Don't over-categorize on day one. Three to five categories is usually enough; you can always split them later as patterns emerge.
- If the bot keeps misrouting tickets, check that each category's description gives the AI enough context (one or two clear sentences).
Knowledge Base skill
Answers frequently asked questions from your own content — manual FAQs, uploaded documents, and crawled website pages. Best for product Q&A, policy questions, and any 'we get asked this all the time' surface.
- An active Knowledge Base skill
- At least one of: an FAQ entry, an uploaded document, or a website URL we can crawl
4.1Add manual FAQs
Dashboard → Skills → your KB skill → FAQs. Add Q&A pairs by category. Both the question and the answer can be in English and Arabic; the bot picks the customer's language at runtime.
4.2Upload documents
Under Upload & Scrape, drag in PDFs, Word docs, or text files. We chunk them, embed them, and use them as answer sources with citations. Each chunk shows a 'Used N times' counter so you can see what's actually being read.
4.3Scrape your website
Paste your website URL. The crawler follows internal links (same domain only) and indexes the pages. Progress streams live in the dashboard; large sites take a few minutes.
4.4Review unanswered questions
When the bot can't answer with confidence, the question is logged automatically under Unanswered Questions with a 'times asked' counter. Review the list weekly — the highest-frequency gaps are the ones to fill first.
4.5Use Draft with AI
On any unanswered question, click Draft with AI to generate a candidate answer based only on your existing FAQs and documents. Edit and approve before publishing — nothing auto-publishes, by design.
4.6Test in the preview
Ask a few sample questions in the chatbot preview. Check that answers cite the right source and that the language matches the question.
- AI-drafted answers never use outside knowledge — they only synthesize from your sources, so they're safe for regulated verticals.
- Re-scrape your website on a schedule (every few weeks) so new policy pages and product updates are picked up.
Lead Management skill
Captures sales leads from chat, scores them, assigns them to a rep, and notifies the team. Best for sales teams that already get inquiries through their site or social channels.
- An active Lead Management skill
- At least one team member with role Owner, Admin, Manager, or Rep and Receive leads = on
5.1Define capture fields
Dashboard → Skills → your Lead Management skill → Lead Capture. Pick which fields the bot must collect (name, email, phone, company) and which are optional. The bot asks for them naturally during conversation.
5.2Set scoring rules
Under Scoring Rules, define how a lead becomes Hot / Warm / Cold based on attributes (e.g. country = UAE +10, deal_value > 5000 +50, company_size > 100 +30) and behavior (mentioned 'demo', uploaded a document).
5.3Choose assignment mode
Round-robin distributes leads evenly across eligible reps. Manual leaves owner_user_id empty for you to assign yourself. Round-robin is the recommended default for any team with two or more reps.
5.4Set the SLA
Define how fast a rep should follow up — Hot leads typically 15 min, Warm 60 min, Cold 240 min. The bot creates a Task with the corresponding due date and surfaces it in the rep's queue.
5.5Wire up notifications
Email is always sent on assignment. To also ping reps on WhatsApp, set their whatsapp_phone in Settings → Team and toggle 'New lead assigned (notify rep)' ON in the WhatsApp tab. The first toggle ON auto-provisions the Meta template.
5.6Push to your CRM (optional)
Connect Zoho or HubSpot under Integrations. Qualified leads sync as Contacts/Leads in your CRM with full conversation context, source, and score.
5.7Verify with a test lead
Send a test inquiry through the widget. Check Dashboard → Leads — the new lead should appear with owner_user_id set, score label visible, and a Task created with the right due date.
- If a lead doesn't get auto-assigned, the most common cause is that no team member has Receive leads = on. Check Settings → Team.
- WhatsApp templates need Meta approval (typically minutes-to-hours). Until APPROVED, the WhatsApp send is skipped silently and only the email goes out.
E-commerce skill
Connects your store, lets the bot search products, look up orders, and recover abandoned carts. Best for any merchant on Shopify, Salla, WooCommerce, Zid, or Magento.
- An active E-commerce skill
- Admin access to your store
6.1Pick your platform
In the Store step, choose Shopify, Salla, WooCommerce, Zid, or Magento. Shopify and Salla use OAuth (one-click install); WooCommerce, Zid, and Magento use API keys you generate in your store admin. See the 'Connect your store' section below for platform-specific steps.
6.2Connect the store
Follow the platform's connection flow. Once connected, we sync your product catalog (name, price, stock, images, variants). Large catalogs (10k+ SKUs) take a few minutes for the initial sync.
6.3Configure the catalog
Under Catalog, choose what the bot can show: prices, stock badges, sort order (popular / newest / price). Hide categories you don't want surfaced in chat.
6.4Enable order support
Under Orders & Returns, toggle on Order tracking and Returns. Customers can ask 'where is my order?' and the bot looks it up by email + order number, with status, tracking link, and ETA.
6.5Turn on engagement features
Cart recovery, restock alerts, and review requests are off by default (they're marketing-template messages billed by Meta). Toggle them on individually as you're ready, and approve the Meta templates that get auto-provisioned.
6.6Test the product search
In the preview, ask about a specific product or category. Confirm the bot returns results with images, prices, and 'Add to cart' or 'View on store' links.
- If product images don't show, check that your store sets the og:image / featured image — we use the platform's default product image.
- Cart recovery requires that the customer initiated the conversation in the past 24 hours OR opted in via a marketing template. Meta enforces this.
Connect WhatsApp
Routes WhatsApp messages from your business number to the same AI front desk that powers your website widget. Two paths: Embedded Signup (recommended, ~5 minutes) or manual.
- A Meta Business Account with WhatsApp Business API access
- Admin role on the Meta Business Account
- A phone number not currently registered on personal WhatsApp
7.1Open the WhatsApp tab
Dashboard → Settings → WhatsApp. You'll see two options: Connect with Facebook (Embedded Signup) and Connect manually.
7.2Run Embedded Signup (recommended)
Click Connect with Facebook. A Meta popup walks you through choosing or creating a Meta Business Account, your WhatsApp Business Account (WABA), and the phone number to use. Verify the phone via SMS or call. We exchange the OAuth code for an access token, phone_number_id, and waba_id automatically.
7.3OR connect manually
If you already have direct API credentials, click Connect manually and paste your access_token (long-lived), phone_number_id, and waba_id. Token is encrypted at rest. Useful when your IT team manages the Meta Business Manager directly.
7.4Configure the webhook in Meta (manual path only)
If you used the manual path, copy the webhook URL and verify token from the WhatsApp tab into your WABA's webhook configuration in Meta Business Manager. Embedded Signup does this for you.
7.5Toggle outbound notifications
Under Outbound notifications, turn on what you want: Appointment confirmations, Appointment reminders, Ticket status updates, New lead assigned, Cart recovery, Restock alerts, Review requests. Each toggle ON auto-provisions the corresponding Meta template.
7.6Wait for Meta to approve templates
Templates start in PENDING status and move to APPROVED in 1–24 hours (sometimes minutes). Until APPROVED, outbound sends for that template are skipped silently — the email assignment notice still goes out, so reps aren't blocked.
7.7Send a test message
From your personal WhatsApp, message your business number. The AI front desk should reply in under a few seconds. Test in both English and Arabic to confirm language detection.
- Phone numbers already on personal WhatsApp must be deregistered before they can be used for Business API. Plan for this — it's a 24-hour cooldown on Meta's side.
- Marketing templates (cart recovery, restock alerts, review requests) cost ~$0.03–$0.15 per conversation, billed by Meta directly to your WABA payment method. Utility templates are usually $0.01–$0.05.
Connect Instagram Direct
Routes Instagram DMs to your AI front desk. Replies go out from your business profile; the bot can also recognize story mentions and product tags.
- An Instagram Business Account (not Personal or Creator)
- The Instagram account linked to a Facebook Page you administer
8.1Open the Instagram tab
Dashboard → Settings → Instagram. You'll see Connect with Facebook (Business Login) and Connect manually.
8.2Run Business Login
Click Connect with Facebook. A Meta popup asks you to grant access to your Instagram Business Account and the Facebook Page it's linked to. We exchange the OAuth code for an Instagram User ID and a long-lived Page access token.
8.3OR connect manually
Paste a Page access token (long-lived) and the Page ID. You can generate these in Meta Business Manager under Business Settings → Accounts → Pages → token tools.
8.4Verify the webhook
Embedded Signup configures the webhook for you. For manual setups, copy the webhook URL and verify token into your Page's Messenger / Instagram webhook configuration in Meta.
8.5Enable DM features
In the Instagram tab, toggle on what you need: DM auto-reply, Story mention auto-reply, Lead capture from DMs, Content sync (so the bot knows about your latest posts and product tags).
8.6Send a test DM
From a personal Instagram account, send a DM to your business profile. The bot should reply within a few seconds. Story mention auto-reply triggers when someone @-mentions your account in a story.
- Page access tokens expire if your Facebook account changes its password or 2FA settings. We refresh proactively, but if delivery suddenly fails, the token is the first thing to check.
- Instagram has a 24-hour customer-service window — once a customer DMs you, you can reply freely for 24h. Outside that window, only message tags (HUMAN_AGENT, ACCOUNT_UPDATE) are allowed.
Connect your store
Platform-specific steps for hooking up Shopify, Salla, WooCommerce, Zid, or Magento. The E-commerce skill picks one of these as its data source.
9.1Shopify (OAuth)
Pick Shopify in the wizard and enter your store URL (mystore.myshopify.com). Shopify OAuth opens in a popup and asks you to approve product, order, and inventory scopes. After approval, you're redirected back and we sync your catalog. Prerequisite: Shopify admin access.
9.2Salla (OAuth)
Pick Salla and follow the App Store install flow. If you came in via Salla's app marketplace, the website and skill are pre-selected for you. Direct (private) installs use the same OAuth flow with a private app variant. Prerequisite: Salla merchant account.
9.3WooCommerce (REST API keys)
Pick WooCommerce. In your WordPress admin, go to WooCommerce → Settings → Advanced → REST API → Add key. Set permissions to Read/Write. Copy the consumer_key and consumer_secret (the secret is shown only once). Paste them along with your store URL into the wizard.
9.4Zid (Access Token + Store ID)
Pick Zid. In your Zid merchant dashboard, go to Apps → API. Copy your Access Token and Store ID. Paste them into the wizard along with your store URL.
9.5Magento (Access Token)
Pick Magento. In Magento admin, go to System → Extensions → Integrations → Add. Set the resource access scope to include Catalog and Sales. Activate, copy the Access Token. Paste it into the wizard along with your store URL.
9.6Verify the connection
After saving credentials, the wizard runs a connection test and shows your store name plus product count. If the test fails, double-check the credentials and that the API user has product + order read access.
- For WooCommerce, the consumer_secret is shown only once during key generation. If you didn't copy it, you'll need to delete the key and create a new one.
- Uninstalling a Shopify or Salla app revokes the OAuth token immediately — you'll need to reconnect from the dashboard.
Embed the widget on your website
The chat widget is a single <script> tag that loads on any HTML page. It's the same widget that powers shamz.ai/chat/* standalone pages — so behavior is identical across embedded and standalone modes.
- An active chatbot
- Edit access to your website's HTML / template
10.1Copy the embed snippet
Dashboard → Chatbots → your bot → Embed. Copy the <script src="https://widget.shamz.ai/v1/shamz-widget.js"></script> tag plus the ShamzWidget.init({...}) block. The chatbotId is filled in for you.
10.2Paste before </body>
Add the snippet on every page where you want the widget to appear, just before the closing </body> tag. Most CMSes have a Custom HTML / Footer section for this — the snippet only loads ~30KB and is async, so it won't block your page render.
10.3Add your domain to Allowed Domains
Under Embed → Allowed Domains, add the domain where the widget will run (e.g. example.com). The widget refuses to load on un-listed origins, which prevents another site from impersonating yours. Add subdomains and staging domains too if needed.
10.4Customize the bubble
Under Bubble settings, set the position (bottom-right or bottom-left), size, color, and auto-open behavior. Auto-open shows a small tooltip on mobile and opens the chat directly on desktop. You can also pass language: 'ar' (or another supported code) at init time to force a specific language.
10.5Test in production
Load your site in a fresh browser tab. The bubble should appear in the bottom corner; clicking it opens the chat. Open the browser console — there should be no errors from widget.shamz.ai.
- If the widget doesn't appear, the most common cause is a missing entry in Allowed Domains. Open the browser console — we log a clear 'Domain not authorized' error.
- For React/Next.js sites, you can also use <Script src="..." strategy="afterInteractive" /> instead of plain <script>. Both work.
Branding & customization
Match the widget to your visual brand — colors, logo, welcome message, language, and the customer-intake fields the bot collects.
11.1Edit branding
Dashboard → Chatbots → your bot → Branding. Set primary color, secondary color, header background, font, and upload your logo. Live preview updates as you change values.
11.2Customize the welcome message
Under Welcome, set the bot's first message in English and Arabic (welcome_message and welcome_message_ar). Use it to set expectations: hours, what the bot can/can't do, who to reach for emergencies.
11.3Pick the bot's primary language
Set the chatbot's default language. The widget can override this at init time (?lang=hi etc.). Arabic dialect can be configured under Settings → Account → Arabic Chatbot Dialect (MSA, Saudi, Emirati, Egyptian, etc.).
11.4Add custom intake fields
Under each skill, add fields the bot must collect from customers — civil ID, vehicle plate, room number, insurance details. Each field has a name, type (text / email / phone / select), and required flag.
11.5Toggle pre-chat survey and post-chat review
Under Settings → Chat Behavior, decide whether to show a pre-chat survey (name + email before the conversation starts) and a post-chat review (1–5 stars + free comment after the conversation ends).
- The welcome message also appears as the og:description on standalone shamz.ai/chat pages — make it inviting.
- Custom intake fields are stored on the customer record and reused across conversations, so you only collect them once.
Voice, image & document AI
The widget accepts voice notes, photos, and document uploads on every channel — web, WhatsApp, Instagram. We transcribe, OCR, and extract structured fields automatically.
12.1Voice transcription (Whisper)
Customers tap the microphone in the widget and record. We transcribe with Azure OpenAI's gpt-4o-mini-transcribe (Whisper-class) and feed the text into the regular conversation. Works with Arabic (including dialect), English, and the other supported languages.
12.2Image upload
Customers can drop in JPG, PNG, or HEIC images. The bot can recognize products (for E-commerce), document types (ID, insurance card, receipt), and scenes (for Service Desk — 'photo of broken AC').
12.3Document OCR (Mistral Document AI)
PDFs and multi-page documents are processed with Mistral Document AI. We extract structured fields — names, ID numbers, dates, amounts — in Arabic and English, and pre-fill the appointment / ticket / lead intake form so the customer doesn't retype them.
12.4Tune what's accepted
Under Settings → Chat Behavior, you can disable file uploads entirely or restrict to specific file types. Useful for regulated verticals where some uploads must go through a different channel.
- OCR confidence is shown in the dashboard for each extracted field — anything below 80% gets flagged for human review before it auto-fills.
- Voice and OCR both count against your plan's monthly conversation budget, but each at a different multiplier — see Settings → Usage for the breakdown.
Analytics & reporting
Track conversations, lead conversion, ticket SLA, and usage. Each skill has its own dashboard tab.
13.1Conversation analytics
Dashboard → Analytics → Conversations. See total conversations over time, peak hours, top intents (booking, support, browsing), and language breakdown. Useful for staffing decisions and content gaps.
13.2Lead analytics
Dashboard → Analytics → Leads. Track lead volume by source (chat, WhatsApp, Instagram, manual), conversion rate (lead → won), score distribution (hot/warm/cold), and rep performance (response time, conversion per rep).
13.3Service Desk analytics
Dashboard → Analytics → Tickets. SLA performance (% on-time response and resolution), volume by category, escalation rate, and average resolution time.
13.4E-commerce analytics
Dashboard → Analytics → Commerce. Cart recovery rate, top searched products, returns volume, and AI-driven sales attribution (conversations that led to a checkout).
13.5Plan usage
Dashboard → Usage. Conversation count vs. plan limit, voice minutes, OCR pages, WhatsApp messages by template type. Set alerts so you're notified before you hit the limit.
- All charts respect a date range — use it to compare a campaign week to the previous week.
- Export any chart as CSV from the … menu — handy for monthly reporting to your team.
Need more help?
Can't find what you're looking for? Our support team is here to help.