الرسائل الجماعية

الرسالة الجماعية ترسل رسالة واحدة، مثل عرض أو خبر، إلى كثيرين ممن وافقوا على التواصل. أي من راسلوا الرقم. يتلقى كل شخص رسالته الخاصة، واحدة تلو الأخرى، كما يرسلها الإنسان. وتتوقف الرسالة الجماعية من تلقاء نفسها إن كان الرقم في خطر. لهذا استخدامها آمن، بعكس تكرار POST /v1/messages على قائمة.

من يتلقاها#

فقط من وافقوا على التواصل معك على ذلك الرقم:

• recent: كل من راسله خلال آخر days (30 افتراضيًا، وهي أيضًا أقصى مدة تُحفظ فيها الرسائل)، الأقدم أولًا. وإرسال رمز للتحقق من رقم هاتف لا يُحتسب مراسلة.
• label: المحادثات التي عليها أحد تصنيفات المحادثات لديك (label_id)، كما يضعها فريقك في صفحة «المحادثات» في لوحة التحكم.
• phones: قائمة recipients الخاصة بك، مقتصرة على من راسلوا الرقم منها. ومع include_saved_contacts: true، يمكن أن تبقى فيها أيضًا جهات الاتصال المحفوظة على الهاتف التي لم تراسل من قبل. يُتحقق من كل جهة على الهاتف حين يأتي دورها. وتُحسب محادثات جديدة، بكل حدود المحادثات الجديدة. ويجب أن يحتوي النص على حقل غير {phone}. وتُستبعد جهة الاتصال المحفوظة التي ليس لها اسم ولا قيمة لهذا الحقل (nothing_personal).

ولا يُراسَل أحد غيرهم أبدًا:

• لم يراسل من قبل: الهاتف الذي لم يراسل الرقم من قبل يُستبعد، ولا يُبحث عنه في واتساب أبدًا.
• طلبوا التوقف: من كتب «STOP»، قبل الرسالة الجماعية أو أثناءها، يُستبعد. ويبقى خارج كل رسالة جماعية، حتى بعد أن يراسلك من جديد، إلى أن يرسل «START» (أو «subscribe» أو «اشترك» أو «ابدأ»).
• المجموعات والقنوات: لا تُرسل الرسالة الجماعية إليها أبدًا.
• أرقامك أنت: أبدًا.

التقليل. في صفحة «رسالة جماعية جديدة» في لوحة التحكم، يمكنك قصر أيٍّ من هذه على المحادثات التي عليها تصنيف. ويمكنك قصرها أيضًا على من يحمل حقل جهة الاتصال لديهم قيمة معينة (مثلًا: المدينة هي الجيزة). والتقليل يستبعد أشخاصًا فقط: فكل من يبقى كانت الرسالة الجماعية ستصله على أي حال. وتذكر الرسالة الجماعية بعدها ما اقتصرت عليه في narrowed_to، وتعدّ من استبعدتهم في not_matching. الرسالة الجماعية تستوعب 5,000 شخص كحد أقصى، والتقليل يختار من بينهم. فإن زاد العدد، يُطبَّق التقليل على أول 5,000 فقط (الأقدم مراسلةً، أو الأوائل في قائمتك). والـ API لا يدعم التقليل بعد.

ويذكر الرد عدد من استُبعدوا، والسبب، ضمن left_out: never_wrote وopted_out وnot_on_whatsapp وinvalid وduplicate وown_number وno_phone وover_limit. الرسالة الجماعية تستوعب 5,000 شخص كحد أقصى.

ما تقوله#

text حتى 1,000 حرف، مع هذه الحقول:

أضف بعد | كلمات تُستخدم حين تكون القيمة فارغة: Hi {name|there}. وحقل جهة الاتصال الذي لا يحمل شيئًا عن شخص يُعد فارغًا أيضًا، تمامًا كالاسم الناقص. وتنتهي كل رسالة بسطر إلغاء الاشتراك باللغة التي تختارها في language:

• en: "Reply STOP to stop these messages."
• ar: "أرسل «توقف» لإيقاف هذه الرسائل."

مع سطر إلغاء الاشتراك، الحد الأقصى لكل رسالة 600 حرف. ولا يمكن أن تحمل الرسالة الجماعية رابط http:// (استخدم https://)، ولا أن تكون رابطًا فقط.

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

يمكن إرفاق صورة أو فيديو أو مستند واحد معها في media (url، أو data بصيغة base64، مع mimetype وfilename اختياري)، حتى 16 ميجابايت، والنص تعليق عليه. وإن أُرسل بـ data يُحتسب من ملفات اليوم بصيغة base64 للحساب. ولا يمكن إرسال رسالة صوتية، لأنه لا مكان فيها لسطر إلغاء الاشتراك.

كيف تُرسل#

curl https://threadwire.net/api/v1/broadcasts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "YOUR_INSTANCE_ID", "audience": "recent", "days": 14,
       "text": "Hi {name}, our autumn menu starts today. Show this message for a free coffee."}'

يرد بـ 201 مع الرسالة الجماعية بحالة running (أو scheduled مع start_at). ثم:

• واحدة تلو الأخرى. لا تُنشأ الرسالة التالية إلا بعد إرسال السابقة، وبعد interval_seconds منها. الفاصل 60 افتراضيًا، و600 كحد أقصى، ولا يقل عن 20 أبدًا. ويتغير كل فاصل بزيادة تصل إلى نصفه، حتى لا يبدو منتظمًا كالآلة.
• في النهار فقط. لا يُرسل شيء في ساعات هدوء الرقم (من 22:00 إلى 08:00 بتوقيته افتراضيًا).
• حد يومي. ترسل per_day رسالة يوميًا كحد أقصى (200 افتراضيًا، و1,000 كحد أقصى). وللرقم الجديد حده اليومي الخاص أيضًا أثناء الإحماء. ويُستكمل الباقي في اليوم التالي، فالقائمة الطويلة تحتاج عدة أيام.
• كل قواعد الإرسال العادي تبقى سارية. كل رسالة هي رسالة عادية، تُرسل بكل القواعد الواردة في كيف يحمي الإرسال رقمك. وترسل أحداث message.status المعتادة، مع origin قيمته broadcast.
• رسالة جماعية واحدة في كل مرة لكل رقم. الثانية تتلقى 409 حتى تنتهي الأولى أو تتوقف مؤقتًا.
• باقتك. كل رسالة تُحتسب من رسائل باقتك كأي رسالة أخرى.

تتوقف من تلقاء نفسها#

تتوقف الرسالة الجماعية مؤقتًا من تلقاء نفسها، مع السبب في reason (code وtext)، عندما:

يصلك حدث broadcast.paused، ويتلقى فريقك رسالة بريد إلكتروني. والرسالة التي كانت في طريقها تُؤجَّل: تفشل مع error يذكر ذلك، وتُرسل من جديد عند الاستئناف.

الاستئناف: POST /v1/broadcasts/{id}/resume يعمل فقط بعد زوال السبب. وحتى ذلك الحين يرد بـ 409 مع ما يمنعها بعد. وبعد opt_outs أو failures تنتظر يومًا، ويبدأ العد من جديد. وفي الأثناء لا تبدأ أي رسالة جماعية أخرى من ذلك الرقم، حتى لو ألغيت هذه. راجع أولًا من تُرسل إليهم وما تقوله.

تابعها وتحكّم فيها#

• GET /v1/broadcasts/{id}: status يكون draft أو scheduled أو running أو paused أو completed أو cancelled. ويحتوي progress على recipients وpending وskipped (حسب السبب: opted_out وnot_saved وcancelled، وno_longer_known لمن حُذفت رسائله بعد 30 يومًا، قبل دوره: راسله حين يكتب من جديد). ويعدّ أيضًا الرسائل queued وsent وdelivered وread (وكل منها يعدّ الرسائل التي بلغت تلك المرحلة على الأقل)، وfailed وreplied وopted_out.
• GET /v1/broadcasts يعرضها، الأحدث أولًا. صفِّ النتائج بـ instance_id وstatus.
• POST /v1/broadcasts/{id}/pause يوقفها مؤقتًا.
• DELETE /v1/broadcasts/{id} يلغيها. لا يتلقاها أحد آخر، والرسالة التي ما زالت تنتظر تُلغى أيضًا.
• broadcast.completed يصل حين يتلقى الجميع رسائلهم.

لا يحمل أيٌّ من الحدثين النص ولا رقم أي شخص. أرسل ترويسة Idempotency-Key مع طلب البدء، حتى لا تبدأ إعادة المحاولة رسالة جماعية ثانية أبدًا. فهي ترد بـ 200 مع الرسالة الأولى والترويسة Idempotent-Replayed: true، أيًّا كان محتوى إعادة المحاولة. والمفتاح خاص برقمه، ويُقارن حرفيًا (حالة الأحرف تُحتسب). تُحذف الرسائل الجماعية بعد 30 يومًا من انتهائها، وكذلك رسائلها.