رابط برنامه‌نویسی اختصاصی زیمو چت

مستندات REST API v2

با استفاده از API زیمو چت می‌توانید گفتگوها، مخاطبان، پیام‌ها و گزارش‌های عملکرد فضای کاری خود را به‌صورت خودکار مدیریت یا با CRM سازمان خود یکپارچه کنید.

Base URL: https://api.zimu.chat

احراز هویت و امنیت

نحوه ارسال هدرهای امنیتی و امضای درخواست‌ها با توکن اختصاصی.

همهٔ درخواست‌ها باید از پروتکل امن HTTPS استفاده کنند و هدر استاندارد Authorization: Bearer sk_live_... را در هدر درخواست ارسال نمایند.

Authorization: Bearer sk_live_YOUR_WORKSPACE_KEY

محدودیت نرخ درخواست (Rate Limit):هر کلید API حداکثر مجاز به ارسال ۱۲۰ درخواست در دقیقه است. در صورت فراتر رفتن، پاسخ با وضعیت 429 Too Many Requests بازگردانده می‌شود.

دریافت کلید API

مراحل ایجاد و صدور کلیدهای جدید از طریق پنل مدیریت زیمو چت.

وارد پنل کاربری شده و به بخش تنظیمات بروید.
از منوی تنظیمات، گزینه کلیدهای API را انتخاب کنید.
روی دکمه «+ ساخت کلید تازه» بزنید، نام و دامنه‌های دسترسی (Scopes) مورد نظر را تعیین کنید.
کلید تولیدشده را کپی و در متغیرهای محیطی امن سرور خود قرار دهید (کلید فقط یک‌بار نمایش داده می‌شود).

GET/api/v2/conversationsدسترسی: مشاهده گفتگوها

فهرست گفتگوها

دریافت فهرست گفتگوها با فیلتر و صفحه‌گذاری مبتنی بر مکان‌نما (Cursor).

پارامترهای درخواست:

Status — فیلتر وضعیت گفتگو (Open یا Resolved)
AssigneeId — فقط گفتگوهای واگذارشده به یک اپراتور
WebsiteId — فقط گفتگوهای یک وب‌سایت
limit — تعداد نتایج (پیش‌فرض ۲۰، حداکثر ۵۰)
cursor — مکان‌نمای صفحهٔ بعدی از NextCursor پاسخ قبلی

نمونه درخواست و پاسخ:

curl -X GET "https://api.zimu.chat/api/v2/conversations?limit=20" \
  -H "Authorization: Bearer «redacted:sk_live_…»"

GET/api/v2/conversations/:idدسترسی: مشاهده گفتگوها

جزئیات گفتگو

دریافت اطلاعات کامل یک گفتگو با شناسهٔ آن.

پارامترهای درخواست:

id — شناسهٔ گفتگو (در مسیر درخواست)

نمونه درخواست و پاسخ:

curl -X GET "https://api.zimu.chat/api/v2/conversations/68cba1f4a2d94e0f8c31b7aa" \
  -H "Authorization: Bearer «redacted:sk_live_…»"

GET/api/v2/conversations/:id/messagesدسترسی: مشاهده گفتگوها

پیام‌های گفتگو

دریافت پیام‌های یک گفتگو به‌ترتیب صعودی (قدیمی‌ترین اول) با صفحه‌گذاری.

پارامترهای درخواست:

limit — تعداد نتایج (پیش‌فرض ۵۰، حداکثر ۲۰۰)
before — تاریخ ISO؛ فقط پیام‌های قدیمی‌تر از این لحظه

نمونه درخواست و پاسخ:

curl -X GET "https://api.zimu.chat/api/v2/conversations/68cba1f4a2d94e0f8c31b7aa/messages?limit=50" \
  -H "Authorization: Bearer «redacted:sk_live_…»"

POST/api/v2/conversations/:id/messagesدسترسی: پاسخ به گفتگوها

ارسال پیام در گفتگو

ارسال پیام متنی جدید از طرف اپراتور / سیستم در یک گفتگو.

پارامترهای درخواست:

id — شناسهٔ گفتگو (در مسیر درخواست)

نمونه درخواست و پاسخ:

curl -X POST "https://api.zimu.chat/api/v2/conversations/68cba1f4a2d94e0f8c31b7aa/messages" \
  -H "Authorization: Bearer «redacted:sk_live_…»" \
  -H "Content-Type: application/json" \
  -d '{"Content":"متن پیام ارسالی"}'

PATCH/api/v2/conversations/:id/statusدسترسی: مدیریت گفتگوها

تغییر وضعیت گفتگو

بستن (Resolved) یا بازگشایی مجدد (Open) یک گفتگو.

پارامترهای درخواست:

id — شناسهٔ گفتگو (در مسیر درخواست)

نمونه درخواست و پاسخ:

curl -X PATCH "https://api.zimu.chat/api/v2/conversations/68cba1f4a2d94e0f8c31b7aa/status" \
  -H "Authorization: Bearer «redacted:sk_live_…»" \
  -H "Content-Type: application/json" \
  -d '{"Status":"Resolved"}'

GET/api/v2/contactsدسترسی: مشاهده گفتگوها

جستجو و فهرست مخاطبان

دریافت فهرست مخاطبان و مشتریان با قابلیت جستجوی متنی.

پارامترهای درخواست:

Search — متن جستجو روی نام، شماره تماس یا ایمیل
limit — تعداد نتایج (پیش‌فرض ۲۰، حداکثر ۵۰)
cursor — مکان‌نمای صفحهٔ بعدی

نمونه درخواست و پاسخ:

curl -X GET "https://api.zimu.chat/api/v2/contacts?Search=0912&limit=20" \
  -H "Authorization: Bearer «redacted:sk_live_…»"

GET/api/v2/reports/summaryدسترسی: مشاهده گزارش‌ها

خلاصهٔ آماری و عملکرد

دریافت آمار کلی فضای کاری شامل حجم پیام‌ها، نرخ پاسخ‌گویی و رضایت.

پارامترهای درخواست:

days — بازه زمانی به روز (پیش‌فرض ۷، حداکثر ۹۰)

نمونه درخواست و پاسخ:

curl -X GET "https://api.zimu.chat/api/v2/reports/summary?days=7" \
  -H "Authorization: Bearer «redacted:sk_live_…»"

کدهای وضعیت و خطاها

فرمت یکپارچه خطاهای API و معانی کدهای بازگشتی.

{
  "Success": false,
  "Error": {
    "Code": "Unauthorized",
    "Message": "کلید API نامعتبر است یا منقضی شده است."
  }
}

400 Bad Request

پارامترهای ارسالی در بدنه یا کوئری معتبر نیستند.

401 Unauthorized

کلید ارسال نشده یا نامعتبر است.

403 Forbidden

کلید API سطح دسترسی لازم برای این اندپوینت را ندارد.

404 Not Found

مورد درخواستی (گفتگو یا مخاطب) یافت نشد.