API عمومی مُنشیوا v1
تماسها، مشتریان، نوبتها و پیگیریهای شیوا را در نرمافزار خودتان بخوانید و بنویسید؛ سرنخ بفرستید تا شیوا همان لحظه تماس بگیرد؛ برای هر رویداد وبهوک امضاشده بگیرید.
https://monshiva.com/api/public/v1شروع سریع
API عمومی مُنشیوا برای این است که سایت، فرمها، CRM یا ابزار اتوماسیون شما (n8n، Make و مانند آن) مستقیماً با شیوا کار کنند: تماسها و مشتریان را بخوانید، سرنخ ثبت کنید، نوبتها و پیگیریها را همگام کنید و برای هر رویداد وبهوک بگیرید.
فایل OpenAPI: مشخصات کامل همهٔ مسیرها در openapi.json؛ آن را در Postman، Insomnia یا ابزار ساخت کد خودتان وارد کنید.
- در پنل: تنظیمات و اشتراک ← API و وبهوک ← کلید تازه (فقط مالک/مدیر). کلید فقط یک بار نمایش داده میشود.
- هر درخواست را با هدر
Authorization: Bearer msk_live_…بفرستید. - آدرس پایه:
https://monshiva.com/api/public/v1— فقط HTTPS.
bashcurl https://monshiva.com/api/public/v1/me \
-H "Authorization: Bearer msk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
json{
"workspace": {"id": "8a75…", "name": "ویستا ویزا", "industry": "immigration", "branch": {"label": "شیراز · مرکزی", "organization": "گروه ویستا"}},
"key": {"id": "key_1a2b3c", "name": "سایت", "scopes": ["read", "leads:write"]},
"limits": {"per_minute": 60, "per_day": 5000}, "version": "v1", "time": "2026-11-08T14:05:12+03:30"
}احراز هویت و دسترسیها
هر کلید فقط به یک فضای کار دسترسی دارد و در سرور بهصورت هش (SHA-256) نگه داشته میشود. دسترسیها (scope) هنگام ساخت کلید انتخاب میشوند:
| scope | اجازه میدهد |
|---|---|
read | خواندن تماسها، مشتریان، نوبتها، زمانهای آزاد و پیگیریها (پیشفرض، همیشه هست) |
leads:write | ثبت سرنخ تازه (و درخواست تماس فوری شیوا) |
bookings:write | ثبت نوبت برای یک تماس، جابهجایی و لغو نوبت |
tasks:write | ثبت پیگیری برای یک مشتری |
contacts:phone | نمایش شمارهٔ کامل مشتری (بدون آن شمارهها ماسک میشوند: 0912***4567) |
webhooks:manage | ساخت/حذف/آزمایش وبهوک از طریق API |
کلید لو رفته را همان لحظه از پنل لغو کنید؛ «آخرین استفاده» هر کلید در پنل دیده میشود.
محدودیتها، خطاها و Idempotency
- نرخ: ۶۰ درخواست در دقیقه و ۵٬۰۰۰ در روز برای هر کلید؛ بیش از آن
429با هدرRetry-After. - زمانها: ISO-8601 به وقت تهران (
+03:30). تاریخها میلادیYYYY-MM-DD. - صفحهبندی:
?page=از ۱؛ هر صفحه ۲۰ تا ۲۵ مورد؛ در فهرست تماسهاhas_moreمیگوید صفحهٔ بعدی هست یا نه. - Idempotency: روی
POST /leadsوPOST /tasksهدرIdempotency-Key: <شناسهٔ یکتای شما>بفرستید؛ تکرار همان درخواست تا ۲۴ ساعت همان پاسخ را برمیگرداند و رکورد تکراری نمیسازد.
همهٔ خطاها یک شکل دارند:
json{"error": {"code": "validation_error", "message": "شمارهٔ موبایل ایرانی معتبر (09…) لازم است.", "field": "mobile"}}
| کد HTTP | code | معنی |
|---|---|---|
| 400 | bad_request | بدنهٔ JSON خراب است |
| 401 | unauthorized | کلید نیست، نامعتبر یا لغو شده |
| 403 | insufficient_scope / crm_unavailable | کلید این دسترسی را ندارد / CRM فضا فعال نیست |
| 404 | not_found | رکورد پیدا نشد |
| 409 | limit | سقف تعداد (کلید/وبهوک) |
| 422 | validation_error | فیلد نامعتبر (در field آمده) |
| 429 | rate_limited | محدودیت نرخ |
| 503 | upstream_unavailable | موتور مکالمه یا CRM لحظهای در دسترس نیست؛ کمی بعد دوباره بفرستید |
تماسها
GET /calls?page=1&status=all|completed|incomplete — تماسها و گفتگوهای واقعی مشتریان (جدیدترین اول). GET /calls/{id} جزئیات یک تماس.
json{
"calls": [{
"id": 438, "created": "2026-11-07T20:34:45+03:30", "completed": true, "state": "completed",
"channel": "phone", // phone | web | chat
"direction": "outbound", // inbound | outbound
"customer": {"name": "ستار غیرتمند", "phone": "0933***9003"},
"summary": "درخواست مشاورهٔ مهاجرت تحصیلی…", "requested_service": "مشاوره تحصیلی",
"booking": {"id": "VV-1100BE7AEC", "status": "confirmed"}, // یا null
"callback_requested": false, "recording_available": true, "transcript_available": true
}],
"page": 1, "limit": 20, "has_more": true
}
در نسخهٔ ۱ فایل صوت و متن کامل از طریق API داده نمیشود (پنل و ضبط با رضایت)؛ فقط «در دسترس بودن» آنها اعلام میشود.
مشتریان
GET /contacts?q=&page=&stage= — مشتریان CRM فضا (۲۵ در هر صفحه). GET /contacts/{id} پروندهٔ یک مشتری با تماسها، نوبتها و پیگیریها.
json{"contacts": [{"id": "o000000035", "name": "ستار غیرتمند", "phone": "0912***1203", "verified": true, "stage": "new", "created": "2026-11-06T05:08:08+03:30"}],
"page": 1, "limit": 25, "total": 86, "stages": {"new": "متقاضی جدید", "qualified": "بررسی اولیه", "...": "..."}}نوبتها و زمانهای آزاد
GET /bookings?date_from=&date_to=&status= — نوبتهای ثبتشده. GET /availability?date=YYYY-MM-DD&advisor_id=default — زمانهای آزاد همان روز طبق برنامهٔ کاری فضا.
json{"bookings": [{"id": "VV-1100BE7AEC", "call_id": 187, "date": "2026-11-07", "time": "11:30", "customer": "ستار غیرتمند",
"service": "مشاوره مهاجرت به کانادا", "status": "confirmed", "revision": 1, "advisor_id": "default"}], "timezone": "Asia/Tehran", "duration_minutes": 30}
ثبت نوبت (bookings:write): POST /bookings با {"call_id": 438, "date": "2026-11-12", "time": "10:30", "service": "…"} — در نسخهٔ ۱ نوبت به یک تماس تکمیلشدهٔ مشتری (call_id) وصل میشود تا هویت و شمارهٔ تأییدشدهٔ او از همان تماس بیاید. جابهجایی/لغو: PATCH /bookings/{id} با {"operation": "reschedule", "date": "…", "time": "…", "revision": 1} یا {"operation": "cancel", "reason": "…", "revision": 1}؛ revision همان مقدار فعلی نوبت است (قفل خوشبینانه). پیامک تأیید/تغییر مثل پنل از خط خود شما میرود.
پیگیریها
GET /tasks?status=open|completed|all&page= — پیگیریهای ثبتشده روی پروندهها. ثبت پیگیری (tasks:write): POST /tasks
json{"contact_id": "o000000035", "title": "تماس برای ارسال مدارک", "note": "مدارک تحصیلی را بخواهید", "due": "2026-11-12T10:00:00", "assignee": "office"}
due به وقت تهران و در آینده؛ assignee اختیاری (شناسهٔ همکار از پنل؛ پیشفرض همکار مسئول دفتر).
سرنخها و تماس فوری شیوا
POST /leads (leads:write) — فرم سایت، کمپین یا هر منبع دیگر را به یک سرنخ در CRM فضا تبدیل میکند؛ با "call_now": true شیوا در ساعت کاری (۸ تا ۲۱:۳۰ تهران) با مشتری تماس میگیرد و نتیجه به همان پرونده میرود (Speed-to-Lead). تماس فوری فقط برای فضاهایی فعال است که خط خروجی دارند؛ وگرنه call_now.queued=false با reason برمیگردد.
bashcurl -X POST https://monshiva.com/api/public/v1/leads \
-H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: form-2026-11-08-1234" \
-d '{"name": "مریم احمدی", "mobile": "09121234567", "source": "site-form", "note": "مشاورهٔ ویزای تحصیلی کانادا", "call_now": true}'
json{"lead": {"id": "odoo:41", "name": "مریم احمدی", "mobile": "0912***4567", "source": "site-form", "duplicate": false, "created": "2026-11-08T14:10:03+03:30"},
"call_now": {"queued": true, "reason": null, "window": "08:00–21:30 Asia/Tehran"}}دریافت فرم از هر فرمساز (پرسلاین، فرمالو، Google Forms و …)
POST /forms/inbound (leads:write) — نشانی وبهوکی است که در تنظیمات فرمساز میگذارید. بدنه هر شکلی داشته باشد (JSON یا فرم معمولی، تخت یا تو در تو، یا فهرست «پرسش/پاسخ»)، شمارهٔ موبایل ایرانی، نام و ایمیل خودکار پیدا میشوند و همهٔ پاسخها در یادداشت سرنخ میآیند؛ نقشهکشی فیلد لازم نیست. همان پاسخ اگر دوباره فرستاده شود، سرنخ تکراری نمیسازد (duplicate: true).
- احراز هویت: سرآیند
Authorization: Bearer msk_live_…؛ اگر فرمساز سرآیند نمیپذیرد،?key=msk_live_…در نشانی (برای این کار یک کلید جدا با فقط دسترسی «ثبت سرنخ» بسازید تا هر وقت خواستید باطلش کنید). - پارامترهای اختیاری نشانی:
source=porsline(برچسب منبع در CRM) وcall_now=1(تماس فوری شیوا، در فضاهایی که خط خروجی دارند). - اگر در پاسخ شمارهٔ موبایل نباشد:
422 validation_errorباfield: "mobile"؛ یک پرسش «شمارهٔ موبایل» به فرم اضافه کنید.
bashcurl -X POST "https://monshiva.com/api/public/v1/forms/inbound?source=porsline" -H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json" -d '{"answers": [{"question": "نام و نام خانوادگی", "answer": "مریم احمدی"}, {"question": "شمارهٔ موبایل", "answer": "۰۹۱۲۱۲۳۴۵۶۷"}, {"question": "خدمت مورد نظر", "answer": "ایمپلنت"}]}'
json{"lead": {"id": "odoo:52", "name": "مریم احمدی", "mobile": "0912***4567", "source": "porsline", "duplicate": false, "created": "2026-11-18T13:12:44+03:30"},
"call_now": {"queued": false, "reason": null, "window": "08:00–21:30 Asia/Tehran"}}
راهنمای قدمبهقدم پرسلاین و فرمسازهای دیگر: اتصالها و افزونهها.
اتصال سایت و افزونهٔ وردپرس
POST /sites (leads:write) — یک سایت را به فضای شما وصل میکند: دامنه و نسخهٔ www آن به فهرست مجاز دستیار صوتی و چت اضافه میشود و نشانی اسکریپت دستیار برمیگردد. افزونهٔ وردپرس منشیوا هنگام اتصال همین را صدا میزند؛ برای سایتهای غیروردپرسی هم کار میکند. فراخوانی دوباره بیخطر است: همان توکن برمیگردد و فقط زمان آخرین اتصال بهروز میشود.
bashcurl -X POST https://monshiva.com/api/public/v1/sites \
-H "Authorization: Bearer msk_live_…" -H "Content-Type: application/json" \
-d '{"domain": "example.com", "platform": "wordpress", "version": "1.2.1"}'
json{"site": {"domain": "example.com", "platform": "wordpress"},
"widget": {"token": "emb_…", "script": "https://monshiva.com/widget/monshiva-widget.js?token=emb_…", "type": "voice"},
"outbound_calls": false, "business": {"name": "کلینیک لبخند"}}
برای نصب دستیار، این خط را پیش از </body> بگذارید:
html<script src="{widget.script}" defer></script>
outbound_calls نشان میدهد call_now در این فضا تماس میگیرد یا نه. دامنهٔ نامعتبر: 422 validation_error با field: "domain".
کاربران وردپرس به کد نیازی ندارند: افزونهٔ وردپرس منشیوا اتصال، فرم «یک دقیقهای با شما تماس میگیریم» و ورود فرمهای Contact Form 7، WPForms، Gravity، المنتور، Ninja و Fluent و سفارشهای ووکامرس به CRM را خودش انجام میدهد.
بیعانهٔ نوبت
اگر کسبوکار «بیعانهٔ نوبت» را در پنل فعال کرده باشد (تنظیمات ← بیعانهٔ نوبت؛ با درگاه و حساب خودِ کسبوکار — زرینپال یا آقای پرداخت)، برای هر نوبت تأییدشده یک لینک پرداخت یکبارمصرف ساخته میشود: https://monshiva.com/pay/<token>. مشتری در درگاه پرداخت میکند، منشیوا نتیجه را سمت سرور تأیید میکند و وضعیت را نگه میدارد؛ پولی نزد منشیوا نمیماند.
GET /deposits?booking_id=&status=&page= — فهرست بیعانهها (جدیدترین اول). هر نوبت در GET /bookings هم فیلد deposit دارد (یا null).
json{"deposits": [{"token": "k3Jf…", "booking_id": "VV-1100BE7AEC", "call_id": 187, "amount": 500000, "currency": "IRT", "gateway": "zarinpal",
"state": "paid", "state_label": "پرداخت شد", "pay_url": null, "customer": {"name": "ستار غیرتمند", "phone": "0912***1203"},
"service": "مشاوره", "date": "2026-11-12", "time": "10:30", "ref_id": "123456789", "sms_status": "awaiting_template",
"created": "2026-11-08T18:40:00+03:30", "expires": "2026-11-09T18:40:00+03:30", "paid_at": "2026-11-08T19:02:11+03:30"}],
"page": 1, "limit": 20, "has_more": false, "enabled": true, "amount": 500000}
| state | یعنی |
|---|---|
pending | لینک ساخته شده، پرداخت شروع نشده |
ready / verifying | مشتری در درگاه است / در حال تأیید |
paid | تأیید شد (ref_id کد پیگیری درگاه) |
review | نتیجهٔ درگاه نامعلوم ماند؛ از پنل «بررسی مجدد» بزنید |
expired | مهلت تمام شد (پیشفرض ۲۴ ساعت و همیشه پیش از ساعت نوبت) |
cancelled | نوبت لغو شد |
waived | همکار «حضوری/معاف» زد |
لینک پرداخت را خودتان هم میتوانید به مشتری برسانید (پیامک، پیامرسان، سایت): از رویداد deposit.created یا همین فهرست. پیامک خودکار منشیوا پس از تأیید الگوی اپراتور فعال میشود (sms_status).
وبهوکها
برای هر رویداد، یک POST با بدنهٔ JSON به آدرس https شما فرستاده میشود. وبهوک را از پنل (API و وبهوک ← وبهوک تازه) یا با POST /webhooks بسازید؛ secret فقط یک بار نمایش داده میشود.
| رویداد | کی |
|---|---|
call.completed | پایان هر تماس/گفتگوی مشتری (همان شکل /calls) |
booking.created | ثبت نوبت در تماس یا از API |
callback.created | مشتری درخواست تماس/پیگیری گذاشته |
lead.created | سرنخ تازه از API |
task.created | پیگیری تازه از API |
deposit.created | لینک بیعانه برای یک نوبت ساخته شد (data.deposit.pay_url) |
deposit.paid | بیعانه پرداخت و تأیید شد |
deposit.expired | مهلت بیعانه تمام شد |
webhook.test | دکمهٔ «آزمایش» |
json{"id": "evt_6f1c…", "type": "call.completed", "created": "2026-11-08T14:12:40+03:30", "workspace": "8a75…", "branch": null,
"data": {"call": {"id": 441, "channel": "phone", "customer": {"name": "…", "phone": "0912***4567"}, "summary": "…", "booking": null, "callback_requested": true}}}
مدیریت وبهوکها با API (نیاز به scope webhooks:manage):
| مسیر | کار |
|---|---|
GET /webhooks | فهرست وبهوکهای فضای کار + فهرست رویدادهای مجاز (events) |
POST /webhooks | ساخت: {{"url": "https://…", "events": ["call.completed", …]}} → پاسخ شامل secret (فقط همین یک بار) |
DELETE /webhooks/{{id}} | حذف وبهوک |
POST /webhooks/{{id}}/test | ارسال یک رویداد آزمایشی ping به آدرس شما و برگرداندن نتیجهٔ تحویل |
GET /webhooks/{{id}}/deliveries | آخرین تحویلها (وضعیت HTTP، زمان، تلاش مجدد) برای عیبیابی |
امضا و تلاش مجدد. هدر X-Monshiva-Signature: t=<unix>,v1=<hex> که در آن v1 = HMAC-SHA256(secret, t + "." + body). فقط درخواستهایی را بپذیرید که امضا درست است و t کمتر از ۵ دقیقه با زمان حال فاصله دارد. پاسخ 2xx یعنی تحویل شد؛ در غیر این صورت ۱، ۵، ۳۰، ۱۸۰ و ۷۲۰ دقیقه بعد دوباره تلاش میشود و پس از ۵ شکست پیاپی وبهوک معلق میشود (در پنل با «تحویلها» ببینید و دوباره بسازید). ترتیب تضمین نمیشود؛ با id رویداد تکراریزدایی کنید.
pythonimport hmac, hashlib, time
def verify(secret: str, header: str, body: bytes) -> bool:
parts = dict(p.split('=', 1) for p in header.split(','))
if abs(time.time() - int(parts['t'])) > 300: return False
expected = hmac.new(secret.encode(), (parts['t'] + '.').encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts['v1'])
javascript// Node.js (Express): app.post('/monshiva-hook', express.raw({type: 'application/json'}), (req, res) => { ... })
const crypto = require('crypto');
function verify(secret, header, rawBody) {
const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
const v1 = crypto.createHmac('sha256', secret).update(p.t + '.' + rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(p.v1));
}
php<?php // WordPress / PHP
$raw = file_get_contents('php://input');
$parts = []; parse_str(str_replace(',', '&', $_SERVER['HTTP_X_MONSHIVA_SIGNATURE']), $parts);
$ok = abs(time() - (int)$parts['t']) <= 300 && hash_equals(hash_hmac('sha256', $parts['t'] . '.' . $raw, $secret), $parts['v1']);
if (!$ok) { http_response_code(401); exit; }
$event = json_decode($raw, true); // $event['type'], $event['data']
http_response_code(200);نمونهٔ n8n
قالبهای آماده: فایل را بگیرید و در n8n از منوی گردشکار «Import from File» را بزنید؛ راهنمای هر قالب روی یادداشت داخل خودش است.
- رویدادها با امضای معتبر: رویدادهای منشیوا را میگیرد، امضا را بررسی میکند و یک پیام فارسی آماده برای تلگرام، بله یا ایمیل میدهد.
- سرنخ از هر فرم: هر فرم یا سامانه را به ثبت سرنخ (و در صورت نیاز تماس فوری شیوا) وصل میکند.
- گزارش روزانهٔ تماسها: هر شب ساعت ۲۰ خلاصهٔ تماسهای همان روز را میسازد.
گرفتن رویدادها: یک گرهٔ Webhook (POST) بسازید، آدرس Production آن را در پنل منشیوا ثبت کنید و در گرهٔ بعدی (Code) امضا را با کد بالا بررسی کنید. خواندن یا نوشتن: گرهٔ HTTP Request با Authentication = Header Auth (نام Authorization، مقدار Bearer msk_live_…).
json{"method": "POST", "url": "https://monshiva.com/api/public/v1/leads",
"sendHeaders": true, "headerParameters": {"parameters": [{"name": "Idempotency-Key", "value": "={{ $json.form_id }}"}]},
"sendBody": true, "specifyBody": "json",
"jsonBody": "={{ {\"name\": $json.name, \"mobile\": $json.phone, \"source\": \"site-form\", \"call_now\": true} }}"}
جریان پیشنهادی: فرم سایت ← n8n ← POST /leads (call_now) ← شیوا تماس میگیرد ← call.completed به n8n ← پیام به تلگرام/ایمیل تیم فروش.
تغییرات
- مستندات — ۱ آذر ۱۴۰۵ (۲۲ نوامبر ۲۰۲۶): فایل openapi.json (OpenAPI 3) و سه قالب آمادهٔ n8n.
- v1 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶): انتشار اول: کلیدهای tenant-scoped، تماسها، مشتریان، نوبتها/زمانهای آزاد، پیگیریها، سرنخ + تماس فوری، وبهوک با امضای HMAC و تلاش مجدد.
- v1.1 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶، عصر): بیعانهٔ نوبت:
GET /deposits، فیلدdepositروی نوبتها، رویدادهایdeposit.created/deposit.paid/deposit.expired. - v1.2 — ۱۸ آبان ۱۴۰۵ (۸ نوامبر ۲۰۲۶، شب): چندشعبه: فیلد
branch(برچسب شعبه و نام سازمان، یاnull) درGET /meو در بدنهٔ همهٔ رویدادهای وبهوک. کلید هر شعبه جداست؛ کلید سازمانی در نسخهٔ بعد. - مستندات (۸ نوامبر، شب): جدول مدیریت وبهوک با API (
GET/POST /webhooks،DELETE،/test،/deliveries) اضافه شد؛ رفتار API تغییری نکرده است. - v1.3 — ۲۴ آبان ۱۴۰۵ (۱۵ نوامبر ۲۰۲۶): اتصال سایت:
POST /sites(مجازکردن دامنه برای دستیار + اسکریپت نصب)؛ پایهٔ افزونهٔ وردپرس منشیوا. - v1.4 — ۲۷ آبان ۱۴۰۵ (۱۸ نوامبر ۲۰۲۶):
POST /forms/inboundبرای وبهوک هر فرمساز (پرسلاین، فرمالو، Google Forms…) بدون نقشهکشی فیلد. - در راه: ارسال پیامک/پیام الگودار (
messages:send)، ثبت نوبت بدون تماس قبلی، دسترسی به فایل صوت/متن با قرارداد (calls:media).
فیلد تازه اضافه میشود، حذف نمیشود؛ هر تغییر ناسازگار نسخهٔ جدید (v2) خواهد داشت.
