الأدوات
يسجل الخادم 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).
الرسائل
Section titled “الرسائل”send_sms
Section titled “send_sms”ترسل نصًا واحدًا إلى رقم واحد أو حتى 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 مساء.»
list_messages
Section titled “list_messages”تعرض أحدث الرسائل، الأحدث أولًا.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
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 إذا وجد المزيد.
مثال على الطلب: «اعرض لي الرسائل التي فشلت اليوم.»
get_message
Section titled “get_message”تعيد رسالة واحدة مع سجل تسليمها.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | معرف رسالة: msg_ تليها حروف لاتينية صغيرة وأرقام |
تعيد الحالة وسلسلة الأحداث (queued → routed → sent → delivered)، ثم الرسالة بصيغة JSON.
مثال على الطلب: «هل سلّمت الرسالة msg_q8v2k4n6p1r3t5w7y9z0b2c4؟»
التحقق
Section titled “التحقق”send_verification
Section titled “send_verification”ترسل رمزًا لمرة واحدة للتأكد من أن شخصًا يملك رقم هاتف. تولد SMSFabric الرمز ولا تعيده أبدًا؛ وعلى المساعد أن يطلب من الشخص قراءته. الإرسال الجديد إلى الرقم نفسه يستبدل الرمز المعلق. الحد ثلاثة رموز لكل رقم كل 10 دقائق، ويجب أن تكون الدولة مسموحًا بها في البوابة ضمن إعدادات التحقق.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
to |
string | نعم | بصيغة E.164 |
locale |
enum | لا | en أو ar. الافتراضي en |
codeLength |
integer | لا | من 4 إلى 10 أرقام. الافتراضي 6 |
ttlSeconds |
integer | لا | من 60 إلى 1,800. الافتراضي 600 |
تعيد معرف التحقق (ver_…) والرقم مخفيًا جزئيًا وحالته وموعد انتهائه.
مثال على الطلب: «أرسل رمز تحقق بالعربية إلى +201001234567.»
check_verification
Section titled “check_verification”تفحص الرمز الذي استلمه الشخص. كل استدعاء يستهلك واحدة من المحاولات الخمس، لذا يجب ألا يفحص المساعد إلا رمزًا أعطاه إياه الشخص.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | معرف ver_… من send_verification |
code |
string | نعم | من 4 إلى 10 أرقام |
تعيد approved (تم التحقق من الرقم)، أو pending مع المحاولات المتبقية (رمز خاطئ)، أو denied (خمسة رموز خاطئة)، أو expired.
مثال على الطلب: «تقول إن الرمز هو 482913.»
الهواتف
Section titled “الهواتف”list_devices
Section titled “list_devices”تعرض هواتف البوابة. لا تأخذ أي مدخلات.
تعيد سطرًا لكل هاتف (المعرف والاسم وonline أو offline أو disabled والبطارية وعدد الشرائح) والهواتف بصيغة JSON مع الإشارة والشبكة وتفاصيل الشرائح.
مثال على الطلب: «هل كل هواتف البوابة متصلة؟ أيها بطاريته أقل من 20%؟»
جهات الاتصال
Section titled “جهات الاتصال”find_contacts
Section titled “find_contacts”تبحث في دفتر العناوين.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
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.»
add_contact
Section titled “add_contact”تضيف جهة اتصال، واحدة لكل رقم. الرقم الموجود مسبقًا يعيد 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. سجلت عبر موقعنا.»
الحملات
Section titled “الحملات”معرفات الحملات cmp_ تليها حروف لاتينية صغيرة وأرقام. تنتقل الحملة بين draft ← running ⇄ paused ← completed، أو تنتهي canceled.
list_campaigns
Section titled “list_campaigns”تعرض الحملات، الأحدث أولًا، مع التقدم.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
status |
enum | لا | draft وscheduled وrunning وpaused وcompleted وcanceled |
limit |
integer | لا | من 1 إلى 200. الافتراضي 20 |
cursor |
string | لا | قيمة nextCursor من الاستدعاء السابق |
تعيد سطر تقدم لكل حملة: المعرف والاسم والحالة والمرسل من إجمالي المستلمين والمسلّم والفاشل والمتخطى والمعلق والموعد المتوقع للانتهاء.
مثال على الطلب: «أي الحملات تعمل الآن؟»
get_campaign
Section titled “get_campaign”حملة واحدة مع تقدمها المباشر، أو تقريرها.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
report |
boolean | لا | true تضيف المتخطين حسب السبب والإخفاقات حسب رمز الخطأ والأعداد لكل هاتف |
تعيد سطر التقدم، ومع report تفصيل المتخطين والإخفاقات، ثم JSON.
مثال على الطلب: «كيف كان أداء حملة عروض نوفمبر؟ ولماذا تخطت الحملة بعض الأشخاص؟»
create_campaign
Section titled “create_campaign”تنشئ مسودة. لا يرسل شيء حتى 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 صباحًا.»
estimate_campaign
Section titled “estimate_campaign”ما ستفعله حملة في حالة المسودة أو الجدولة قبل أن تبدأ: المستلمون بعد استبعاد الملغى اشتراكهم والقائمة السوداء، وإجمالي الأجزاء، والمعدل الفعلي حسب ضبط المعدل وسعة الهواتف، وعدد من ينتظرون انتهاء ساعات الهدوء، والمدة، وأي تحذيرات.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
تعيد ملخصًا مثل “1,240 recipients (12 opted out, 3 blacklisted skipped), 1,240 segments, about 11 min at 120/min” والتقدير بصيغة JSON.
مثال على الطلب: «كم ستستغرق هذه الحملة، وكم شخصًا ستصل إليه؟»
start_campaign
Section titled “start_campaign”تبدأ المسودة الآن، أو في موعدها المجدول. مع مفتاح حقيقي ترسل رسائل حقيقية إلى كل مستلم. الأداة موسومة بـ destructiveHint: true، ويطلب وصفها من المساعد أن يؤكد معك وأن يشغّل estimate_campaign أولًا.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
تعيد سطر التقدم بالحالة running (أو scheduled).
مثال على الطلب: «التقدير مناسب. ابدأ حملة عرض نهاية الأسبوع.»
pause_campaign
Section titled “pause_campaign”توقف حملة جارية مؤقتًا. الرسائل التي سلّمت إلى هاتف بالفعل تخرج كالمعتاد، ولا يؤخذ مستلم جديد حتى الاستئناف.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
تعيد سطر التقدم بالحالة paused.
مثال على الطلب: «أوقف حملة عرض نهاية الأسبوع مؤقتًا، في النص خطأ.»
resume_campaign
Section titled “resume_campaign”تستأنف حملة موقوفة مؤقتًا. يبدأ ضبط المعدل من الآن، فلا يحدث اندفاع مفاجئ.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
تعيد سطر التقدم بالحالة running.
مثال على الطلب: «استأنف الحملة.»
cancel_campaign
Section titled “cancel_campaign”تلغي حملة مجدولة أو جارية أو موقوفة نهائيًا. يتخطى النظام المستلمين المعلقين، وتحظر الرسائل التي لم يستلمها أي هاتف بعد. لا يمكن التراجع عن ذلك. الأداة موسومة بـ destructiveHint: true.
| المدخل | النوع | مطلوب | القيود |
|---|---|---|---|
id |
string | نعم | cmp_… |
تعيد سطر التقدم بالحالة canceled.
مثال على الطلب: «ألغ حملة عرض نهاية الأسبوع نهائيًا.»