٠١ · نظرة عامة

الـ API الخاص بشاتكس

طلب HTTP واحد يضيف رسالة واتساب إلى قائمة الإرسال. ثم يضبط شاتكس إيقاعها: يحدّد الرسائل غير المقروءة كمقروءة إن وُجدت، ويُظهر مؤشر الكتابة لمدة تناسب طول النص، ويترك فاصلًا متغيّرًا قبل الرسالة التالية في المحادثة نفسها.

كل عملية كتابة تُرجع 202 Accepted مع معرّف للرسالة. وهذا مقصود — الرسالة محفوظة عند هذه النقطة لكنها لم تُسلَّم بعد، لأن الإرسال المضبوط يستغرق فعلًا من ثوانٍ إلى عشرات الثواني.

٠٢

المصادقة

مفتاح API لكل رقم، يُرسل في الـ header بصيغة Bearer. أنشئ واحدًا من إنشاء مفتاح API في صفحة الرقم — يُعرض مرة واحدة ولا يُخزَّن منه إلا التجزئة، فلا يمكن استرجاعه لاحقًا، بل تجديده فقط.

curl https://chatex.store/api/v1/INSTANCE_ID/usage \
  -H "Authorization: Bearer ctx_your_token_here"

{
  "number": {
    "id": "01M1N…",
    "name": "Support line",
    "phone": "+201234567890",
    "status": "WORKING",
    "can_send": true
  },
  "tier": { "name": "Starter", "slug": "starter" },
  "messages": { "sent_today": 41, "limit": 2000, "remaining": 1959 }
}

يوضّح حقل number الرقمَ الذي يفتحه المفتاح، حتى يُكتشف المفتاح الموضوع في البيئة الخطأ قبل أن يُرسل من هوية خاطئة. تكون قيمة phone فارغة حتى يُربط الرقم، ويوضّح status السبب.

المفتاح مقصور على ذلك الرقم وحده. أنت لا تحمل أبدًا بيانات اعتماد واتساب أو WAHA — شاتكس يحتفظ بها على الخادم.

٠٣

كيف يعمل ضبط الإيقاع

بعد أن تضيف رسالة إلى قائمة الإرسال، وقبل إرسالها، ينفّذ شاتكس هذا بالترتيب:

1. ١. إشعار القراءة — فقط إذا كانت في المحادثة رسائل واردة غير مقروءة فعلًا. المحادثة التي قرأ فيها الطرف الآخر كل شيء لا تحصل على إشعار، لأنه لا يوجد ما يُحدَّد.
2. ٢. وقفة قصيرة قبل الكتابة — 400–1200 مللي ثانية.
3. ٣. الكتابة — طول النص ÷ 11 حرفًا في الثانية، مع تغيّر عشوائي، محصورًا بين 900 و18000 مللي ثانية. المدد الطويلة تُجدَّد، لأن واتساب يترك المؤشر ينقطع بعد نحو ٢٥ ثانية.
4. ٤. الإرسال، ثم فاصل قبل الرسالة التالية في تلك المحادثة — 1000 مللي ثانية ترتفع نحو 15000 مللي ثانية كلما زاد ما ينتظر في تلك المحادثة.

الرسائل إلى المحادثة نفسها مرتّبة ترتيبًا صارمًا، والمحادثات المختلفة تعمل بالتوازي. وكل فاصل يتغيّر عشوائيًا مع كل إرسال، فلا تأخذ رسالتان متطابقتان الوقت نفسه أبدًا. وكل ذلك قابل للتعديل لكل رقم تحت سلوك الإرسال.

٠٤

الإرسال

POST/messages/text

curl -X POST https://chatex.store/api/v1/INSTANCE_ID/messages/text \
  -H "Authorization: Bearer ctx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "201234567890@c.us",
    "text": "Thanks for getting in touch — I can help with that.",
    "replyTo": null,
    "priority": 5
  }'

chatId هو رقم المستقبِل متبوعًا بـ @c.us، أو @g.us للمجموعات. priority من 1 إلى 9، والأقل يُرسل أولًا.

202 Accepted

{
  "accepted": true,
  "messages": [
    { "id": "01M1N…", "chatId": "201234567890@c.us", "status": "queued", … }
  ],
  "quota": { "sent_today": 12, "limit": 100, "remaining": 88 }
}

إذا كان التقسيم مفعّلًا لهذا الرقم وكان النص طويلًا، تعود إليك عدة رسائل — واحدة لكل جزء، لكل منها إيقاعها الخاص، وكل منها تُحسب من حصتك.

٠٥

الوسائط

ارفع الملف مرة واحدة، ثم أرسله بالمعرّف.

# 1. upload  ->  201 { "id": "01M1N…", "mime": "image/png", … }
curl -X POST https://chatex.store/api/v1/INSTANCE_ID/media \
  -H "Authorization: Bearer ctx_your_token_here" \
  -F "file=@receipt.png"

# 2. send it
curl -X POST https://chatex.store/api/v1/INSTANCE_ID/messages/image \
  -H "Authorization: Bearer ctx_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": "201234567890@c.us", "mediaId": "01M1N…", "caption": "Here it is" }'

استخدم /messages/file لإرسال المستندات. الحد الأقصى 64 ميغابايت. ومع الوسائط تُحسب مدة الكتابة من التعليق لا من نص الرسالة.

٠٦

قراءة الحالة

GET /messages/{id}          # one message plus its full event timeline
GET /messages?status=sent   # filter: status, chatId, since, perPage
GET /usage                  # which number this token opens, plus tier and limits

تمرّ الرسالة بالحالات التالية:

queued → waiting → typing → sending → sent → delivered → read

مع failed, cancelled و revoked كحالات نهائية. held هو التوقف الوحيد الذي ليس حالة نهائية — يعني أن الحصة اليومية أو حد الخطة أوقف الرسالة، وهي تستأنف من تلقاء نفسها بمجرد زوال السبب.

GET /messages/{id} يُرجع أيضًا سجل الأحداث: متى أُرسل إشعار القراءة، وكم استمرت الكتابة، ومتى أُرسلت الرسالة ومتى تأكّد وصولها.

٠٧

الإلغاء والحذف

لأن الرسائل تخرج بإيقاع، فالرسالة المنتظرة في قائمة الإرسال قابلة للسحب فعلًا. وهذه ثلاثة أشياء مختلفة، وأسماؤها تدل عليها:

٠٨

الـ Webhooks

يستقبل شاتكس الأحداث من واتساب نفسه ليتتبّع التسليم وحالة عدم القراءة. أما تمريرها إلى endpoint خاص بك فغير متاح بعد — استعلم دوريًا من GET /messages مع since في الوقت الحالي، أو راقب رسالة واحدة بمعرّفها.

٠٩

الأخطاء

أخطاء الحصة والخطة تحمل معها الأرقام، لتتراجع بدقة بدل التخمين: sent_today, queued, limit, remaining.

429 Too Many Requests

{
  "error": "quota_exhausted",
  "message": "You have used your daily message allowance. …",
  "sent_today": 97,
  "queued": 2,
  "limit": 100,
  "remaining": 1
}

قيمة remaining هي ما يمكن إضافته إلى القائمة اليوم: الحد، مطروحًا منه ما أُرسل وما ينتظر في القائمة. والطلب الأكبر من ذلك يُرفض حتى لو كانت القيمة أكبر من صفر، فأرسل أقل بدل الانتظار.

١٠

الحدود

تسمح خطة Free بـ 10 رسالة يوميًا و 1 رقم. تتجدّد الحصة اليومية عند منتصف الليل بتوقيتك المحلي.

يقبل الـ API حتى 300 طلب في الدقيقة لكل رقم، لكن منظّم الإيقاع هو الحد الحقيقي — فهو لن يرسل أسرع مما تسمح به إعدادات التوقيت مهما أضفت إلى القائمة بسرعة. وإضافة أكثر من حصتك اليومية المتبقية تُرفض من البداية، بدل قبولها ثم تركها عالقة بلا إرسال.