# Ask Medwiki — Partner Widget Integration Guide

Add an AI-powered health Q&A chat to your website with a single line of code.

---

## Before you start

Before you can embed the widget, the Medwiki team will give you:

1. **Your Partner ID** — a short identifier like `medwiki-uk` or `partner-abc`
2. **Confirmation that your site's origin is whitelisted** — the widget will only load on domains that the Medwiki team has registered for your Partner ID

Send the Medwiki team the **exact origins** of the sites where you'll embed the widget, for example:

```
https://www.example.com
https://staging.example.com
http://localhost:3000   (if you need to test locally)
```

An "origin" is the scheme + host + port with **no trailing slash and no path**. Subdomains are separate origins — `www.example.com` and `app.example.com` must each be whitelisted.

---

## Step 1 — Add the embed script

Paste this **one line** into your HTML, ideally right before the closing `</body>` tag:

```html
<script
  src="https://medwiki-bot-1013642442699.us-central1.run.app/widget/embed.js"
  data-partner="YOUR_PARTNER_ID"
  async
></script>
```

Replace `YOUR_PARTNER_ID` with the ID you received from Medwiki (e.g. `data-partner="medwiki-uk"`).

That's it. Reload the page — you should see a chat bubble appear in the bottom-right corner. Click it to open the chat.

---

## Step 2 — (Optional) Customise the placement

The widget supports two display modes:

### Floating (default)

A circular chat bubble in the bottom-right of every page. No configuration needed — this is what you get from Step 1.

### Inline

Embed the chat directly into a container on your page (for dedicated "Ask a question" pages).

```html
<!-- 1. Create a container with the size you want -->
<div id="ask-medwiki-chat" style="width: 100%; max-width: 420px; height: 600px;"></div>

<!-- 2. Load the widget in inline mode, pointing at the container -->
<script
  src="https://medwiki-bot-1013642442699.us-central1.run.app/widget/embed.js"
  data-partner="YOUR_PARTNER_ID"
  data-mode="inline"
  data-target="#ask-medwiki-chat"
  async
></script>
```

---

## Script attributes reference

| Attribute | Required | Default | Description |
|---|---|---|---|
| `src` | yes | — | Must be `https://medwiki-bot-1013642442699.us-central1.run.app/widget/embed.js` |
| `data-partner` | **yes** | — | Your Partner ID. Supplied by Medwiki. |
| `data-mode` | no | `floating` | Either `floating` (bubble) or `inline` (embedded in container) |
| `data-target` | only if `data-mode="inline"` | — | CSS selector of the container the widget should fill |
| `data-color` | no | `#7b2ff7` | Background color of the floating bubble (floating mode only). Accepts any CSS color. |
| `async` | recommended | — | Standard HTML attribute — lets the script load without blocking the page |

---

## What the partner controls vs. what Medwiki controls

Your **branding** (theme color, logo, welcome message, supported language, which helper buttons appear, daily/monthly message limits) is configured **centrally** in the Medwiki admin panel against your Partner ID. You do not need to configure any of this in your HTML.

To update any branding or limits, contact the Medwiki team — changes take effect immediately without any code change on your side.

Your HTML tag only needs to include `data-partner`. Everything else is dynamic.

---

## Responsive behaviour

- **Desktop**: floating mode renders a 380×600 px chat window anchored to the bottom-right corner
- **Mobile (< 600 px wide)**: floating mode opens full-screen over the page
- **Inline mode**: fills 100% of whatever container you provide — you control the size

The bubble has `z-index: 2147483646`, which should stay above virtually any content on your page. If you see layering conflicts, let Medwiki know.

---

## Privacy, session persistence, and analytics

- Each visitor's chat session is stored in **their browser's `localStorage`**, keyed by your Partner ID. No cookies are set on your domain.
- If a visitor refreshes the page, their conversation continues seamlessly.
- The **Reset** button inside the chat clears that visitor's session.
- Medwiki tracks per-partner message volume and OpenAI costs centrally. You do not need to add any analytics tags.
- No visitor PII is sent to the widget unless the visitor types it into the chat themselves.

---

## Security & access control

- The widget is protected by an **origin allowlist**. If a site not registered for your Partner ID loads the embed script, the API will reject all requests with HTTP 403.
- If your Partner ID is disabled, the widget will refuse to load (you'll see a small error message in the chat pane instead of the chat UI).
- Daily and monthly message quotas are enforced per Partner ID. Once a quota is reached, visitors see a friendly "please try again later" message until the next day / month rolls over. Contact Medwiki if you need higher limits.

---

## Testing checklist

After adding the script to your site, verify each of these:

- [ ] Chat bubble appears in the bottom-right (floating mode) **or** the inline container renders the chat (inline mode)
- [ ] Clicking the bubble opens a chat window with your branded theme color and welcome message
- [ ] Typing a health question and hitting send returns an answer within ~10 seconds
- [ ] Helper buttons (e.g. "Check a symptom", "About a medicine") appear above the input box
- [ ] Refreshing the page preserves the current conversation
- [ ] Clicking **Reset** starts a fresh conversation
- [ ] On a mobile device, the widget opens full-screen when tapped

If any check fails, see the **Troubleshooting** section below.

---

## Troubleshooting

### Nothing happens — no bubble, no error
1. Open your browser's devtools console (F12). Look for any line starting with `[ask-medwiki]`.
2. If you see `data-partner attribute is required`, your `<script>` tag is missing the `data-partner="…"` attribute.
3. If you see no errors at all, confirm the script tag is actually present in the rendered HTML (some CMS platforms strip `<script>` tags).

### Bubble shows, but clicking it shows an error instead of the chat
- Your origin is probably not in the allowlist for your Partner ID. Open devtools → Network tab → look for a request to `/api/ask-medwiki/public/config` — if it returns `403`, send your exact origin to Medwiki to get it added.
- If the request returns `404`, your Partner ID is wrong or has been deleted.

### Chat opens but sending a message fails
- Open devtools → Network tab → look for a request to `/api/ask-medwiki/public/turn`.
  - **403**: origin issue (see above)
  - **404**: your session expired — click **Reset** in the chat
  - **429**: you've hit your daily or monthly quota. Contact Medwiki.
  - **500**: internal error. Contact Medwiki with the timestamp.

### Wrong language in responses
The widget's language is set centrally per Partner ID. Contact Medwiki to change your locale (we support English, Hindi, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Arabic, Urdu, Bengali, Tamil, Telugu, Marathi, Gujarati, Kannada, Malayalam, Punjabi).

### CSS of my page is conflicting with the widget
The widget runs inside an **iframe**, so your CSS cannot affect the chat UI and the chat's CSS cannot affect your page. If you see layout issues on the wrapping button/iframe container, let Medwiki know — those are the only elements injected directly into your page's DOM.

### Bubble is hidden behind another element
The widget bubble uses `z-index: 2147483646`, which is the maximum safe integer minus one. If another element on your page is higher than that, reduce its z-index — it's almost certainly unintentional.

---

## Removing the widget

To disable the widget on a given page, remove the `<script>` tag. To disable it across your entire account, contact Medwiki — they'll disable your Partner ID, and the widget will stop loading on every site that uses it without you needing to touch your HTML.

---

## Need help?

Contact the Medwiki team with:
- Your Partner ID
- The exact origin (URL) of the site where you're embedding
- A screenshot of any error in the browser's devtools console or Network tab
- A description of what you expected vs. what you're seeing

We'll get back to you shortly.