# MonCha documentation

This file is generated from the same articles as https://dev-moncha.com/docs/ — every sidebar page, in order.

Canonical site: https://dev-moncha.com/
Dashboard: see links inside each article.
Support: support@moncha.co
Shorter map: https://dev-moncha.com/llms.txt
Human-readable docs: https://dev-moncha.com/docs/

---

# Overview

Everything you need to train, customize, and ship a MonCha support agent — from your first crawl to webhooks and voice.

New here? Start with the [Quickstart](https://dev-moncha.com/docs/quickstart/) — you'll have a bot answering questions from your own website in about five minutes.

## Core ideas

- **Grounded answers.** Your bot answers only from the knowledge base you give it, cites its sources, and declines when it doesn't know.
- **One message = one answer.** Your customers' questions never count against your quota.
- **Bots are independent.** Each bot has its own knowledge, design, conversations, and embed snippet. Extra bot slots are add-ons with isolated quotas.

## Pages

- [Quickstart](https://dev-moncha.com/docs/quickstart/)
- [Install the widget](https://dev-moncha.com/docs/install/)
- [Knowledge base](https://dev-moncha.com/docs/knowledge-base/)
- [Bot settings](https://dev-moncha.com/docs/bot-settings/)
- [Customize the widget](https://dev-moncha.com/docs/customize/)
- [Voice](https://dev-moncha.com/docs/voice/)
- [WhatsApp](https://dev-moncha.com/docs/whatsapp/)
- [Email Inbox](https://dev-moncha.com/docs/inbox/)
- [Leads](https://dev-moncha.com/docs/leads/)
- [Human support (tickets)](https://dev-moncha.com/docs/tickets/)
- [Bookings](https://dev-moncha.com/docs/bookings/)
- [Conversations & analytics](https://dev-moncha.com/docs/analytics/)
- [Functions](https://dev-moncha.com/docs/functions/)
- [Webhooks](https://dev-moncha.com/docs/webhooks/)
- [API & MCP reference](https://dev-moncha.com/docs/api/)
- [Plans & quotas](https://dev-moncha.com/docs/plans/)
- [Enterprise](https://dev-moncha.com/docs/enterprise/)

---

# Quickstart

From zero to a bot answering customers on your site — about five minutes.

Human page: https://dev-moncha.com/docs/quickstart/

## How to install MonCha

From a new account to a live widget: create an account, train the bot on your site, then paste one script tag.

## 1. Create your account

Sign up at [app.dev-moncha.com](https://app.dev-moncha.com/signup) with Google or email. Every new account starts on a 7-day Growth trial — no credit card.

## 2. Teach it your content

Go to Knowledge Base → Add source and paste your website URL. MonCha discovers your pages, crawls them, and builds a searchable index. You can also upload PDFs and Word docs, add YouTube videos, write exact Q&A pairs, or paste raw text.

Watch the status column — documents move from queued to processing to ready. Fresh content takes a minute or two to become searchable.

## 3. Try it

Open Playground and ask your bot something only your website would know. If the answer is wrong or missing, add a Custom Response in the Knowledge Base — an exact Q&A pair always wins.

## 4. Make it yours

Under Widget, set the bot name, colors, welcome message, and quick prompts, with a live preview. Under Bot settings, pick the reply language, persona, and what the bot should say when it doesn’t know.

## 5. Put it on your site

Copy the snippet from Install and paste it before your closing </body> tag:

```
<script src="https://cdn.dev-moncha.com/moncha-widget.iife.js"></script>
<script>
  MonCha.init({ tenantId: 'YOUR_TENANT_ID' });
</script>
```

On WordPress? Use the [free plugin](https://dev-moncha.com/wordpress/) instead. Want the chat embedded inside a page rather than floating? See the Install guide.

## 6. Lock it down

Each bot has its own Allowed domains list, under Bot settings, for the bot selected in the sidebar. Add every domain (and its subdomains are covered automatically) allowed to embed it — leaving the list empty allows any domain; adding even one locks that bot to only the listed domains, and it stops rendering elsewhere.

## What next

- [Turn on voice so customers can just talk.](https://dev-moncha.com/docs/voice/)
- [Capture leads and offer human handoff.](https://dev-moncha.com/docs/leads/)
- [Watch what customers ask — especially the unanswered ones.](https://dev-moncha.com/docs/analytics/)

---

# Install the widget

Three ways to put your bot in front of customers.

Human page: https://dev-moncha.com/docs/install/

## Install with an AI agent (fastest)

If you use **Claude Code**, **Cursor**, **GitHub Copilot**, **Codex**, or **Windsurf**, you don't have to edit anything by hand. Paste this one line into your agent:

```
Fetch https://dev-moncha.com/agent-setup/prompt.md and follow it to install MonCha on this site. My tenantId is YOUR_TENANT_ID.
```

Your agent reads the published instructions, detects your framework (Next.js, React, Vue, Astro, WordPress, Shopify…), drops the widget in the right place, wires up multilingual pages correctly, and connects the MonCha [MCP server](https://api.dev-moncha.com/mcp) so it can manage your bot — add knowledge, ask the bot, pull analytics — without leaving your editor.

Grab your Tenant ID from **Dashboard → Install** (it's pre-filled in the copy button there). The instructions are published at `https://dev-moncha.com/agent-setup/prompt.md`, so you or your agent can verify them at any time.

Prefer to do it manually? Everything below gives the same result.

## Floating bubble (most common)

Paste this before your closing `</body>` tag. The launcher appears in the corner; the design comes from your dashboard, so you never need to change this snippet again.

```
<script src="https://cdn.dev-moncha.com/moncha-widget.iife.js"></script>
<script>
  MonCha.init({ tenantId: 'YOUR_TENANT_ID' });
</script>
```

### Running more than one bot?

Pass the bot's id — find it on the Install page after selecting that bot. Plan-included bots and extra bots both embed this way:

```
MonCha.init({ tenantId: 'YOUR_TENANT_ID', chatbotId: 'YOUR_BOT_ID' });
```

## Inline (embedded in a page)

Puts the chat inside a page — a help center, a contact page — instead of a floating bubble. No script needed; it's an iframe:

```
<iframe
  src="https://api.dev-moncha.com/embed/YOUR_TENANT_ID"
  width="100%" height="600"
  style="border:1px solid #eee;border-radius:12px"
  allow="microphone" title="Chat with us"></iframe>
```

Keep `allow="microphone"` if you want voice to work inside the iframe. Add `?chatbotId=…` to the src to pick a specific bot. Because an iframe can't see the host page's language, pass it explicitly per language variant — `?language=ja-JP` (e.g. use the iframe on your `/jp` page with `…/embed/YOUR_TENANT_ID?language=ja-JP`).

## Inline container (no iframe)

Prefer to render the chat directly in your page markup (no iframe isolation)? Add a `div` with the widget class and your IDs, then load the script with `?hideBubble=true`. The widget mounts inside the div automatically — no `init()` call, and you can add as many containers as you like:

```
<div class="MonCha-chat-widget"
  data-MonCha-tenant="YOUR_TENANT_ID"
  data-MonCha-chatbot="YOUR_BOT_ID"
  style="width:100%;height:600px"></div>

<script src="https://cdn.dev-moncha.com/moncha-widget.iife.js?hideBubble=true" async></script>
```

## WordPress

Install the [free MonCha plugin](https://dev-moncha.com/wordpress/), paste your Tenant ID under **Settings → MonCha**, and the widget appears site-wide. No theme editing.

## Options reference

- `tenantId` — required. From **Dashboard → Install**.
- `chatbotId` — optional. Defaults to your first bot.
- `mode` — `'floating'` (default) or `'inline'`.
- `hideButton` — keep the floating widget but hide its bubble; open it only via `MonCha.open()`.
- `primaryColor`, `position`, `language` — override the dashboard settings for this embed only.

## Control it from your code (SDK)

After the snippet loads, `window.MonCha` lets you drive the widget from your own buttons, links, or app logic:

```
MonCha.open()            // + close() / toggle(); open({ reset: true }) starts fresh
MonCha.isOpen()          // true/false
MonCha.sendMessage('What are your pricing plans?')   // send now
MonCha.prefill("Hi, I'd like help with…")            // fill the box, user edits & sends
MonCha.reset()           // start a new conversation
MonCha.reload()          // re-mount after client-side navigation

// Steer the bot for the current page (prepends/appends to its instructions)
MonCha.setContext({
  prefix: 'You are a sales assistant. Guide users to book a demo.',
  suffix: 'Current page: Pricing',
})

MonCha.setCss(':host #header { background: #072A54 }')  // custom CSS
```

Migrating from another provider? The same actions also work as a command queue — `MonCha.push(['do','message:send','hi'])`, `MonCha.push(['set','context',[prefix, suffix]])` — and can be buffered before the script loads with `window.MonCha = window.MonCha || []`.

### Identify signed-in visitors

If your site has logged-in users, call this after login (and again on logout to clear it) so their [leads](https://dev-moncha.com/docs/leads/) and [tickets](https://dev-moncha.com/docs/tickets/) carry their real name/email instead of relying on the AI to extract them:

```
MonCha.identify({ userId: 'usr_8f21', email: 'priya@example.com', name: 'Priya Sharma' })
```

Add a server-computed `userHash` — HMAC-SHA256 of `userId` with the identity secret shown on **Dashboard → Install** — to prove the identity. That verifies the visitor, so their tickets follow them across devices/browsers instead of staying tied to one. Without it, `identify()` still labels the contact, just per-device.

## Languages — one snippet, every language

You don't need a different snippet per language. The widget detects the page language **once, when `MonCha.init()` runs**, in this order: an explicit `language` passed to `init()` (if not `'auto'`) > `<html lang>` > a `?lang=`/`?locale=`/`?language=` query string > the URL path (e.g. `/jp/`) > the visitor's browser — then greets and replies in it, limited to the languages you allow in [Bot settings → Language](https://dev-moncha.com/docs/bot-settings/). A visitor on `/jp` gets a Japanese bot automatically; one on `/th` gets Thai.

If your site carries the locale in a non-standard query key, name it with `langParam` — e.g. `langParam: 'ui_lang'` reads `?ui_lang=jp`. To pin one fixed language on a page instead of auto-detecting, pass `language`:

```
MonCha.init({ tenantId: 'YOUR_TENANT_ID', language: 'ja-JP' });
```

Codes: `en-IN`, `ja-JP`, `ko-KR`, `zh-CN`, `ms-MY`, `id-ID`, `th-TH`, `vi-VN`, `fil-PH`, `ar-AE`, `hi-IN`, `ta-IN`, `sw-KE`, `ha-NG`, `yo-NG` and more. The same `language` field works on the [REST API](https://dev-moncha.com/docs/api/) `/chat` call and the MCP `ask_bot` tool.

### Header language switcher → widget language (no page reload)

**Required:** when the visitor changes language in your site header, the MonCha widget must switch too — greeting, UI, and replies — **immediately, with no page reload**. Because language is resolved once at `init()`, a header / SPA switcher that changes locale without a full reload needs an explicit call. Don't call `MonCha.init()` from a static `index.html` in that case; call it once your i18n store is ready, then call `MonCha.setLanguage()` on every header locale change:

```
// After your i18n store resolves the initial locale:
MonCha.init({ tenantId: 'YOUR_TENANT_ID', language: 'ta-IN' });

// On every header language change — widget updates live, no reload:
MonCha.setLanguage('ja-JP');
```

`setLanguage()` swaps the widget language in place — no refresh, no manual cleanup, and no duplicate widget even if you call `init()` more than once. Acceptance test: change language in the header → widget greeting/UI updates immediately.

## Allowed domains

Domain lock is **per bot**, not account-wide. Select the bot in the sidebar, then go to **Bot settings → Allowed domains** and list the domains permitted to embed *that* bot — every other bot keeps its own separate list. A domain you add also covers its subdomains automatically (e.g. adding `example.com` allows `app.example.com` too).

By default the list is empty, which means the widget loads on **any** domain — fine for testing, but it also means anyone who copies your snippet can embed your bot and spend your quota. Add at least one domain to lock it down: once a bot has one or more domains listed, its widget stops rendering everywhere else, and the chat/token/lead/ticket APIs reject requests from origins that aren't on the list. Remove every domain again and the bot goes back to allowing all origins.

## Uninstall / delete a bot

Deleting a bot from the dashboard removes it immediately. On the next page load, the widget checks your bot id with MonCha — if that bot is gone, **the chat bubble does not render**, even if the embed snippet is still in your site's HTML.

The snippet itself is just a script tag on your frontend, so MonCha cannot delete that file for you. After you delete the bot:

- The widget disappears from integrated sites right away (no bubble, no chat).
- You should still remove the MonCha `<script>` / `MonCha.init(…)` (or WordPress plugin / iframe) from your site when you can, so you are not loading unused JavaScript.

When you delete a bot in the dashboard you must type the bot name exactly (same capitals and spelling) to confirm. The dialog also reminds you about this uninstall behavior.

## Temporarily turn a bot off (Active / Inactive)

Prefer not to delete? On **Bot settings**, toggle **Active / Inactive** next to Rename. Inactive bots stay in your account — Playground and dashboard still work — but the widget stops appearing on customer sites until you turn Active back on.

---

# Knowledge base

Everything your bot knows. It answers only from here — nothing else.

Human page: https://dev-moncha.com/docs/knowledge-base/

## Sources you can add

- **Website** — paste a URL. MonCha finds linked pages (set crawl depth and include/exclude paths) and lets you pick which to ingest.
- **Sitemap** — point at `sitemap.xml` to pull a clean list of pages.
- **Files** — upload PDF, DOCX, or TXT.
- **YouTube** — paste a video URL; the transcript becomes searchable content.
- **Text snippets** — paste content that lives nowhere on your site.
- **Custom responses** — exact question/answer pairs.

## Custom responses are your override switch

When a bot answers something wrong, don't fight the crawler — add a Custom Response. You write the question and the exact answer, and it wins over crawled content. This is the fastest way to fix a bad answer, and the most reliable way to control high-stakes replies (refunds, pricing, policies).

## Advanced crawl options

When adding a website you can control what gets read:

- **Main content only** — strips navigation, headers, and footers (on by default).
- **Include / exclude CSS selectors** — target `main` or drop `.comments`.
- **Include / exclude paths** — crawl `/docs/*` but skip `/blog/*`.
- **Custom headers** — pass an `Authorization` or `Cookie` header to crawl protected pages.
- **Depth & max pages** — how far to follow links, and a hard cap.

## Keeping content fresh

- **Manual resync** — re-crawl one document, or all of them, any time.
- **Auto-sync** — MonCha re-crawls on a schedule set by your plan (monthly on Growth, weekly on Scale). Ship a new pricing page tonight; your bot knows it tomorrow.

Deleting a document removes its content from the bot immediately, and frees the pages back into your quota.

## How pages are counted

One page = 2,500 characters of cleaned text. A long article may count as several pages; a short one counts as one. Re-syncing a document doesn't double-count it — only the difference is applied.

## Suggest FAQs from your content

On the **Widget** page, *Suggest from knowledge base* reads what you've indexed and proposes quick prompts your customers are likely to ask. Review them, keep the good ones.

## Per-bot knowledge

Each bot has its own knowledge base. Switch bots with the selector at the top of the sidebar — the Knowledge Base page always shows the selected bot's content. Your plan includes 1–3 bots; buy extra bot slots on Billing if you need more. Extra bots have their own page quota (same as that SKU's plan), not shared with the plan pool. See [Plans & quotas](https://dev-moncha.com/docs/plans/).

---

# Bot settings

How your assistant thinks, sounds, and answers.

Human page: https://dev-moncha.com/docs/bot-settings/

## Model

- **Fast** — best for most support queries. Quick, cheap, accurate on grounded answers.
- **Quality** — deeper reasoning for complex or nuanced questions. Slower.

## Language

**Default language** sets the first message and the fallback when nothing else is detected. Chat works in all 24 languages; voice is live in 12 across Asia today, with more rolling out — see [Voice](https://dev-moncha.com/docs/voice/).

**Language behavior** controls switching:

- **Match the visitor** (recommended) — the widget auto-detects the page language (from `<html lang>`, the URL like `/jp`, or the browser) and greets in it; if the customer then writes in another language, the bot follows theirs.
- **Fixed** — always reply in the default language, whatever the visitor writes.

**Supported languages** is the allowlist the bot may switch into — leave all on, or restrict it (e.g. only English + Japanese). Answers come from your knowledge base in whatever language you wrote it; MonCha bridges the language at answer time, so you don't maintain a separate KB per language. To translate the welcome message and quick prompts per language, use the widget's Localization tab. See [Install](https://dev-moncha.com/docs/install/) for per-page overrides.

## Conversation memory

How many previous exchanges the bot considers when replying (0–6). Higher means better follow-up questions (“and how much does *that* cost?”), at slightly higher cost per message.

## Fallback message

Sent verbatim when the knowledge base has nothing relevant. This matters: without a good fallback, a bot that doesn't know sounds evasive. A good one moves the customer forward — *“I don't have that yet. Email support@yourcompany.com and we'll sort it out.”*

MonCha never invents answers from general knowledge. If your content doesn't cover it, the bot says so.

## Instructions vs. persona

They're separate on purpose:

- **Instructions** — rules the bot must follow. What to do, what to avoid, how to structure answers.
- **Persona** — tone and voice. Warm and enthusiastic, or precise and formal.

## User data collection

Ask visitors for their name, email, or phone before or during the chat. Set it to **optional** (skippable) or **mandatory** (chat is blocked until submitted). Captured contacts land on your [Leads](https://dev-moncha.com/docs/leads/) page and trigger an email.

## Notification email

Where new leads, “talk to a human” requests, and [booking](https://dev-moncha.com/docs/bookings/) requests are sent. Defaults to your login email; set a shared inbox here if your team handles support together.

## Delete a bot

In Bot settings (or the Bots list), delete requires typing the bot name exactly. Once deleted, the widget stops appearing on integrated sites immediately — even if the embed snippet is still on the page. Remove the script when you can; see [Install → Uninstall / delete a bot](https://dev-moncha.com/docs/install/).

Deleting an extra bot does **not** cancel the paid slot. The slot stays on your subscription until you remove it on Billing. See [Plans & quotas → Buy Extra bots](https://dev-moncha.com/docs/plans/).

## Active / inactive

Use the **Active / Inactive** toggle next to Rename on Bot settings to take a bot offline without deleting it. While inactive, the widget stops showing on your website (same as a deleted bot for visitors). Playground, knowledge base, and the rest of the dashboard keep working so you can keep editing. Turn it back to Active and the widget appears again on the next page load.

---

# Customize the widget

Everything on the Widget page updates instantly on your live site — you never re-paste the snippet.

Human page: https://dev-moncha.com/docs/customize/

## Content

- **Bot name** and **tooltip** shown on the launcher.
- **Welcome message** — the first thing customers read.
- **Input placeholder**.
- **Disclaimer text** — a small line under the chat, for compliance notes.

## Appearance

- **Primary color** — header, buttons, and accents. Plus separate overrides for **link color**, the **launcher's background** (or make it transparent, for a PNG launcher icon with its own background), and the **voice orb** color during a live call.
- **Custom icons** — upload your own launcher icon, bot avatar, user avatar, and agent avatar (shown on ticket replies) instead of the defaults.
- **Font size** and **chat height**.
- **Icon size and shape** — circle, rounded, or square.
- **Position and offsets** — bottom-right or bottom-left, with separate offsets for desktop and mobile.
- **RTL** — right-to-left layout for Urdu and Arabic scripts.
- **Expand button** — adds a fullscreen toggle to the header.
- **External link** — an outbound link-out icon in the header, pointed at any URL you choose.

## Behavior

- **Auto-open** after N seconds on desktop or mobile.
- **Require terms** before chatting, with a link to your terms page.
- **Max messages per conversation** — cap how many replies one conversation can use (0/blank = unlimited); useful for controlling cost exposure per visitor.
- **Download transcript** — lets visitors save the chat as a text file.
- **Temporarily disable chat** — takes the bot offline everywhere it's embedded and shows a message you write, without touching the snippet or your knowledge base.

## Home screen

Shortcuts on the widget home (WhatsApp, Facebook Messenger, X, LINE, Booking) — at most two at a time. WhatsApp uses the number connected for this bot in [Integrations](https://dev-moncha.com/docs/whatsapp/); turn it on or off here or with **Show on website widget**. Facebook, X, and LINE need a public URL and logo. Booking needs **Enable booking** first.

## Quick prompts and follow-up chips

**Quick prompts** are the suggested questions on the welcome screen — the single best lever for getting customers to engage. Don't guess them: click *Suggest from knowledge base* and MonCha proposes questions grounded in what you've actually indexed.

**Follow-up chips** appear after each reply. Leave them on auto and the bot suggests relevant next questions, or supply a fixed list.

## Visibility

- **Hide source attribution** — the “answered from” links under replies.
- **Hide feedback buttons** — the thumbs up/down.
- **Hide refresh**.
- **Hide launcher tooltip** — the hint bubble above the chat icon.
- **Hide “Powered by MonCha”** — available as a separate add-on (not included in any plan). The add-on also unlocks a custom watermark: turn the branding text into a link to your own site, with your own logo.

## Localization

All 24 supported languages are translated out of the box — the bot-settings language picks the translation automatically, including the lead form and the “talk to a human” button. Use the Localization tab only to *override* a specific string with your own wording.

## Per-bot design

Each bot has its own widget config. Switch bots in the sidebar and style them independently. Extra bots work the same way — each has its own design and embed. See [Plans & quotas](https://dev-moncha.com/docs/plans/).

## Booking

Turn on **Enable booking** under Icon & position (or on the **Bookings** page) to add a calendar button to the widget. Visitors request a time; you still approve each request. See [Bookings](https://dev-moncha.com/docs/bookings/) for clinic, gym, salon, and hourly-hire setups.

---

# Voice

Your customers press the mic and speak. The bot listens, answers from your knowledge base, and speaks back.

Human page: https://dev-moncha.com/docs/voice/

## How it works

The mic button is built into the widget — nothing to enable. A customer taps it, speaks naturally, and the bot detects when they've stopped, transcribes, retrieves from your knowledge base, and replies out loud. They can interrupt mid-answer, just like a phone call.

## Languages

Voice runs on speech models tuned per language — so replies sound natural in Hindi, Tamil, or Telugu rather than machine-translated. Voice is live today in **12 languages across Asia**: English, Hindi, Tamil, Telugu, Kannada, Malayalam, Marathi, Bengali, Gujarati, Punjabi, Odia, and Urdu.

Text chat already works in all 24 languages, including Japanese, Korean, Chinese, Malay, Thai, Vietnamese, Indonesian, Filipino, and Arabic. Voice for East & Southeast Asia and Arabic is rolling out.

## Requirements

- Your site must be served over **HTTPS** — browsers block microphone access otherwise.
- Embedding inline? Keep `allow="microphone"` on the iframe:

```
<iframe src="https://api.dev-moncha.com/embed/YOUR_TENANT_ID"
  allow="microphone" width="100%" height="600"></iframe>
```

The customer's browser will ask their permission the first time. If they decline, chat still works normally.

## Voice minutes

Voice is metered separately from messages: 60 minutes on Starter, 180 on Growth, 600 on Scale. Minutes reset on your Stripe billing date each month and don't roll over. Need more? Buy Extra voice minutes (60, 180, or 600) on Billing — they stack on your plan pool (plan bots only). Extra bots have their own isolated voice minutes. Track usage on the Overview page. See [Plans & quotas](https://dev-moncha.com/docs/plans/).

## Multi-bot

Voice conversations are scoped to the bot in the embed — a customer talking to your storefront bot gets answers from that bot's knowledge base, never another's. Plan bots share the plan's voice pool; each extra bot uses only its own voice minutes.

## Tips

- Voice answers are read aloud, so keep your **fallback message** short.
- Set the bot language to the one most of your callers use; the bot will still follow a customer who switches.
- Test in the **Playground** before you ship.

---

# WhatsApp

Connect a WhatsApp Business number from Dashboard → Integrations, or get a number from MonCha billed monthly in your plan currency. MonCha answers there with the same knowledge as your website chat.

Human page: https://dev-moncha.com/docs/whatsapp/

## What it is

Connect a WhatsApp Business number to any one of your bots, and MonCha answers customers there with the exact same knowledge base, persona, and instructions as your website chat. It's the same bot — just another door in. There is no separate WhatsApp add-on: once a bot is live, WhatsApp is included.

Setup lives on **Dashboard → Integrations**. Each bot has its own WhatsApp row: **Not connected**, or **Connected ·** plus the phone number. You can connect a number you already own, or **Get a number** from MonCha (billed monthly) and attach it to a bot.

## Before you start

- Create at least one bot. If you have none, Integrations shows *Create a bot first to connect WhatsApp.*
- You need a **Facebook** login that can manage the business you want to use with WhatsApp.
- The number must be a **WhatsApp Business** number — not a personal WhatsApp account. If this number currently runs personal WhatsApp, delete that personal account on the phone first. WhatsApp will not let the same number be personal and Business at once.
- Have the phone nearby if you are adding a new number. WhatsApp sends a one-time code to that SIM.

## Connect WhatsApp — step by step

1. In the dashboard sidebar, select the bot that should answer WhatsApp (for example your gym bot, not a second brand). Each number is locked to *that* bot's knowledge base.
2. Open [Dashboard → Integrations](https://app.dev-moncha.com/dashboard/integrations). Find the **WhatsApp** card.
3. On that bot's row, click the green **Connect WhatsApp** button. The label switches to **Connecting…** while MonCha opens WhatsApp Business setup.
4. Log in with Facebook when asked. Use the Facebook that owns (or can create) this business — not a personal profile that has no access.
5. Choose or create the Facebook Business, then choose or create the WhatsApp Business account for it.
6. Choose the phone number:

- **You already have WhatsApp Business** — pick that number.
- **New SIM, never used for WhatsApp** — add the number and enter the code WhatsApp texts to the phone.
7. If this business already has more than one WhatsApp number, you will be asked to pick *which* number belongs to this MonCha bot. Pick one. The same number cannot be connected to two MonCha bots.
8. Finish the window. You land back on Integrations. The row should read **Connected ·** followed by the number (for example *Connected · +91 7397 366 612*).

If the window closes and Integrations still says **Not connected**, click **Connect WhatsApp** again — do not add the number in WhatsApp Manager alone. The number is only linked to the bot after this Integrations flow completes.

## Get a number from MonCha

On the WhatsApp card, under **Your WhatsApp numbers**, click **Get a number**. That opens a country picker. The price is a **monthly subscription** — not a one-time fee. You must tick *I understand this renews every month until I release the number* before checkout.

- Countries, stock, and which places need verification come from live availability. If a country is missing, we cannot sell it that day. Singapore and the United Kingdom typically need verification; the United States typically does not. Trust the flag on the country you pick, not a static list.
- Price is shown in **your billing currency** (USD, INR, SGD, MYR, or JPY) — the same currency as your plan after you have paid. If you have not paid yet, we use the currency for your location. You cannot pick a different currency at checkout.
- The underlying list price is in US dollars. For any other billing currency we convert at today's mid-market rate (the same class of rate you see on Google or XE) and round up so the charge is never below that dollar price. The amount on the picker is the amount Stripe charges each month.
- Some countries need business verification (usually 1–3 business days). You add a card now; the first month starts when the number is approved, not the day you add the card. Complete verification from the number row — **Continue verification**. Some countries also ask for **Finish identity check**.
- Out-of-stock countries that still accept a pre-order usually take 2–4 weeks. They are not instant.
- When the row says **Number ready**, choose a bot and click **Continue with Facebook** to finish WhatsApp Business setup — same Facebook steps as connecting a number you already own.
- If you close Facebook before it finishes, the number is *not* connected. The row will say WhatsApp is not connected yet, and that bot will show **Finish connecting**. Use that, or **Cancel** to free the number for another bot. Only after Facebook completes will the bot row say **Connected**.

A purchased number belongs to the workspace, not to one bot. Disconnect it from a bot to attach it to another. That does *not* stop the monthly charge. Click **Stop billing** to cancel the next month — WhatsApp keeps working until that date, then we remove the number automatically. You can also **Remove number** sooner if you do not need it. You cannot remove a number while the next month is still set to renew.

## One number per bot

Each bot connects its own number. A business with separate bots for Sales and Support connects a different WhatsApp number to each. Messages to one number never see the other bot's knowledge base. A bot that already has WhatsApp cannot connect a second number until you disconnect the first.

## Controls on Integrations

Once the row shows Connected, two switches appear under that bot:

- **AI replies** — on by default. MonCha answers WhatsApp with the same brain as the website widget. Turn it off to keep the number as a staff-only inbox: messages are still saved, but the assistant stays silent until a teammate replies.
- **Show on website widget** — on by default. Adds a WhatsApp shortcut on this bot's chat widget home screen so site visitors can tap through to that number. Turn it off if you want WhatsApp for inbound messages only, with no button on the site.

You can also show or hide that shortcut from **Dashboard → Widget → Home screen**. WhatsApp there uses the number connected here — you do not paste a `wa.me` link. Up to two shortcuts can be on at once (WhatsApp, Facebook Messenger, X, LINE, or Booking). See [Customize the widget](https://dev-moncha.com/docs/customize/).

## Try it

1. From a *different* phone than the connected number, send a WhatsApp message to the connected number (a simple “hi” is enough).
2. You should get a reply from the bot, using that bot's knowledge base.
3. Open **Dashboard → Conversations** to see the thread. The same conversation continues if the person writes again later. Leads are scored the same way as website chat — see [Leads](https://dev-moncha.com/docs/leads/) — using their WhatsApp number as the contact.

## Disconnect

On the bot's WhatsApp row, click **Disconnect**. Confirm when asked — this disconnects the number from that bot. Past conversations stay in your history. The widget shortcut disappears immediately and the bot stops answering that number.

If this was a number you already owned, click **Connect WhatsApp** to use WhatsApp again. If you bought the number from MonCha, click **Stop billing** on **Your WhatsApp numbers** — it keeps working until the paid month ends, then we remove it. You can also remove it immediately.

## Quota

Each AI reply on WhatsApp counts toward the same monthly message quota as your website widget — see [Plans & quotas](https://dev-moncha.com/docs/plans/). Customer messages are not counted. There is no per-message WhatsApp add-on. A number you buy from MonCha is a separate monthly charge for the number itself.

## The 24-hour window

WhatsApp Business rules mean MonCha can reply freely while a customer is actively messaging. If more than 24 hours pass since their last message, they need to write in again before the bot can reply — this is a WhatsApp platform rule, not a MonCha limit.

## If something goes wrong

- **Connect WhatsApp does nothing / “temporarily unavailable”** — WhatsApp connections may be paused on our side. Wait and try again, or contact support.
- **“This bot already has WhatsApp”** — disconnect the current number first, then connect the new one.
- **“That WhatsApp number is already connected to another bot”** — disconnect it from the other bot, or pick a different number. One number cannot sit on two bots.
- **The number shows in WhatsApp Manager but not in MonCha** — adding a number only in Meta’s tools does not attach it to a bot. Run **Connect WhatsApp** from Integrations for that bot.
- **You bought a number but the bot still says Not connected** — Facebook did not finish. On **Your WhatsApp numbers** click **Continue with Facebook**, or on the bot click **Finish connecting**. Do not use **Connect WhatsApp** on another bot for that same purchased number.
- **No reply when you message the number** — confirm Integrations shows **Connected**, **AI replies** is on, and you wrote from a different phone. Check [Conversations](https://dev-moncha.com/docs/analytics/) for the inbound message.

---

# Email Inbox

Give a paid bot your company email. Visitors write support@yourcompany.com; you forward that mailbox to MonCha and add DNS so the bot can reply as you.

Human page: https://dev-moncha.com/docs/inbox/

Email Inbox lets a paid bot read mail sent to **any mailbox you can forward** — `you@gmail.com`, Outlook, Yahoo, or `support@yourcompany.com`. You keep your current mail host. We do not take over your MX records.

The bot uses the same knowledge base, language, and monthly answer quota as your website widget. One message still equals one AI answer.

## Who can use it

- Starter, Growth, Scale, extra bots, and Enterprise — the bot must sit on an **active paid plan**, not the free tier or the 7-day trial.
- The sidebar item is locked until the workspace is paid. Same pattern as other paid features.
- Personal inboxes (Gmail and similar) are allowed. Forward that inbox to us. Replies cannot come from @gmail.com — they send from `inbox@inbox.moncha.co`.
- A company domain you control can add DNS so replies show your address.

## How it works

1. You type your email on **Dashboard → Inbox** — Gmail or company.
2. You forward that mailbox to one MonCha routing address: `inbox@inbox.moncha.co`.
3. Gmail sends its own confirmation. Open it and confirm. We do not send a separate OTP.
4. A visitor writes your address. Your host forwards the mail to us. The bot replies from your company address once DNS is verified, or from `inbox@inbox.moncha.co` for Gmail / unverified domains (Reply-To stays your mailbox).

MonCha receives mail only on `inbox.moncha.co`. Your root domain mail — including anything you already send through Resend or another provider — is unchanged.

## Enable Inbox

1. Subscribe if the workspace is still on trial or free. Open [Billing](https://app.dev-moncha.com/dashboard/billing).
2. Select the bot in the sidebar, then open **Inbox**.
3. Enter the mailbox visitors should write to — `you@gmail.com` or `hello@yourcompany.com`.
4. Click **Enable Inbox**.

That address is unique per bot. Two bots cannot share `support@yourcompany.com`. Disconnect (or delete the bot) to free it so the same bot or another bot can connect it again.

## Forward your mailbox

After enable, the page shows the routing address. Copy it.

**Gmail (personal or Workspace):** Settings → See all settings → Forwarding and POP/IMAP → Add a forwarding address → paste `inbox@inbox.moncha.co`. Confirm the email Google sends to that inbox (it also appears as a note on the Inbox page if we received it). Then turn forwarding on, or use a filter so only this mailbox forwards.

**Microsoft 365:** Exchange admin or Outlook forwarding for that mailbox → forward to `inbox@inbox.moncha.co`. Keep a copy in the mailbox if you still want staff to see the thread.

Do not change your domain's MX to Cloudflare. Forwarding is enough. Changing MX would steal all mail for the domain.

## Add DNS so replies come from you

The Inbox page lists three TXT records and watches them through Cloudflare DNS. Add them at the DNS host for *your company domain* (GoDaddy, Cloudflare, Route 53, etc.).

| Record | Type | Host | What to do |
| --- | --- | --- | --- |
| SPF | TXT | @ | Merge `include:_spf.mx.cloudflare.net` into your existing SPF. Do not add a second SPF record. |
| DKIM | TXT | cf2024-1._domainkey | Add the DKIM TXT shown for this domain. We watch `cf2024-1._domainkey.yourdomain.com`. |
| DMARC | TXT | _dmarc | Keep the DMARC you already have. We only check that `_dmarc` exists. A typical starter value is `v=DMARC1; p=none;`. |

Click **Check DNS** after the records propagate (often a few minutes, sometimes up to 48 hours). When SPF and DKIM are found, the page marks the domain verified and replies can send as your company address.

## What the bot can and cannot do

- Reads the plain-text body and replies in the same thread.
- Uses your knowledge base. Unanswered questions follow the same fallback as the widget.
- **Attachments:** filenames are noted so the bot knows a file was sent. The bot cannot open PDFs, images, or other files, and it cannot attach files to its reply. Ask the visitor to paste the relevant text or put the file in the knowledge base.
- Auto-replies, bounce mail, and mailing-list noise are dropped.
- Each inbox is rate-limited so a flood cannot burn your quota.

## Disconnect

Click **Disconnect** on the Inbox page. A confirmation asks you to confirm first. After you confirm, that bot stops receiving and sending on the address immediately. The mailbox itself stays yours — this bot or another bot can connect the same email again.

We cannot turn off Gmail or Outlook forwarding for you. If you forwarded the mailbox to `inbox@inbox.moncha.co`, turn that forwarding off after disconnect. Otherwise mail still leaves your inbox and we drop it (unknown recipient) — the bot will not reply.

Deleting the bot also disconnects and frees the address.

## Plans

Included on every paid plan. Not available on trial or the free tier. See [Plans & quotas](https://dev-moncha.com/docs/plans/).

---

# Leads

Turn conversations into contacts — and know when a person needs to step in.

Human page: https://dev-moncha.com/docs/leads/

## Smart lead capture

MonCha doesn't rely on an upfront form. A background classifier reads each conversation against *your own* definition of a lead and scores it 0–100 — so a visitor asking about pricing for a 20-seat team this quarter is captured as a hot lead even before they share an email. Configure it in **Bot settings → Smart lead generation**:

- **Lead goal** — describe, in plain words, what counts as a lead for your business. The scorer uses this, not a generic rule.
- **Capture mode** — *Passive* (score & notify silently), *Conversational* (the bot also asks once, naturally, for a name and email so the team can follow up), or *Off*.
- **Notify threshold** — only alert you when a lead scores at or above this (defaults to the “hot” band).

Every scored lead appears on the **Leads** page with its score, band, an AI one-line summary, sentiment, visitor country/region (from the request geo), and any qualification details (budget, timeline, team size) the visitor revealed — whether or not they ever gave contact info.

## Signed-in visitors (identify)

If your site has logged-in users, call `MonCha.identify({ userId, email, name })` after login (see the [install guide](https://dev-moncha.com/docs/install/)). Their leads are then pre-filled with their real name and email instead of relying on the AI to extract them, and carry an `external_user_id` so you can tie the lead back to the same person in your own system. A “Signed in” badge marks these on the Leads page.

## Talking to a person

Escalating to a human is its own feature now — customers open a ticket from the widget's **Support** tab and chat with your team in real time, rather than a one-off email. See [Tickets & human support](https://dev-moncha.com/docs/tickets/).

## Where notifications go

Set **Bot settings → Send leads & handoff requests to**. It defaults to your login email. Each bot can notify a different address — useful when sales and support are different people.

## Wiring leads into your CRM

Email is fine to start, but on the Scale plan you can subscribe to the `lead.created` and `conversation.handoff` [webhooks](https://dev-moncha.com/docs/webhooks/) and push contacts straight into your CRM the moment they arrive. You can also pull leads on demand — `GET /v1/leads` through the [REST API](https://dev-moncha.com/docs/api/) (scope `leads:read`), or the `list_leads` tool over [MCP](https://dev-moncha.com/docs/api/). Both include the score, summary, qualification, and `external_user_id`.

## Privacy

Contact details belong to you. If a visitor asks to be removed, delete the lead from your dashboard. MonCha never uses your customers' data to train models.

---

# Human support (tickets)

A dedicated Support tab in the widget, so customers can open a ticket and chat live with your team — no email round-trips.

Human page: https://dev-moncha.com/docs/tickets/

## The Support tab

The widget has two tabs: **Chat** (the AI) and **Support** (tickets with your team). A customer opens Support, taps *New conversation*, writes a subject and message, and gets a threaded ticket they can leave and come back to — replies show up live, with a badge on the tab when there's something new.

Starting a ticket from an active AI chat carries the conversation along as context, so your team isn't starting cold.

## Attachments & screenshots

Customers can attach an image or short video to any message — including an annotated screenshot captured right from the page they're on (draw an arrow, circle the button that's broken). Images up to 5 MB, video up to 25 MB.

## Replying from the dashboard

Go to **Tickets** to see every open thread across your bots, reply, and change status: **Open → In progress → Resolved** (or **Closed**). The customer sees your reply appear live in their widget — no refresh, no email needed on either side.

## Contacts

The **Contacts** page lists everyone who has messaged your widget — guests and identified users — with their ticket history in one place. A “Verified” badge marks contacts whose identity your site vouched for via `MonCha.identify()` (see [Install](https://dev-moncha.com/docs/install/)); their tickets follow them across devices instead of staying tied to one browser.

## Notifications

New tickets email **Bot settings → Send leads & handoff requests to** (defaults to your login email; each bot can route to a different inbox). Subscribe to the `ticket.created` [webhook](https://dev-moncha.com/docs/webhooks/) to push new tickets into Slack, a CRM, or your own helpdesk.

## Per-bot

Tickets are scoped to the bot they were opened against, same as conversations and leads — switch bots in the sidebar to see a different bot's queue.

---

# Bookings

Let website visitors request an appointment from the widget. You approve, reject, reschedule, or cancel each request — clinics, gyms, salons, turf bookings, and hourly hire.

Human page: https://dev-moncha.com/docs/bookings/

## What it is

Booking is off until you turn it on. When it's on, the widget shows a calendar button (default label **Book Now**). A visitor picks a date and time, leaves their name, email, and phone, and the request lands as **pending**. Nothing is confirmed until you (or a teammate with permission) approve it.

Use this when people already ask your site to book something — you do not need a separate booking product for simple appointment requests.

## Example: clinic, salon, or gym appointment

A dental clinic, hair salon, or gym personal-training session usually has a list of start times.

1. Open **Bookings** (or **Widget**) and turn **Enable booking** on.
2. Open **Calendar settings** and choose **Fixed slots**.
3. Set hours (for example first slot 9:00 AM, last slot ends 6:00 PM) and slot length (15, 30, or 60 minutes — or a custom length).
4. Optional: require a note, add extra fields (e.g. “Preferred trainer”), and paste a Google Maps link for your studio.
5. Save. On your website, a visitor taps Book Now, picks *Saturday 15 August, 3:00 PM*, enters contact details, and submits.

You get an email with Approve / Reject. After you approve, the visitor gets a confirmation with that time in **their** timezone (India shows IST, 3:00 PM — not UTC) and, if you added it, an Open in Google Maps button.

## Example: turf, gaming centre, or hourly hire

A football turf or PC café often lets the visitor choose any start time inside opening hours, rather than a fixed grid.

1. Enable booking the same way.
2. In Calendar settings choose **Visitor picks time**.
3. Set opening / closing hours and how long each booking lasts (for example 60 minutes, or a custom 90 minutes).
4. Save. The visitor picks a date, then a start time; each booking still uses the slot length you set.

## Turning it on and saving

Enable booking from the **Bookings** page toggle or from [Widget](https://dev-moncha.com/docs/customize/) → Icon & position. Calendar settings start collapsed; expand them to edit. Unsaved changes use Discard / Save, same as the widget customizer. Turning the toggle off hides the calendar in the widget immediately if it was already saved on.

## What the visitor sees

- Calendar button in the widget header, and a **Book Now** chip when they ask the bot about booking or appointments.
- Step 1: date and time. Confirmed times are crossed out so nobody else can take them.
- Step 2: name, email, phone (country flag and calling code, defaulted from their location; they can search and change it), optional notes and extra fields.
- After submit: the request is pending. They are emailed when you approve, reject, reschedule, or cancel.

## Approving and rejecting

Open **Bookings** in the dashboard, or use Approve / Reject in the request email (you'll be asked to sign in if needed). Owners and teammates with content permission can decide; others can view only.

If that time was already confirmed for someone else, approve is blocked. If the same visitor tries to book the *same* pending slot again, the widget tells them it's already waiting for your team and to pick a different time. Other visitors can still request a pending slot until you confirm it.

## Rescheduling and cancelling

Pending and confirmed appointments can be moved or cancelled from **Bookings** (owners and teammates with content permission). Pick a new date and time and save — the visitor gets an email that the appointment was rescheduled, with the previous time and the new time in their timezone. Cancel asks for confirmation first; after you confirm, the visitor is emailed that the appointment was cancelled. You can add an optional note on the cancel email.

Rescheduling a confirmed booking is blocked if another confirmed booking already occupies that time. Rejected and cancelled bookings cannot be changed again.

## Emails and maps

New requests go to **Bot settings → Send leads & handoff requests to** (or your login email). Visitor emails (confirmed, rescheduled, cancelled, rejected) use 12-hour time (5:00 PM) in the visitor's country timezone. Add a Google Maps URL in calendar settings to include a maps button on confirmation and reschedule emails — Gmail does not show an interactive map, so the link is what visitors tap.

## Webhooks

On the Scale plan, subscribe to `booking.created` to push new requests into Slack, a CRM, or your own calendar. See [Webhooks](https://dev-moncha.com/docs/webhooks/).

## API & MCP

Growth+ tokens can fetch and decide bookings the same way the dashboard does. Create a token on **Dashboard → API & Agents** with `bookings:read` and `bookings:write` (included in the Standard preset).

- `GET /v1/bookings?status=pending` — list requests.
- `GET /v1/bookings/{id}` — one request.
- `PATCH /v1/bookings/{id}` with `{ "action": "confirm" }` or `{ "action": "reject", "rejectionComment": "…" }` — emails the visitor, same as Approve / Reject in the dashboard.
- `PATCH /v1/bookings/{id}` with `{ "action": "reschedule", "requestedSlot": "2026-08-20T15:00:00+05:30" }` — moves a pending or confirmed booking and emails the visitor the new time.
- `PATCH /v1/bookings/{id}` with `{ "action": "cancel", "cancelComment": "…" }` — cancels a pending or confirmed booking and emails the visitor.

MCP tools for agents: `list_bookings`, `get_booking`, `update_booking`. Full reference: [API & MCP](https://dev-moncha.com/docs/api/).

---

# Conversations & analytics

Your customers are telling you what your website is missing. This is where you read it.

Human page: https://dev-moncha.com/docs/analytics/

## Conversations

Every chat and voice session, searchable by keyword and filterable by date. Open one to read the full transcript, including which sources the bot cited and any thumbs-up/down feedback the customer left.

Export everything to CSV for your own analysis, or pull it through the [API](https://dev-moncha.com/docs/api/).

## Analytics

- **Messages per day** over the last 30 days.
- **Top questions** — what customers actually ask, ranked.
- **Unanswered rate** — how often your bot had nothing relevant to say.
- **Feedback** — thumbs up vs. down.
- **Sessions** — total conversations and average length.

## The unanswered rate is the number that matters

A high unanswered rate isn't a bot problem — it's a content gap. Every unanswered question is something a real customer wanted to know and your website didn't say. Read them, then either add the content to your site (and resync) or add a [Custom Response](https://dev-moncha.com/docs/knowledge-base/).

Want them pushed to you in real time? Subscribe to the `message.unanswered` [webhook](https://dev-moncha.com/docs/webhooks/).

## Per-bot scoping

Conversations and analytics always reflect the bot selected in the sidebar. Switch bots to compare how each one is performing.

## Message counting

One message = one AI answer. Your customers' questions, greetings, and the welcome message are free. Messages sent through the API and the Playground count the same as widget messages.

---

# Functions

Let the bot do things, not just say things. It calls your API mid-conversation and answers with live data.

Human page: https://dev-moncha.com/docs/functions/

Available on the Scale plan and higher.

## What a function is

A function is one of your HTTP endpoints, described in plain language. When a customer asks something that needs live data — “where's my order ORD-12345?” — the bot decides to call it, extracts the parameters from the conversation, hits your API, and answers with what it gets back.

## Setting one up

Go to **API & Agents → Functions** and provide:

- **Name** — `get_order_status`. Lowercase, underscores.
- **When should the bot use it?** — the description the model reads to decide. Be specific; this is the most important field.
- **Method & URL** — `GET` sends parameters as a query string, `POST` as a JSON body. HTTPS only.
- **Parameters** — one per line, `name: what it means`.

```
Name:        get_order_status
Description: Look up the current shipping status and expected delivery
             date of a customer's order using their order number
Method:      GET
URL:         https://api.yourshop.com/orders/status
Parameters:  order_id: the customer's order number, e.g. ORD-12345
```

## What your endpoint receives

For the example above, the bot calls:

```
GET https://api.yourshop.com/orders/status?order_id=ORD-12345
```

Return JSON. The bot reads it and phrases the answer for the customer, in their language:

```
{"order_id":"ORD-12345","status":"shipped",
 "courier":"BlueDart","expected_delivery":"July 13, 2026"}

→ "Your order ORD-12345 has shipped with BlueDart and should
   arrive by July 13, 2026."
```

## Writing good descriptions

The model only calls a function when the description convinces it this is the right tool. Vague descriptions cause missed calls and wrong calls.

- *“Check whether a specific product size is currently in stock at a given store branch”*
- *“Product API”*

## Security

- Endpoints must be **HTTPS** and publicly reachable. Private and internal addresses are rejected.
- Pass auth with custom headers — they're stored with the function and never exposed to the visitor.
- Responses are truncated to 4,000 characters and time out after 10 seconds.
- The bot never shows the customer your raw response or your endpoint.
- Treat every parameter as untrusted input. Authorize on your side.

## Limits

Up to 10 functions per account. If the bot gets confused it stops after three tool rounds and tells the customer it couldn't complete the lookup, rather than looping.

## Related

Functions let the bot *pull* from your systems. To *push* events out to your systems, see [Webhooks](https://dev-moncha.com/docs/webhooks/).

---

# Webhooks

MonCha POSTs signed events to your systems the moment they happen.

Human page: https://dev-moncha.com/docs/webhooks/

Available on the Scale plan and higher.

## Events

- `lead.created` — a visitor was scored as a lead (see the payload below).
- `conversation.handoff` — legacy handoff signal, kept for existing integrations.
- `message.unanswered` — the bot had no relevant content for a question.
- `ticket.created` — a customer opened a support ticket from the widget's [Support tab](https://dev-moncha.com/docs/tickets/).
- `booking.created` — a visitor submitted an appointment request from the widget (see [Bookings](https://dev-moncha.com/docs/bookings/)).

## Adding one

Go to **API & Agents → Webhooks**, enter an HTTPS endpoint, tick the events you want, and save. You'll get a signing secret (`whsec_…`). The last delivery status is shown next to each webhook so you can spot a broken endpoint.

## What you receive

```
POST https://yourapp.com/hooks/MonCha
X-MonCha-Event: lead.created
X-MonCha-Timestamp: 1783691750
X-MonCha-Signature: 69b291806d1023a89d4e414e…
Content-Type: application/json

{
  "event": "lead.created",
  "timestamp": 1783691750,
  "data": {
    "lead_id": "010e19a1-…",
    "session_id": "…",
    "chatbot_id": "9166406d-…",
    "score": 85,
    "band": "hot",
    "category": "pricing",
    "summary": "40-person team evaluating enterprise pricing for Q1",
    "sentiment": "positive",
    "name": "Priya Sharma",
    "email": "priya@example.com",
    "phone": null,
    "country": "SG",
    "region": "Singapore",
    "external_user_id": "usr_8f21",
    "qualification": { "team_size": "40", "timeline": "Q1" },
    "captured_via": "inferred"
  }
}
```

## Verifying the signature

Always verify before trusting a payload. The signature is the hex HMAC-SHA256 of ``${timestamp}.${rawBody}``, keyed with your signing secret:

```
import crypto from 'crypto'

function verify(rawBody, headers, secret) {
  const ts  = headers['x-MonCha-timestamp']
  const sig = headers['x-MonCha-signature']
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(sig)
  )
}
```

Use the *raw* request body, not a re-serialized object — key order matters. Reject timestamps more than a few minutes old to prevent replay.

## Delivery behavior

- Delivered as a fire-and-forget POST; a slow endpoint never slows your customer's chat.
- 10-second timeout. Respond `2xx` quickly and do your work asynchronously.
- No automatic retries today — reconcile through the [API](https://dev-moncha.com/docs/api/) if you need guarantees.

## Scoping

A webhook can listen to all bots or one specific bot. Add several webhooks if different systems care about different events.

## Related

Webhooks *push* events out. To let the bot *pull* live data during a conversation, see [Functions](https://dev-moncha.com/docs/functions/).

---

# API & MCP reference

Everything the dashboard does, as a REST API — plus a hosted MCP server so AI agents like Claude can manage your bots directly. Available on the Growth plan and higher.

Human page: https://dev-moncha.com/docs/api/

## Authentication

Create a token in **Dashboard → API**. Tokens are scoped, can be limited to specific bots, and can expire. Pass them as a bearer header:

```
curl https://api.dev-moncha.com/v1/bots \
  -H "Authorization: Bearer mgpt_your_token_here"
```

## Endpoints

| Method | Path | Scope | Description |
| --- | --- | --- | --- |
| GET | /v1/bots | bots:read | List bots |
| POST | /v1/bots | bots:write | Create a bot (plan-limited) |
| GET | /v1/kb?chatbotId=… | kb:read | List knowledge-base documents |
| POST | /v1/kb/ingest | kb:write | Add knowledge from a URL or raw text (queued) |
| POST | /v1/chat | chat:invoke | Chat with a bot — SSE streaming, counts toward quota |
| GET | /v1/conversations | conversations:read | List conversations (?q= search) |
| GET | /v1/conversations/{sessionId} | conversations:read | Full transcript of one session |
| GET | /v1/leads | leads:read | List intent-scored leads (?chatbotId= filter) |
| GET | /v1/analytics | analytics:read | 30-day analytics summary |
| GET | /v1/bookings | bookings:read | List appointment requests (?status= pending\|confirmed\|rejected\|cancelled) |
| GET | /v1/bookings/{id} | bookings:read | One booking — visitor, slot, status |
| PATCH | /v1/bookings/{id} | bookings:write | Confirm, reject, reschedule, or cancel — emails the visitor |
| GET | /v1/openapi.json | — | This API as an OpenAPI 3.1 spec (no auth) |

Full schemas: [openapi.json](https://api.dev-moncha.com/v1/openapi.json)

## Chat (streaming)

`POST /v1/chat` returns Server-Sent Events with OpenAI-style chunks. Pass a stable `sessionId` to group turns into one conversation.

```
curl https://api.dev-moncha.com/v1/chat \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is your refund policy?","chatbotId":"…","sessionId":"user-42","language":"ja-JP"}'
```

## Bookings

List appointment requests and confirm, reject, reschedule, or cancel them. Confirming emails the visitor and blocks that slot. Reschedule needs `requestedSlot` (ISO-8601 with offset) and emails the new time. Cancel emails the visitor. Same behaviour as the Bookings page. Scopes: `bookings:read` / `bookings:write`.

```
curl https://api.dev-moncha.com/v1/bookings?status=pending \
  -H "Authorization: Bearer mgpt_…"

curl https://api.dev-moncha.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"confirm"}'

curl https://api.dev-moncha.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"reschedule","requestedSlot":"2026-08-20T15:00:00+05:30"}'

curl https://api.dev-moncha.com/v1/bookings/BOOKING_ID \
  -X PATCH \
  -H "Authorization: Bearer mgpt_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"cancel","cancelComment":"We need to close that day."}'
```

## MCP server (for AI agents)

MonCha hosts a remote MCP server, so Claude and other MCP-capable agents can list bots, add knowledge, ask questions, read conversations, leads & analytics, and **list / confirm / reject / reschedule / cancel bookings** — using the same scoped tokens. Tools: `list_bots`, `list_knowledge`, `add_knowledge`, `ask_bot`, `list_conversations`, `get_conversation`, `list_leads`, `get_analytics`, `list_bookings`, `get_booking`, `update_booking`.

```
{
  "mcpServers": {
    "MonCha": {
      "url": "https://api.dev-moncha.com/mcp",
      "headers": { "Authorization": "Bearer mgpt_…" }
    }
  }
}
```

## Get an API key in 2 minutes

Start the free trial, open Dashboard → API & Agents, create a token.

[Start free trial](https://app.dev-moncha.com/signup)

---

# Plans & quotas

What each plan includes, how extra bots and add-ons work, and how usage is counted.

Human page: https://dev-moncha.com/docs/plans/

|   | Starter | Growth | Scale |
| --- | --- | --- | --- |
| Chatbots | 1 | 2 | 3 |
| AI answers / month | 2,500 | 6,000 | 25,000 |
| Pages | 5,000 | 25,000 | 100,000 |
| Voice minutes / month | 60 | 180 | 600 |
| Team members | 1 | 4 | 10 |
| Auto-sync | Manual only | Monthly | Weekly |
| Remove branding | Add-on | Add-on | Add-on |
| API & MCP access | — | Yes | Yes |
| Webhooks | — | — | Yes |
| Functions | — | — | Yes |
| Email Inbox | Yes | Yes | Yes |
| Buy Extra bots | Starter only | Starter + Growth | All three |

Need more bots, messages, or voice? Buy add-ons on the [pricing page](https://dev-moncha.com/pricing/). Enterprise is invite-only — [talk to us](mailto:support@moncha.co?subject=Enterprise%20plan) if you need a custom contract.

## Buy Extra bots

Each plan includes 1–3 chatbots. Buy extra bot slots on Billing with the Buy Extra bots toggle.

- **Match the plan (default).** Extra bots are a line on your current plan subscription — same monthly or annual cycle, same invoice.
- **Annual plan, one month only.** Turn on Buy Extra bots and switch to Monthly. That slot is a **separate monthly subscription** (like Extra 5k), not on the yearly invoice. Remove slot after that month — this month stays billed; it does not renew with your annual plan.
- **Who can buy what.** Starter can buy Extra bot · Starter. Growth can buy Starter and Growth extra bots. Scale can buy all three.
- **Isolated quota.** Each extra bot gets the same answers, pages, and voice minutes as that SKU's plan, used only by that bot. A Growth extra bot has 6,000 answers / 25,000 pages / 180 voice minutes of its own — not taken from, and not added to, the plan pool.
- **Plan bots first.** New bots fill plan-included slots first. Extra slots are used only when those are full. Extra bots show an Add-on pill in the dashboard.
- **Delete ≠ cancel.** Deleting a bot does not cancel a paid extra slot. Use **Remove slot** on Billing to stop paying.
- **Remove slot.** This billing period stays charged (no refund for days already used). The slot drops from the next invoice. The extra bot keeps working until that period ends. If a plan-included slot is free, it moves onto that slot; otherwise visitors see Please subscribe to access that bot — same as when a plan is canceled.
- **Mid-cycle buy.** On the plan invoice, you are charged for the remaining days of this period now. A monthly extra bot on an annual plan is billed from Checkout as its own monthly subscription.

## Extra messages and voice

These are **separate monthly subscriptions** (not on the plan invoice). They stack, and they apply only to **plan bots** — never to extra bots.

- **Extra 5,000 messages** — adds 5,000 AI answers to the plan pool. Buy another pack to stack.
- **Extra voice minutes** — pick 60, 180, or 600 on Billing. Adds those minutes to the plan voice pool. Packs stack. Extra bots keep their own isolated voice quota.
- **Remove MonCha branding** — hides the watermark on the widget. One per account; cancel from the Stripe billing portal.

Prices and currencies are on the [pricing page](https://dev-moncha.com/pricing/). Manage or cancel message, voice, and branding add-ons from the Stripe portal on Billing.

## WhatsApp numbers

Connecting WhatsApp is included on every plan. **Buying a number** from MonCha is a separate monthly subscription, charged in your billing currency. Price depends on the country and today's mid-market conversion from US dollars — see [WhatsApp](https://dev-moncha.com/docs/whatsapp/). Disconnecting a bot does not cancel that charge. Stop billing from Integrations — the number keeps working until the paid month ends, then we remove it. You can also remove it sooner.

## Email Inbox

Paid workspaces can give a bot a company mailbox. Visitors write your address; you forward that mailbox and add DNS. Trial and the free tier stay locked. See [Email Inbox](https://dev-moncha.com/docs/inbox/).

## How messages are counted

**One message = one AI answer.** Your customers' questions are never counted. Greetings, the welcome message, and quick prompts are free. Messages sent through the API, MCP, and the Playground count the same as widget messages.

Most competitors count both sides of the exchange, so a “2,200 message” plan is really about 1,100 conversations. Ours isn't.

Plan bots share the plan's monthly answer pool (plus any Extra 5,000 packs). Each extra bot has its own answer quota and does not draw from that pool.

## How pages are counted

One page = 2,500 characters of cleaned text. Re-syncing a document doesn't double-count it — only the difference applies. Deleting a document returns its pages to your quota.

Plan bots share the plan page cap. Each extra bot has its own page cap matching that SKU (Starter 5,000, Growth 25,000, Scale 100,000).

## Voice minutes

Metered separately from messages, counted while a voice session is open. Extra voice packs (60, 180, or 600 minutes) stack on the plan pool (plan bots only). Extra bots use only their own voice minutes.

## When quotas reset

Messages and voice minutes reset on your **Stripe billing date** — the same day you are charged — not the 1st of the calendar month. They do not roll over. Extra-bot isolated quotas reset on that same date. Pages, chatbots, and team seats are account totals, not monthly.

## Trial and downgrades

Every new account gets 7 days of Growth, free, no card. When the trial ends you move to the free tier — your bot, knowledge base, and conversations stay intact. Add-ons require an active paid plan. Message, voice, and branding add-ons are billed separately and switch off if cancelled. Extra bots on the plan invoice stay until you remove the slot. A monthly extra bot on an annual plan is a separate subscription — stop it with Remove slot.

## Rate limits

Requests per minute scale with your plan and apply per bot for the widget and per token for the [API](https://dev-moncha.com/docs/api/). A `429` response includes a `Retry-After` header.

---

# Enterprise

A private contract with per-bot plan tiers, custom pricing, and branding removal included free.

Human page: https://dev-moncha.com/docs/enterprise/

Enterprise is an invite-only, custom-priced contract. Each bot gets its own isolated quota from a catalog-equivalent plan tier — Starter, Growth, or Scale. Remove MonCha Branding is included free on every enterprise bot.

## How bot slots work

Your admin allocates a number of Starter, Growth, and Scale bot slots when they create your contract. When you create a bot you choose which tier it sits on. That tier determines the bot's monthly limits — each bot is completely isolated:

| Tier | Messages / mo | Voice min / mo | Knowledge pages |
| --- | --- | --- | --- |
| Starter | 2,500 | 60 | 5,000 |
| Growth | 6,000 | 180 | 25,000 |
| Scale | 25,000 | 600 | 100,000 |

Quotas do not pool across bots. A Growth bot and a Scale bot each have their own separate counters.

## Creating a bot

Go to **Bots → Create bot**. You'll be asked to pick a plan tier. The dialog shows how many slots of each tier are still available. Once you confirm, the bot is created with its quota locked to that tier.

## Changing a bot's plan tier

Go to **Billing** with the bot selected in the sidebar. You'll see the bot's current tier and a **Change bot plan** button. Select a new tier — any usage you've already consumed this month carries over (e.g. if you used 1,000 messages on Growth and switch to Scale, you start Scale with 24,000 remaining). A free slot of the new tier must be available.

## Remove MonCha Branding

Remove MonCha Branding is automatically included on every bot in your enterprise workspace at no extra charge. You don't need to buy it as an add-on.

## Add-ons

Extra messages and voice minute packs are available on Billing and apply workspace-wide. Extra bot slots are not purchasable in enterprise — your admin adjusts slot allocation via the contract.

## Paying your contract

After signing in with your enterprise email, go to **Billing**. Your contract amount is shown — click **Pay now** to go through Stripe checkout. Once paid, the sidebar unlocks within 10 seconds. If the sidebar is still locked after payment, refresh the Billing page manually.

## Workspace switching

Your enterprise workspace shows as **Enterprise** in the workspace switcher. If you have a personal workspace, you can switch between them normally.

## Contact

Enterprise is invite-only. If you're interested in a contract, [talk to us](mailto:support@moncha.co?subject=Enterprise%20plan).

---

# Legal

- Privacy: https://dev-moncha.com/privacy/
- Terms: https://dev-moncha.com/terms/
- Refunds: https://dev-moncha.com/refunds/