مرجع API

Webhookها

برای رویدادهای یک پروژه webhook تعریف کنید. در سمت دریافت‌کننده امضای پیام‌ها را بررسی کنید و رویدادهای تکراری را بر اساس شناسه کنار بگذارید.

روند کار

01ساخت webhook برای رویدادهای پروژه
02ارسال دوبارهٔ یک رویداد webhook
03تعویض secret امضای webhook

روی هر عملیات بزنید تا همهٔ ورودی‌ها، request، response و کدهای وضعیت آن را ببینید.

ساخت webhook برای رویدادهای پروژه

POST/api/v1/chat/projects/{project_id}/webhooks

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

نوع محتواapplication/json

پارامترها

این جدول همهٔ ورودی‌هایی را که این endpoint می‌پذیرد نشان می‌دهد. مقدارهای نمونه‌ها ساختگی‌اند و یک روش امن برای یکپارچه‌سازی را نشان می‌دهند.

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`project_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ پروژه.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`event_types`	Body	array<value>	الزامی	مخصوص مهوش	رویدادهایی که می‌خواهید دریافت کنید. رویداد ناشناخته رد می‌شود و بی‌صدا کنار گذاشته نمی‌شود.
`url`	Body	string	الزامی	مخصوص مهوش	آدرس HTTPS مقصد. هم هنگام ثبت و هم پیش از هر ارسال، با قواعد امنیتی شبکه بررسی می‌شود.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/projects/<project_id>/webhooks' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "response.completed"
  ],
  "url": "https://hooks.example.com/mahvash"
}'

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
201	منبع ساخته شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

ارسال دوبارهٔ یک رویداد webhook

POST/api/v1/chat/webhook-deliveries/{delivery_id}/replay

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`delivery_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ یک ارسال webhook.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/webhook-deliveries/<delivery_id>/replay' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

تعویض secret امضای webhook

POST/api/v1/chat/webhooks/{endpoint_id}/rotate

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`endpoint_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ webhook.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X POST 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>/rotate' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
201	منبع ساخته شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

دریافت webhook و وضعیت ارسال‌ها

GET/api/v1/chat/webhooks/{endpoint_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`endpoint_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ webhook.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

ویرایش رویدادها یا فعال و غیرفعال کردن webhook

PATCH/api/v1/chat/webhooks/{endpoint_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

نوع محتواapplication/json

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`endpoint_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ webhook.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.
`event_types`	Body	array<value>	اختیاری	مخصوص مهوش	فهرست جایگزین نوع رویدادها.
`status`	Body	string	اختیاری	مخصوص مهوش	یکی از `ACTIVE` یا `DISABLED`. فعال‌سازی دوباره، شمارندهٔ غیرفعال‌سازی خودکار را پاک می‌کند.

Request

curl -X PATCH 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "event_types": [
    "response.failed"
  ]
}'

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
400	request نامعتبر است.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

حذف webhook

DELETE/api/v1/chat/webhooks/{endpoint_id}

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`endpoint_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ webhook.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X DELETE 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

این endpoint بدنهٔ JSON برنمی‌گرداند یا خروجی آن فایل باینری است.

کدهای وضعیت

HTTP	توضیحات
204	response محتوایی ندارد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

فهرست webhookهای پروژه

GET/api/v1/chat/projects/{project_id}/webhooks

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`project_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ پروژه.
`search`	Query	string	اختیاری	مخصوص مهوش	جست‌وجو در آدرس مقصد و دلیل غیرفعال شدن، بدون حساسیت به حروف بزرگ و کوچک.
`status`	Query	string	اختیاری	مخصوص مهوش	فیلتر بر اساس `ACTIVE` یا `DISABLED`.
`page`	Query	integer	اختیاری	مخصوص مهوش	شمارهٔ صفحه (از ۱)، وقتی صفحه‌بندی می‌خواهید.
`page_size`	Query	integer	اختیاری	مخصوص مهوش	اندازهٔ صفحه از ۱ تا ۱۰۰، وقتی صفحه‌بندی می‌خواهید.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/projects/<project_id>/webhooks' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

فهرست ارسال‌های اخیر webhook

GET/api/v1/chat/webhooks/{endpoint_id}/deliveries

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`endpoint_id`	مسیر (path)	string	الزامی	مخصوص مهوش	شناسهٔ webhook.
`search`	Query	string	اختیاری	مخصوص مهوش	جست‌وجو در شناسه و نوع رویداد و آخرین کد خطا، بدون حساسیت به حروف بزرگ و کوچک.
`status`	Query	string	اختیاری	مخصوص مهوش	فیلتر بر اساس وضعیت ارسال.
`page`	Query	integer	اختیاری	مخصوص مهوش	شمارهٔ صفحه (از ۱)، وقتی صفحه‌بندی می‌خواهید.
`page_size`	Query	integer	اختیاری	مخصوص مهوش	اندازهٔ صفحه از ۱ تا ۱۰۰، وقتی صفحه‌بندی می‌خواهید.
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/<endpoint_id>/deliveries' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
403	دسترسی لازم را ندارید.
404	منبع پیدا نشد یا برای شما قابل دسترسی نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.

فهرست رویدادهای قابل اشتراک

GET/api/v1/chat/webhooks/event-types

آدرس پایهٔ APIhttps://api.mahvashai.ir

احراز هویتJWT کاربر

Responseresponse در قالب مخصوص مهوش

پارامترها

نام	محل ارسال	نوع	الزامی	پشتیبانی	توضیحات
`X-Request-ID`	Header	string	اختیاری	مخصوص مهوش	شناسهٔ ردگیری که کلاینت می‌فرستد. در همهٔ پاسخ‌ها برمی‌گردد و اگر فرستاده نشود یا قالبش درست نباشد، سرور شناسهٔ تازه‌ای می‌سازد.
`X-Mahvash-Project`	Header	string	اختیاری	مخصوص مهوش	slug یا شناسهٔ پروژه در سازمان شما. دامنهٔ request را محدودتر می‌کند و هرگز دسترسی بیشتری نمی‌دهد.

Request

curl -X GET 'https://api.mahvashai.ir/api/v1/chat/webhooks/event-types' \
  -H "Authorization: Bearer $MAHVASH_USER_JWT"

Response

{
  "status": 0,
  "data": "<value>"
}

این نمونه فقط ساختار response را نشان می‌دهد؛ فیلدهای واقعی به نوع عملیات و مدل بستگی دارند.

کدهای وضعیت

HTTP	توضیحات
200	request با موفقیت انجام شد.
401	اطلاعات احراز هویت فرستاده نشده یا معتبر نیست.
429	از سقف مجاز عبور کرده‌اید.
500	خطای داخلی سرور.