# SamCaller — Call Me Now widget & API

Let visitors on your website or app request an instant call. SAM calls them in seconds using your module (your knowledge, language and pitch), and the minutes bill to your account.

## 1. Get your widget key

In your SamCaller dashboard, open a call module, turn on "Call Me Now" widget, and optionally add allowed website domains. A key like `cmn_xxxxxxxx` is generated. Each module has its own key, so you can run a separate widget for sales/general and for support.

## 2a. Drop-in button (websites, no coding)

Paste this one line before `</body>` on any page — it adds a floating "Call me now" button:

```html
<script src="https://samcaller.com/widget.js?key=cmn_YOUR_KEY" async></script>
```

Optional attributes: `data-label`, `data-title`, `data-color`, `data-position="left|right"`.

## 2b. REST API (your own form, or server-to-server)

```
POST https://samcaller.com/api/widget/call-me-now
Content-Type: application/json

{ "key": "cmn_YOUR_KEY", "phone": "+9198XXXXXXXX", "name": "optional", "context": "optional note" }
```

```bash
curl -X POST https://samcaller.com/api/widget/call-me-now \
  -H "Content-Type: application/json" \
  -d '{"key":"cmn_YOUR_KEY","phone":"+919800000000"}'
```

Response: `{ "ok": true, "message": "Calling you now." }` — SAM calls the number within seconds.

## From a mobile app (Android / iOS)

The drop-in script is for websites. In a native app, call the same REST endpoint when the user taps your own "Call me" button. Turn on "Allow calls from mobile apps" for the module first — apps do not send a website domain, so the domain allowlist would otherwise block them.

iOS (Swift):

```swift
var r = URLRequest(url: URL(string: "https://samcaller.com/api/widget/call-me-now")!)
r.httpMethod = "POST"; r.setValue("application/json", forHTTPHeaderField: "Content-Type")
r.httpBody = try! JSONSerialization.data(withJSONObject:
  ["key": "cmn_YOUR_KEY", "phone": phone, "name": name])
URLSession.shared.dataTask(with: r).resume()
```

Android (Kotlin, OkHttp):

```kotlin
val json = "{\"key\":\"cmn_YOUR_KEY\",\"phone\":\"$phone\",\"name\":\"$name\"}"
OkHttpClient().newCall(Request.Builder().url("https://samcaller.com/api/widget/call-me-now")
  .post(json.toRequestBody("application/json".toMediaType())).build()).execute()
```

Tip: a key shipped inside an app can be extracted. For best security, have the app backend make this call (server-to-server) so the key stays private.

## Parameters

| Field | Required | Notes |
|-------|----------|-------|
| key | yes | The widget key for the module (`cmn_...`) |
| phone | yes | Visitor number. India numbers auto-get +91; international need full +country code. |
| name | no | Visitor name (shows in your results) |
| context | no | A short note, e.g. the page or product they were viewing |

## Security & limits

- Allowed domains: if set, the widget only fires from those domains — a copied key cannot be reused elsewhere.
- Mobile apps: enable "Allow calls from mobile apps" so non-web (no-origin) requests are accepted; otherwise they are blocked when domains are set.
- Rate limits: one call per number per 24h, plus a per-network hourly cap.
- Consent: the visitor's action is the consent; you are responsible for lawful consent/DND on your site.
- Billing & results: calls use your module, bill to your minutes, and appear in your dashboard results (summary, recording, questions answered).