ربط رقم

الرقم هو رقم واتساب واحد مربوط بـ Threadwire، بالطريقة نفسها التي يُربط بها WhatsApp Web بالهاتف. يمكنك فعل كل هذا من لوحة التحكم أيضًا؛ وهذه الصفحة لفعله عبر الـ API.

أضف رقمًا واربطه#

1. أضفه: POST /v1/instances مع name (وإن شئت، external_ref خاص بك). في الرد id الخاص به: وهو instance_id الذي يستخدمه كل طلب آخر.
2. اعرض رمز QR: GET /v1/instances/{id}/qr يرد بـ JSON فيه الصورة على هيئة data URL: {"data": {"image": "data:image/png;base64,iVBOR…"}}. ضع data.image في <img src> كما هي. يمسحه صاحب الهاتف من واتساب ← الإعدادات ← الأجهزة المرتبطة. الرمز يتغيّر، فاجلبه من جديد كل بضع ثوانٍ. وإن انتهت الرموز قبل أن يمسح أحد واحدًا منها، فجلب الرمز يبدأ جلسة جديدة.
3. انتظر working: تصبح status للرقم working في GET /v1/instances/{id}، ويخبرك بذلك ويب هوك instance.status.

رمز بدلًا من رمز QR: POST /v1/instances/{id}/pairing-code مع رقم الهاتف في phone. ويكتب الشخص الرمز في واتساب ← الأجهزة المرتبطة ← ربط جهاز ← الربط برقم الهاتف بدلًا من ذلك. بحد أقصى 5 رموز في الساعة لكل رقم، تُحتسب مع «الربط برقم الهاتف بدلًا من ذلك» في لوحة التحكم (ثم 429 مع Retry-After).

ما تعنيه الردود أثناء الربط:

• GET …/qr يرد بـ 409 ما دام الرقم في طور التشغيل (حاول بعد لحظة) وبعد أن يُربط.
• POST /v1/instances يرد بـ 409 مع Retry-After ما دام رقم آخر لك قيد الإضافة (تُضاف الأرقام واحدًا تلو الآخر). ونادرًا يرد بـ 503 مع Retry-After ونحن نعمل على إتاحة مساحة لأرقام أكثر. حاول مرة أخرى بعد الانتظار.

status الرقم تكون starting أو scan_qr أو working أو failed أو stopped.

لكل رقم واتساب رقم واحد في Threadwire. رقم واتساب المربوط برقم آخر لا يُربط مرة ثانية: يُسجَّل خروج الربط الجديد، ويوضح link_refused على الرقم السبب وما عليك فعله. لنقل رقم واتساب، اربطه على الرقم الذي هو عليه، أو أزل ذلك الرقم أولًا. بهذا تبقى الحدود اليومية والإحماء خاصة بكل رقم واتساب. ما دام link_refused قائمًا، يرد GET …/qr وطلب رمز الربط بـ 409 مع السبب نفسه؛ وPOST /v1/instances/{id}/logout يمسحه ويبدأ ربطًا جديدًا. وفي لوحة التحكم، تعرض نافذة الربط السبب وزر «بدء ربط جديد» الذي يعيد رمز QR.

حافظ على تشغيله#

• POST /v1/instances/{id}/restart يعيد اتصال رقم يبدو متوقفًا. ويبقى مربوطًا.
• POST /v1/instances/{id}/stop يوقفه عن العمل عمدًا (stopped: true)؛ وطلبات الإرسال ترد بـ 409 حتى تنفّذ start من جديد.
• POST /v1/instances/{id}/start يعيده إلى العمل.
• POST /v1/instances/{id}/logout يفك ربط الهاتف، كإزالة جهاز مرتبط من واتساب؛ وينتظر الرقم رمز QR جديدًا، من الهاتف نفسه أو من غيره. يبقى معرّفه وإعداداته ومفاتيحه ورسائله؛ والربط الجديد يبدأ الإحماء من جديد.
• DELETE /v1/instances/{id} يزيله نهائيًا.

لحماية الرقم، ترد طلبات إعادة التشغيل والإيقاف وفك الربط بـ 409 ما دام واتساب يقيّده. والأربعة معًا محدودة بـ 5 في الساعة لكل رقم (429 مع Retry-After). DELETE يرد بـ 409 فقط ما دام رقم مربوط تحت تقييد مؤقت من واتساب، أو خلال الساعة التي تلي رفض واتساب لرسالة؛ ويذكر الرد متى يمكن إزالته. الرقم غير المربوط أو المنقطع أو المتوقف يمكن إزالته دائمًا.

الإعدادات#

PATCH /v1/instances/{id} يغيّر name وreject_calls وprotection_settings (راجع كيف يحمي الإرسال رقمك). أرسل ما يتغيّر فقط.

GET /v1/instances/{id} يعرض أيضًا chat_link، وهو رابط wa.me يفتح محادثة معه، وprotection: موقف الرقم اليوم من حدوده ومن عداد الأمان.

ملف واتساب الشخصي للرقم#

GET /v1/instances/{id}/profile يعطي name وpicture_url (واتساب لا يعيد نص «النبذة»). PATCH يغيّر name (حتى 25 حرفًا) أو about (حتى 139) أو picture (صورة JPEG أو PNG بحجم 2 ميجابايت على الأكثر، عبر url أو base64 في data؛ وnull تزيلها). «ملف واتساب الشخصي» في صفحة الرقم بلوحة التحكم يفعل الشيء نفسه. بحد أقصى 10 تغييرات في اليوم لكل رقم.

يبلّغ الناس أكثر عن الأرقام التي بلا اسم وصورة، فاضبطهما قبل أن تراسل أي شخص جديد.

المكالمات#

مكالمات واتساب إلى أرقامك تصل كويب هوك call.received. اضبط reject_calls: true (عبر PATCH /v1/instances/{id}، أو من «الإعدادات» في صفحة الرقم) لرفض كل مكالمة فورًا. أو ارفض مكالمة واحدة بـ POST /v1/instances/{id}/calls/reject مع id المكالمة (في call_id) وchat_id (في from). للمكالمات الفردية فقط.

مفاتيح API#

أنشئ المفاتيح من لوحة التحكم في للمطورين ← مفاتيح API (للمسؤولين فقط)، مفتاحًا لكل نظام يستدعي الـ API، ليمكن إبطال كل واحد منها وحده.

• الصلاحية: واحدة من ثلاث.
  • وصول كامل يفعل كل شيء.
  • إرسال وقراءة يرسل، ويقرأ كل شيء. يشمل ذلك الرسائل (ومعها التعديل والحذف والتفاعلات وعلامات القراءة)، والرسائل الجماعية، ورموز OTP، والحالات، والتصنيفات، والتحقق من الأرقام، ورفض مكالمة، وأرشفة محادثة، واسم المجموعة وإعداداتها ورابط دعوتها. لا يمكنه إدارة رقم: إضافته أو إزالته، أو ربطه (رمز QR أو رمز الربط)، أو تغيير إعداداته. ولا يمكنه إعادة تشغيله أو إيقافه أو تشغيله أو فك ربطه، ولا تغيير ملف واتساب الشخصي أو وكيل الذكاء الاصطناعي الخاص به. ولا يمكنه إنشاء مجموعة أو الانضمام إليها أو مغادرتها، ولا إضافة أشخاص إلى مجموعة أو إزالتهم، ولا إنشاء قناة أو حذفها.
  • قراءة فقط يقرأ الأرقام والرسائل والمحادثات والأحداث والمجموعات والقنوات والحالات والتصنيفات والرسائل الجماعية ورموز OTP. لا يرسل شيئًا ولا يغيّر شيئًا. تفاصيل جهة اتصال واحدة، ورابط دعوة مجموعة، يحتاجان مفتاحًا يمكنه الإرسال.
• رقم واحد: يمكن إنشاء مفتاح لرقم واحد (من صفحة ذلك الرقم، أو من «لـ» عند إنشاء مفتاح). يصل فقط إلى رسائل ذلك الرقم ومحادثاته ومجموعاته وأحداثه وإعداداته، كأن حسابك ليس فيه غيره. ولا يمكنه إضافة أرقام أو إزالتها (403)، ويتوقف عن العمل عند إزالة رقمه. أعطِ ذلك الرقم رابط ويب هوك خاصًا به أيضًا، فلا يصل النظام الذي وراءه إلا أحداثه. استخدم مفتاحًا لكل نظام يخدم رقمًا واحدًا، ومفتاح حساب للأنظمة التي تستخدم كل الأرقام.
• عناوين IP: يمكن قفل المفتاح على عناوين خوادمك أو نطاقاتها، فالمفتاح المسرّب لا فائدة منه من أي مكان آخر.

الطلب الذي يتجاوز صلاحية المفتاح، أو يأتي من عنوان آخر، يرد بـ 403 مع السبب.

الباقات والحدود#

سجّل من /app/register لتحصل على تجربة مجانية لمدة 7 أيام؛ دون حاجة إلى بطاقة. قبل أن تنتهي، ادفع بالبطاقة من صفحة الفواتير والدفع حيث يتاح ذلك، أو بالتحويل ثم اضغط «دفعت» هناك. وإلا يتوقف الحساب مؤقتًا في اليوم التالي حتى تدفع. لا يُخصم أي مبلغ تلقائيًا.

• يمكن لكل حساب إجراء حتى 600 طلب في الدقيقة؛ وبعدها 429 Too Many Requests مع Retry-After.
• تحدد الباقة عدد الأرقام التي يمكنك ربطها (وبعده يرد POST /v1/instances بـ 403). وقد تحدد أيضًا حدود استخدام: الرسائل في اليوم، والأشخاص الذين تراسلهم في الشهر، وطلبات API في الشهر، وعمليات التحقق من الأرقام في اليوم. تعرض صفحة الفواتير والدفع ما في باقتك منها؛ وإن لم يكن فيها شيء، فلا يحدّك إلا حماية كل رقم. الرسائل المكتوبة على الهاتف لا تُحتسب أبدًا. عند تجاوز حد استخدام، يرد الـ API بـ 429 مع السبب وRetry-After.
• إذا كان حسابك موقوفًا، يرد كل طلب بـ 403 مع السبب.