تخطَّ إلى المحتوى

الأدوات

يسجل الخادم 16 أداة. كل أداة تستدعي دالة واحدة من الحزمة بمفتاح API الخاص بالخادم، فنطاقات المفتاح تحدد الأدوات التي تعمل. الأداة التي لا يسمح بها المفتاح تعيد إلى المساعد SMSFabric error 403 (forbidden) بدل أن تفشل بصمت.

ترد كل أداة بملخص من سطر واحد للمساعد، يليه رد JSON الكامل. وتعود الأخطاء كخطأ أداة يحمل حالة HTTP وcode وdetail وأي أخطاء في الحقول، ليشرحها المساعد أو يصحح الطلب.

الأداة النطاق الوسم
send_sms messages:send مدمرة (ترسل)
list_messages messages:read قراءة فقط
get_message messages:read قراءة فقط
send_verification verify:send ترسل
check_verification verify:check تستهلك محاولة
list_devices devices:read قراءة فقط
find_contacts contacts:read قراءة فقط
add_contact contacts:manage تكتب
list_campaigns campaigns:read قراءة فقط
get_campaign campaigns:read قراءة فقط
create_campaign campaigns:manage تكتب مسودة
estimate_campaign campaigns:read قراءة فقط
start_campaign campaigns:manage وmessages:send مدمرة
pause_campaign campaigns:manage تكتب
resume_campaign campaigns:manage تكتب
cancel_campaign campaigns:manage مدمرة

أرقام الهواتف دائمًا بصيغة E.164: علامة + ثم رمز الدولة ثم الرقم، من 8 إلى 16 خانة إجمالًا (+201001234567).

ترسل رسائل

ترسل نصًا واحدًا إلى رقم واحد أو حتى 100 رقم عبر هواتف البوابة. الرقم الموجود في القائمة السوداء يعود بالحالة blocked. مع مفتاح sf_test_ لا يصل شيء إلى هاتف حقيقي.

الأداة موسومة بـ readOnlyHint: false وdestructiveHint: true وopenWorldHint: true: الرسالة المرسلة لا يمكن استرجاعها، لذلك تسألك العملاء التي تحترم الوسوم قبل كل استدعاء. ويطلب وصفها من المساعد أن ينشئ قيمة idempotencyKey واحدة لكل رسالة ينوي إرسالها، وأن يعيد استخدامها إذا استدعى send_sms مجددًا بعد تجاوز مهلة أو خطأ، فتعيد SMSFabric الرسائل الأصلية بدل الإرسال مرة ثانية.

المدخل النوع مطلوب القيود
to string أو string[] نعم رقم بصيغة E.164، أو قائمة من 1 إلى 100 رقم
body string نعم من 1 إلى 1,600 حرف
deviceId string لا الإرسال من هذا الهاتف (dev_…)
simId string لا الإرسال من هذه الشريحة (sim_…)
poolId string لا الإرسال عبر هذه المجموعة (pool_…)
idempotencyKey string لا من 1 إلى 255 حرفًا، فريدة لكل إرسال مقصود. أعد استخدامها عند إعادة محاولة الإرسال نفسه. من دونها لا تحمي إلا المحاولات التلقائية داخل العميل

تعيد سطرًا لكل رسالة (msg_… → +201001234567: queued) والرسائل بصيغة JSON.

مثال على الطلب: «أرسل إلى +201001234567: طاولتك لأربعة أشخاص جاهزة الساعة 8 مساء.»

تعرض أحدث الرسائل، الأحدث أولًا.

المدخل النوع مطلوب القيود
direction enum لا outbound أو inbound
status enum لا queued وrouted وsending وsent وdelivered وfailed وblocked وreceived
q string لا أرقام من رقم هاتف: من 3 إلى 15، مع + اختيارية في البداية. تطابق أي جزء من to أو from، فالقيمة 4567 تجد الأرقام المنتهية بـ 4567. لا تقبل الأسماء؛ استخدم find_contacts لها
limit integer لا من 1 إلى 200. الافتراضي 20
cursor string لا قيمة nextCursor من الاستدعاء السابق

تعيد سطرًا لكل رسالة (الوقت والاتجاه والرقم والحالة وأول 80 حرفًا) والصفحة بصيغة JSON، مع nextCursor إذا وجد المزيد.

مثال على الطلب: «اعرض لي الرسائل التي فشلت اليوم.»

تعيد رسالة واحدة مع سجل تسليمها.

المدخل النوع مطلوب القيود
id string نعم معرف رسالة: msg_ تليها حروف لاتينية صغيرة وأرقام

تعيد الحالة وسلسلة الأحداث (queued → routed → sent → delivered)، ثم الرسالة بصيغة JSON.

مثال على الطلب: «هل سلّمت الرسالة msg_q8v2k4n6p1r3t5w7y9z0b2c4؟»

ترسل رسائل

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

المدخل النوع مطلوب القيود
to string نعم بصيغة E.164
locale enum لا en أو ar. الافتراضي en
codeLength integer لا من 4 إلى 10 أرقام. الافتراضي 6
ttlSeconds integer لا من 60 إلى 1,800. الافتراضي 600

تعيد معرف التحقق (ver_…) والرقم مخفيًا جزئيًا وحالته وموعد انتهائه.

مثال على الطلب: «أرسل رمز تحقق بالعربية إلى +201001234567.»

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

المدخل النوع مطلوب القيود
id string نعم معرف ver_… من send_verification
code string نعم من 4 إلى 10 أرقام

تعيد approved (تم التحقق من الرقم)، أو pending مع المحاولات المتبقية (رمز خاطئ)، أو denied (خمسة رموز خاطئة)، أو expired.

مثال على الطلب: «تقول إن الرمز هو 482913.»

تعرض هواتف البوابة. لا تأخذ أي مدخلات.

تعيد سطرًا لكل هاتف (المعرف والاسم وonline أو offline أو disabled والبطارية وعدد الشرائح) والهواتف بصيغة JSON مع الإشارة والشبكة وتفاصيل الشرائح.

مثال على الطلب: «هل كل هواتف البوابة متصلة؟ أيها بطاريته أقل من 20%؟»

تبحث في دفتر العناوين.

المدخل النوع مطلوب القيود
q string لا حتى 120 حرفًا. اسم أو بريد (احتواء)، أو رقم كامل بصيغة E.164، أو آخر 4 أرقام منه
tag string لا حتى 40 حرفًا
groupId string لا grp_ تليها حروف لاتينية صغيرة وأرقام
optedOut boolean لا true: الملغى اشتراكهم فقط؛ false: من يمكن مراسلتهم فقط
limit integer لا من 1 إلى 200. الافتراضي 20
cursor string لا قيمة nextCursor من الاستدعاء السابق

تعيد سطرًا لكل جهة اتصال (المعرف والرقم والاسم والوسوم و[opted out]) والصفحة بصيغة JSON.

مثال على الطلب: «ابحث عن جهة الاتصال التي ينتهي رقمها بـ 4567.»

تضيف جهة اتصال، واحدة لكل رقم. الرقم الموجود مسبقًا يعيد 409 contact_exists.

المدخل النوع مطلوب القيود
phone string نعم بصيغة E.164
firstName string لا حتى 120 حرفًا
lastName string لا حتى 120 حرفًا
email string لا بريد صالح، حتى 254 حرفًا
tags string[] لا حتى 20 وسمًا، كل منها حتى 40 حرفًا
consentSource enum لا مصدر موافقة الشخص على استقبال الرسائل: web_form أو import أو api أو in_person أو paper أو sms_keyword (أرسل كلمة مثل START) أو other

تعيد معرف جهة الاتصال الجديدة ورقمها، وجهة الاتصال بصيغة JSON.

مثال على الطلب: «أضف سارة عادل، +201001234568، بالوسم vip. سجلت عبر موقعنا.»

معرفات الحملات cmp_ تليها حروف لاتينية صغيرة وأرقام. تنتقل الحملة بين draft ← running ⇄ paused ← completed، أو تنتهي canceled.

تعرض الحملات، الأحدث أولًا، مع التقدم.

المدخل النوع مطلوب القيود
status enum لا draft وscheduled وrunning وpaused وcompleted وcanceled
limit integer لا من 1 إلى 200. الافتراضي 20
cursor string لا قيمة nextCursor من الاستدعاء السابق

تعيد سطر تقدم لكل حملة: المعرف والاسم والحالة والمرسل من إجمالي المستلمين والمسلّم والفاشل والمتخطى والمعلق والموعد المتوقع للانتهاء.

مثال على الطلب: «أي الحملات تعمل الآن؟»

حملة واحدة مع تقدمها المباشر، أو تقريرها.

المدخل النوع مطلوب القيود
id string نعم cmp_…
report boolean لا true تضيف المتخطين حسب السبب والإخفاقات حسب رمز الخطأ والأعداد لكل هاتف

تعيد سطر التقدم، ومع report تفصيل المتخطين والإخفاقات، ثم JSON.

مثال على الطلب: «كيف كان أداء حملة عروض نوفمبر؟ ولماذا تخطت الحملة بعض الأشخاص؟»

تنشئ مسودة. لا يرسل شيء حتى start_campaign. الجمهور هو جهات الاتصال في أي من المجموعات أو التي تحمل أيًا من الوسوم. يمكن أن يستخدم النص {{first_name}} و{{last_name}} و{{custom.<key>}} مع قيم بديلة مثل {{first_name|there}}؛ ويطلب الوصف من المساعد إضافة عبارة إلغاء اشتراك مثل “Reply STOP to opt out”.

المدخل النوع مطلوب القيود
name string نعم من 1 إلى 120 حرفًا
body string لا من 1 إلى 1,600 حرف. أعط واحدًا فقط من body وtemplateId
templateId string لا tpl_ تليها حروف لاتينية صغيرة وأرقام. أعط واحدًا فقط من body وtemplateId
groupIds string[] لا حتى 20 معرف grp_…
tags string[] لا حتى 20 وسمًا، كل منها حتى 40 حرفًا
poolId string لا الإرسال عبر هذه المجموعة
ratePerMinute integer لا من 1 إلى 6,000 عبر كل الهواتف. الافتراضي 120
hourlyCap integer لا من 1 إلى 360,000 مستلم في الساعة حسب المنطقة الزمنية للحملة
dailyCap integer لا من 1 إلى 8,640,000 مستلم في اليوم، ولا يقل عن hourlyCap
quietHoursStart string لا HH:MM (نظام 24 ساعة) بالتوقيت المحلي لكل مستلم، مثل 21:00
quietHoursEnd string لا HH:MM، مثل 09:00
scheduledAt string لا تاريخ ووقت بصيغة ISO 8601 مع فرق التوقيت، مثل 2026-12-01T09:00:00+02:00. عندها تجدول start_campaign الحملة لذلك الوقت بدل بدئها فورًا

أعط quietHoursStart وquietHoursEnd معًا أو لا تعطهما. تعيد الأداة خطأ دون استدعاء الواجهة البرمجية إذا أعطيت واحدة منهما فقط، أو إذا أعطيت body وtemplateId معًا أو لم تعط أيًا منهما.

تعيد معرف المسودة مع تذكير بالتقدير قبل البدء، والحملة بصيغة JSON.

مثال على الطلب: «جهّز حملة باسم عرض نهاية الأسبوع لأصحاب الوسم vip: مرحبًا {{first_name|there}}، خصم 20% هذا الأسبوع. Reply STOP to opt out. لا رسائل بين 9 مساء و9 صباحًا.»

ما ستفعله حملة في حالة المسودة أو الجدولة قبل أن تبدأ: المستلمون بعد استبعاد الملغى اشتراكهم والقائمة السوداء، وإجمالي الأجزاء، والمعدل الفعلي حسب ضبط المعدل وسعة الهواتف، وعدد من ينتظرون انتهاء ساعات الهدوء، والمدة، وأي تحذيرات.

المدخل النوع مطلوب القيود
id string نعم cmp_…

تعيد ملخصًا مثل “1,240 recipients (12 opted out, 3 blacklisted skipped), 1,240 segments, about 11 min at 120/min” والتقدير بصيغة JSON.

مثال على الطلب: «كم ستستغرق هذه الحملة، وكم شخصًا ستصل إليه؟»

مدمرة

تبدأ المسودة الآن، أو في موعدها المجدول. مع مفتاح حقيقي ترسل رسائل حقيقية إلى كل مستلم. الأداة موسومة بـ destructiveHint: true، ويطلب وصفها من المساعد أن يؤكد معك وأن يشغّل estimate_campaign أولًا.

المدخل النوع مطلوب القيود
id string نعم cmp_…

تعيد سطر التقدم بالحالة running (أو scheduled).

مثال على الطلب: «التقدير مناسب. ابدأ حملة عرض نهاية الأسبوع.»

توقف حملة جارية مؤقتًا. الرسائل التي سلّمت إلى هاتف بالفعل تخرج كالمعتاد، ولا يؤخذ مستلم جديد حتى الاستئناف.

المدخل النوع مطلوب القيود
id string نعم cmp_…

تعيد سطر التقدم بالحالة paused.

مثال على الطلب: «أوقف حملة عرض نهاية الأسبوع مؤقتًا، في النص خطأ.»

تستأنف حملة موقوفة مؤقتًا. يبدأ ضبط المعدل من الآن، فلا يحدث اندفاع مفاجئ.

المدخل النوع مطلوب القيود
id string نعم cmp_…

تعيد سطر التقدم بالحالة running.

مثال على الطلب: «استأنف الحملة.»

مدمرة

تلغي حملة مجدولة أو جارية أو موقوفة نهائيًا. يتخطى النظام المستلمين المعلقين، وتحظر الرسائل التي لم يستلمها أي هاتف بعد. لا يمكن التراجع عن ذلك. الأداة موسومة بـ destructiveHint: true.

المدخل النوع مطلوب القيود
id string نعم cmp_…

تعيد سطر التقدم بالحالة canceled.

مثال على الطلب: «ألغ حملة عرض نهاية الأسبوع نهائيًا.»