مستندات API چاپارتل

با API چاپارتل از کد خودت پیامک می‌فرستی، کد تأیید می‌سازی و بررسی می‌کنی، شماره‌های تلفن ابری را مدیریت می‌کنی و رویدادها را با وب‌هوک لحظه‌ای دریافت می‌کنی.

همه‌ی درخواست‌ها با HTTPS و بدنه‌ی JSON کار می‌کنند و پاسخ‌ها هم JSON هستند. متن فارسی را مستقیم با UTF-8 بفرست؛ نیازی به کدگذاری جداگانه نیست.

شروع سریع در سه قدم

1. در ناحیه‌ی کاربری، بخش کلیدهای API، یک کلید بساز. کلیدهای آزمایشی با ct_test_ و کلیدهای اصلی با ct_live_ شروع می‌شوند.
2. کلید را در متغیر محیطی CHAPARTEL_KEY بگذار و هرگز آن را در کد سمت مرورگر قرار نده.
3. اولین پیامک را بفرست:

با کلید آزمایشی، پیامک واقعاً ارسال نمی‌شود اما وضعیت‌ها و وب‌هوک‌ها مثل محیط اصلی تولید می‌شوند. برای آزمایش تحویل ناموفق، به شماره‌ی 09000000000 بفرست.

احراز هویت

هر درخواست باید سربرگ Authorization با مقدار Bearer <کلید> داشته باشد. درخواست بدون کلید پاسخ 401 و کلید بدون دسترسی لازم پاسخ 403 می‌گیرد.

Authorization: Bearer ct_live_8f2c…a91d

دسترسی کلیدها

هنگام ساخت کلید می‌توانی دسترسی را محدود کنی: sms، verify، numbers، contacts. برای سرورهای حساس، فهرست IP مجاز هم تعریف کن.

نشانی پایه و نسخه‌ها

نشانی پایه https://api.chapartel.com/v1 است. تغییرات ناسازگار فقط در نسخه‌ی جدید (v2) می‌آیند و نسخه‌ی قبلی دست‌کم ۱۲ ماه پشتیبانی می‌شود.

قالب شماره‌ها

شماره‌ی ایرانی را به هر یک از قالب‌های 09121234567، 9121234567 یا +989121234567 بفرست؛ چاپارتل آن را به قالب بین‌المللی E.164 تبدیل می‌کند. ارقام فارسی هم پذیرفته می‌شوند.

زمان‌ها

همه‌ی زمان‌ها در قالب ISO 8601 و منطقه‌ی زمانی UTC هستند، مثل 2026-10-23T08:30:00Z. برای زمان‌بندی به وقت تهران، اختلاف +03:30 را در مقدار بگذار.

خطاها

خطاها کد وضعیت HTTP مناسب و بدنه‌ی یکسان دارند. فیلد code ثابت است و برای منطق برنامه از آن استفاده کن؛ متن message ممکن است تغییر کند.

{
  "error": {
    "code": "invalid_recipient",
    "message": "شماره‌ی گیرنده معتبر نیست",
    "param": "to",
    "request_id": "req_7Hk2pQ"
  }
}

فهرست کامل در بخش کدهای خطا آمده است.

محدودیت نرخ درخواست

هر کلید به‌طور پیش‌فرض ۳۰ درخواست در ثانیه دارد. ارسال گروهی با ارسال انبوه تا ۱۰۰ هزار گیرنده را در یک درخواست می‌پذیرد و از این سهمیه کم نمی‌کند.

تکرار امن درخواست (Idempotency)

اگر شبکه قطع شد و نمی‌دانی پیامک رفته یا نه، همان درخواست را با همان سربرگ Idempotency-Key دوباره بفرست. چاپارتل تا ۲۴ ساعت پاسخ اول را برمی‌گرداند و پیامک دوباره ارسال نمی‌شود.

Idempotency-Key: order-2481-shipped

صفحه‌بندی

فهرست‌ها با پارامترهای limit (حداکثر ۱۰۰) و cursor صفحه‌بندی می‌شوند. پاسخ فیلد next_cursor دارد؛ وقتی null شد، به انتهای فهرست رسیده‌ای.

ارسال پیامک

یک پیامک به یک یا چند گیرنده (تا ۱۰۰ نفر) می‌فرستد. برای بیشتر از ۱۰۰ گیرنده از ارسال انبوه استفاده کن.

ارسال انبوه

یک کمپین با متن ثابت یا متن شخصی‌سازی‌شده برای هر گیرنده می‌سازد. متغیرها با {{name}} در متن مشخص می‌شوند و از فیلد vars هر گیرنده پر می‌شوند.

دریافت وضعیت پیامک

وضعیت یک پیامک را برمی‌گرداند. برای اطلاع لحظه‌ای، به‌جای پرس‌وجوی پشت‌سرهم از وب‌هوک استفاده کن.

چرخه‌ی وضعیت

queued ← sent ← delivered. وضعیت‌های پایانی دیگر: failed (خطای اپراتور)، undeliverable (گوشی خاموش تا ۴۸ ساعت) و blocked (شماره در لیست سیاه برای پیامک تبلیغاتی).

پیامک‌های دریافتی

پیامک‌هایی که مشتری‌ها به خط اختصاصی تو فرستاده‌اند. رویداد message.inbound هم برای هر پیامک دریافتی ارسال می‌شود.

ارسال کد تأیید

کد یک‌بارمصرف می‌سازد و می‌فرستد. لازم نیست کد را خودت بسازی یا نگه داری. کد تأیید صف جداگانه دارد و اگر اپراتور اول خطا بدهد، خودکار از خط جایگزین ارسال می‌شود.

بررسی کد تأیید

کدی که کاربر وارد کرده را بررسی می‌کند. هر کد ۵ بار فرصت ورود و ۱۲۰ ثانیه اعتبار دارد.

شماره‌های تلفن ابری

شماره‌های فعال حساب و منوی صوتی متصل به هرکدام را برمی‌گرداند.

گزارش تماس‌ها

تماس‌های ورودی و خروجی شماره‌های ابری، همراه با نشانی فایل ضبط‌شده. نشانی فایل ۱۵ دقیقه معتبر است.

ساخت مخاطب

مخاطب را به دفترچه تلفن اضافه می‌کند. اگر شماره از قبل وجود داشته باشد، اطلاعاتش به‌روز می‌شود.

وب‌هوک‌ها

در پنل، بخش کلیدهای API و وب‌هوک، نشانی سرور خودت را ثبت کن. چاپارتل برای هر رویداد یک درخواست POST با بدنه‌ی JSON می‌فرستد. سرور باید ظرف ۱۰ ثانیه کد 2xx برگرداند؛ در غیر این صورت تا ۲۴ ساعت با فاصله‌ی افزایشی دوباره تلاش می‌کنیم.

{
  "id": "evt_01JB7X3K",
  "type": "message.delivered",
  "created_at": "2026-10-23T08:30:04Z",
  "data": { "message_id": "msg_9fK2a", "to": "+989120000000", "parts": 1 }
}

بررسی امضای وب‌هوک

هر درخواست وب‌هوک سربرگ X-Chapartel-Signature دارد: امضای HMAC-SHA256 از بدنه‌ی خام درخواست با کلید امضای وب‌هوک. پیش از پردازش، امضا را بررسی کن و درخواست‌های قدیمی‌تر از ۵ دقیقه (سربرگ X-Chapartel-Timestamp) را رد کن.

import crypto from "node:crypto";

export function verify(rawBody, headers, secret) {
  const ts = headers["x-chapartel-timestamp"];
  const sig = headers["x-chapartel-signature"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

کدهای خطا

کتابخانه‌ها (SDK)

تغییرات

• فیلد fallback_after برای کد تأیید اضافه شد.
• رویداد call.gathered اضافه شد.

• متغیرهای شخصی‌سازی در ارسال انبوه.

• انتشار نخست.