--- title: "إرسال SMS عبر API: أمثلة بلغات Python وNode.js وPHP وcURL" description: "إرسال SMS عبر API بلغات Python وNode.js وPHP وcURL: إرسال فردي وجماعي، ودعم Unicode والعربية، وحساب الأجزاء، وwebhooks حالة التسليم ومعالجة الأخطاء." canonical: "https://omnichannels.ai/ar/blog/send-sms-api-examples/" language: "ar" updated: "2026-10-16" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "integration" primaryQuery: "send sms api python" keywords: ["إرسال SMS بلغة Python", "مثال SMS API بلغة Node.js", "SMS API بلغة PHP", "إرسال SMS عبر cURL", "SMS API Unicode عربي", "webhook تقرير تسليم SMS", "مثال إرسال رسائل SMS جماعية عبر API"] published: "2026-10-16" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 10 answer: "لإرسال رسالة SMS عبر واجهة OmniChannels.ai، أرسل طلب POST موثّقًا إلى https://api.broadnet.me/sms/sendSms بجسم JSON يحتوي senderId وdestinationNumber وmessage وmessageType. استخدم TEXT لنص GSM-7 وUNICODE للعربية أو الرموز التعبيرية. تعيد الاستجابة 200 معرّف الرسالة نصًا عاديًا، وتصل حالة التسليم النهائية لاحقًا إلى webhook الخاص بك." takeaways: ["يحتاج POST /sms/sendSms أربعة حقول: senderId وdestinationNumber وmessage وmessageType؛ وجسم الاستجابة هو معرّف الرسالة نصًا عاديًا لا JSON.", "اضبط messageType على UNICODE للعربية أو الرموز التعبيرية أو أي حرف خارج GSM-7؛ فحرف واحد من هذا النوع يجعل الرسالة كلها Unicode ويقصّر كل جزء.", "يحسب POST /sms/identify الأحرف والأجزاء قبل الإرسال، فتتوقع عدد الأجزاء التي تستهلكها الرسالة.", "التسليم غير متزامن: 200 تعني القبول، وتصل DELIVERED أو FAILED أو REJECTED لاحقًا إلى webhook.", "لا يوفر الـ API مفتاح idempotency، لذا سجّل كل إرسال قبل تنفيذه وافحص الحالة بعد انتهاء المهلة بدل إعادة الإرسال."] faq: - q: "كيف أرسل SMS بلغة Python؟" a: "استخدم مكتبة requests لإرسال JSON عبر POST إلى https://api.broadnet.me/sms/sendSms مع ترويسة Authorization: Bearer والحقول senderId وdestinationNumber وmessage وmessageType. اقرأ الرمز من متغير بيئة. جسم الاستجابة 200 هو معرّف الرسالة نصًا عاديًا، لذا استخدم r.text بدل r.json()." - q: "ما صيغة رقم الهاتف التي يتوقعها SMS API؟" a: "رمز الدولة مع الرقم الوطني، أرقام فقط، دون علامة زائد أو بادئة 00 أو مسافات أو صفر في البداية. فمثلًا 447700900123 صالح، أما +44 7700 900123 و07700900123 فلا. خزّن الأرقام بصيغة E.164 في قاعدة بياناتك وأزل علامة الزائد عند بناء الطلب." - q: "كيف أرسل SMS بالعربية عبر الـ API؟" a: "اضبط messageType على UNICODE وأرسل النص العربي في الحقل message بترميز UTF-8. تتسع رسائل Unicode لـ 70 حرفًا في الجزء الواحد و67 لكل جزء عند التقسيم، مقابل 160 و153 في GSM-7. اختبر على هواتف حقيقية، واستدعِ /sms/identify لترى عدد الأجزاء أولًا." - q: "كيف أحصل على تقارير التسليم؟" a: "تُدفع الحالات إلى عنوان webhook المضبوط على حسابك. تنتقل الرسائل عبر SUBMITTED وSENT إلى DELIVERED أو FAILED أو REJECTED. ينبغي أن يخزّن نقطة الاستقبال الحدث الخام ويردّ بـ 2xx بسرعة ويعالج بصورة غير متزامنة. وإذا فاتتك أحداث، يستطيع POST /sms/resendDlr إعادة دفع الإيصالات لنطاق تواريخ." - q: "كيف أرسل SMS إلى أرقام كثيرة دفعة واحدة؟" a: "استخدم POST /sms/sendbulk، وهو طلب multipart يتضمن ملف destinationNumberFile (بصيغة CSV أو TXT) ونص JSON باسم bulkRequest يضم senderId وmessage وmessageType. تذكر الاستجابة عدد الأرقام الصالحة وغير الصالحة والمكررة، وتعيد bulkSessionId يمكنك تخزينه مع حملتك." - q: "هل أحتاج إلى تسجيل اسم المرسل؟" a: "في دول كثيرة، نعم. بعضها يشترط اسم مرسل أبجديًا رقميًا معتمدًا، وبعضها معرّفات من الجهة التنظيمية أو القوالب، وتقبلها الواجهة في حقول اختيارية مثل peId وtemplateId. المتطلبات خاصة بكل دولة، فراجع صفحة اسم المرسل لوجهتك، ويستطيع فريقنا تولي التسجيل معك." sources: - title: "3GPP TS 23.040: التنفيذ التقني لخدمة الرسائل القصيرة (SMS)" url: "https://www.3gpp.org/dynareport?code=23040" - title: "ITU-T E.164: خطة الترقيم العامة الدولية للاتصالات" url: "https://www.itu.int/rec/T-REC-E.164" - title: "RFC 9110: دلالات HTTP" url: "https://www.rfc-editor.org/rfc/rfc9110" --- # إرسال SMS عبر API: أمثلة بلغات Python وNode.js وPHP وcURL Canonical: https://omnichannels.ai/ar/blog/send-sms-api-examples/ Language: ar Publisher: OmniChannels.ai by BroadNet Technologies هذا الدليل موجّه للمطورين الذين يحتاجون إلى إرسال SMS من تطبيق ويريدون شيفرة تعمل بلغات Python أو Node.js أو PHP أو cURL. يغطي الإرسال الفردي، وUnicode والعربية، وحساب الأجزاء، والرفع الجماعي، وwebhooks حالة التسليم، ومعالجة الأخطاء، مستخدمًا فقط نقاط النهاية والحقول الواردة في [مرجع SMS API](/developers/sms/) ومواصفة OpenAPI لدينا. ## كيف أرسل SMS عبر الـ API؟ أرسل طلب `POST` موثّقًا إلى `/sms/sendSms` بجسم JSON. الاستجابة `200 OK` ومعها معرّف الرسالة نصًا عاديًا. | العنصر | القيمة | |---|---| | عنوان الأساس | `https://api.broadnet.me` (دون بادئة `/v1`) | | نقطة النهاية | `POST /sms/sendSms` | | المصادقة | `Authorization: Bearer $BROADNET_TOKEN` | | نوع المحتوى | `application/json` | | الحقول المطلوبة | `senderId` و`destinationNumber` و`message` و`messageType` | تُصدَر بيانات اعتماد الاختبار بعد طلب وصول قصير، وتذهب رسائل الاختبار إلى أرقامك الموثّقة. لا يوجد تسجيل ذاتي فوري. راجع [البدء السريع](/developers/quickstart/). ```bash curl -X POST https://api.broadnet.me/sms/sendSms \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "senderId": "OmniDemo", "destinationNumber": "447700900123", "message": "Your OmniDemo code is 482913", "messageType": "TEXT" }' ``` ```js // Node.js 18+ (fetch مدمج) const res = await fetch("https://api.broadnet.me/sms/sendSms", { method: "POST", headers: { Authorization: `Bearer ${process.env.BROADNET_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ senderId: "OmniDemo", destinationNumber: "447700900123", message: "Your OmniDemo code is 482913", messageType: "TEXT", }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const messageId = await res.text(); // معرّف الرسالة نص عادي ``` ```python import os import requests r = requests.post( "https://api.broadnet.me/sms/sendSms", headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"}, json={ "senderId": "OmniDemo", "destinationNumber": "447700900123", "message": "Your OmniDemo code is 482913", "messageType": "TEXT", }, timeout=15, ) r.raise_for_status() message_id = r.text # معرّف الرسالة نص عادي وليس JSON ``` ```php "OmniDemo", "destinationNumber" => "447700900123", "message" => "Your OmniDemo code is 482913", "messageType" => "TEXT", ]); $ch = curl_init("https://api.broadnet.me/sms/sendSms"); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("BROADNET_TOKEN"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $messageId = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); curl_close($ch); echo $status . " " . $messageId . PHP_EOL; ``` يبدو جسم الاستجابة الناجحة هكذا: ```text 2603121407537573731 ``` احفظ هذا المعرّف مع سجلك الخاص، مثل طلب أو محاولة تسجيل دخول. به تطابق حالات التسليم لاحقًا. ## كيف أنسّق أرقام الهاتف؟ استخدم رمز الدولة مع الرقم الوطني، أرقامًا فقط. تتبع الصيغة خطة الترقيم الدولية في ITU-T E.164، دون علامة الزائد. | المُدخل | صالح؟ | السبب | |---|---|---| | `447700900123` | نعم | رمز الدولة 44 مع الرقم الوطني | | `+44 7700 900123` | لا | أزل علامة الزائد والمسافات | | `07700900123` | لا | استبدل الصفر في البداية برمز الدولة | خزّن الأرقام بصيغة E.164 (`+447700900123`) في قاعدة بياناتك وأزل `+` عند بناء الطلب. وتساعدك أداة تنسيق أرقام الهاتف المجانية في فحص سريع. ## كيف أرسل نصًا عربيًا أو رموزًا تعبيرية أو Unicode آخر؟ اضبط `messageType` على `UNICODE`. أي حرف خارج أبجدية GSM-7، مثل حرف عربي أو رمز تعبيري أو علامة اقتباس منحنية أو شرطة طويلة، ينقل الرسالة كلها إلى Unicode. ```python r = requests.post( "https://api.broadnet.me/sms/sendSms", headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"}, json={ "senderId": "OmniDemo", "destinationNumber": "971500000000", "message": "رمز التحقق الخاص بك هو 482913", "messageType": "UNICODE", "campaignName": "login-otp", }, timeout=15, ) ``` في PHP، استخدم `JSON_UNESCAPED_UNICODE` عند استدعاء `json_encode`. يحدد الترميز حجم الجزء، كما تعرّفه 3GPP TS 23.040 لـ SMS: | `messageType` | الرسالة الواحدة | لكل جزء عند التقسيم | الاستخدام | |---|---|---|---| | `TEXT` | 160 حرفًا | 153 حرفًا | نص يستخدم أبجدية GSM-7 فقط | | `UNICODE` | 70 حرفًا | 67 حرفًا | العربية والسيريلية والصينية والرموز التعبيرية | يحتسب معظم المشغّلين رسومًا لكل جزء، فتكلف رسالة عربية طويلة أكثر من رسالة بالطول نفسه بالأحرف اللاتينية. اقرأ [دليلنا عن Unicode وSMS العربية](/ar/blog/sms-character-limits-unicode-arabic/) وجرّب عدّاد أحرف SMS. ## كيف أحسب الأجزاء قبل الإرسال؟ استدعِ `POST /sms/identify` مع الرسالة. تعيد الترميز المكتشف وعدد الأحرف وعدد الأجزاء وحد الجزء. ```bash curl -X POST https://api.broadnet.me/sms/identify \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "message": "Your OmniDemo code is 482913" }' ``` ```json { "message": "Your OmniDemo code is 482913", "messageType": "TEXT", "smscount": 1, "charCount": 28, "charLimit": 160 } ``` يمكنك تمرير `smsParts` (من `smscount`) و`charCount` و`charLimit` في طلب الإرسال. وقد يُوسَم نص GSM-7 بـ `GSM-7` في الاستجابة؛ أرسله بوصفه `TEXT`. ## كيف أرسل إلى أرقام كثيرة؟ استخدم `POST /sms/sendbulk`، وهو طلب `multipart/form-data` يتضمن ملف المستلمين ونص JSON للإعدادات. ```bash curl -X POST https://api.broadnet.me/sms/sendbulk \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -F destinationNumberFile=@recipients.csv \ -F 'bulkRequest={"senderId":"OmniDemo","message":"Your statement is ready in the app.","messageType":"TEXT","campaignName":"oct-statements","allowDuplicate":false}' ``` ```python import json import os import requests bulk_request = { "senderId": "OmniDemo", "message": "Your statement is ready in the app.", "messageType": "TEXT", "campaignName": "oct-statements", "allowDuplicate": False, } with open("recipients.csv", "rb") as f: r = requests.post( "https://api.broadnet.me/sms/sendbulk", headers={"Authorization": f"Bearer {os.environ['BROADNET_TOKEN']}"}, files={"destinationNumberFile": ("recipients.csv", f, "text/csv")}, data={"bulkRequest": json.dumps(bulk_request)}, timeout=60, ) print(r.json()) ``` تتضمن الاستجابة `bulkSessionId` وكائن `bulkListInfo` يضم `total` و`validCount` و`invalidCount` و`duplicate`. خزّن `bulkSessionId` مع الحملة. ويمكن سرد المهام وإيقافها مؤقتًا واستئنافها وإلغاؤها بنقاط النهاية الواردة في المرجع. ويمكنك أيضًا فحص الأرقام قبل إرسال كبير بـ `POST /sms/lookup`؛ راجع [دليل HLR lookup](/ar/blog/hlr-lookup-number-validation/). ## كيف أتلقى حالة التسليم؟ تُدفع حالات التسليم إلى عنوان webhook المضبوط على حسابك. تنتقل الرسالة عبر `SUBMITTED` و`SENT` إلى `DELIVERED`، أو تنتهي بـ `FAILED` أو `REJECTED`. تعطي فريقنا عنوان HTTPS العام، ويستطيع الموزّعون الحصول على webhook واحد لكل حساب فرعي. تختلف حقول الحمولة باختلاف القناة، ولا تحدد مواصفة الـ API مخطط webhook واحدًا، لذا سجّل الجسم الخام أولًا وابنِ الربط بين الحقول من حدث حقيقي على حسابك. يخزّن المستقبِل البسيط الحدث ويؤكد الاستلام سريعًا: ```js import express from "express"; const app = express(); app.post("/webhooks/omnichannels", express.json(), async (req, res) => { await saveStatusEvent(req.body); // التخزين من جانبك؛ عالج بصورة غير متزامنة res.sendStatus(200); // أكّد الاستلام بسرعة }); app.listen(3000); ``` اجعل المعالجة idempotent، لأن الحالة نفسها قد تصل مرتين، ولا تدع `SENT` متأخرة تستبدل `DELIVERED` محفوظة. وإذا كانت نقطة استقبالك متوقفة، يعيد `POST /sms/resendDlr` دفع الإيصالات لنطاق تواريخ: ```bash curl -X POST https://api.broadnet.me/sms/resendDlr \ -H "Authorization: Bearer $BROADNET_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "startDate": "2026-10-09", "endDate": "2026-10-10", "senderId": "OmniDemo", "messageStatus": "DELIVERED" }' ``` اقرأ المزيد في [دليل webhooks](/developers/webhooks/) وفي حالات تسليم الرسائل موضّحة. ## كيف أعالج الأخطاء وأتجنب التكرار؟ عالج حالة HTTP أولًا، ثم جسم الخطأ. أعد المحاولة فقط عند أخطاء الشبكة و`429` و`5xx`. | الرمز | المعنى | الإجراء | |---|---|---| | `200` | مقبول | خزّن المعرّف | | `400` | خطأ تحقق أو حقل مفقود | أصلح الطلب | | `401` / `403` | رمز غير صالح أو عملية غير مسموحة | أصلح؛ ولا تعد المحاولة | | `429` | تجاوز حد المعدل | انتظر `Retry-After` | | `500` و`503` و`504` | مشكلة في الخادم أو المنبع | أعد المحاولة بتراجع وتشويش | تستخدم الأخطاء التي يطلقها الـ API جسم JSON من خمسة حقول: `status` و`error` و`message` و`errorCode` و`requestUri`. والحد الموثّق الافتراضي لـ REST هو 200 طلب في الثانية بصورة مستدامة؛ وتُؤكَّد حدود حسابك مع بيانات اعتمادك. لا يقبل الـ API مفتاح idempotency. قد ينجح الطلب وتضيع استجابته، فتؤدي إعادة المحاولة العمياء إلى إرسال مزدوج. اكتب صفًا معلقًا بمفتاح معرّف عمليتك قبل الاستدعاء، وخزّن معرّف الرسالة العائد، وبعد انتهاء المهلة تحقق من حالة webhook قبل الإرسال مجددًا. وللإرسال الجماعي اضبط `allowDuplicate` على `false`. التفاصيل في [الأخطاء والحدود](/developers/errors-and-limits/). ## مثال تطبيقي: رموز تسجيل الدخول لتطبيق إقليمي ترسل «سوق رفيق» (اسم افتراضي)، وهي متجر تجزئة في الإمارات، رموز تسجيل الدخول عبر SMS. 1. تولّد خدمة المصادقة رمزًا من ست خانات وتخزّن تجزئته مع انتهاء صلاحية خمس دقائق وتكتب صف إرسال بحالة `pending`. 2. تستدعي `/sms/sendSms` مع `messageType=UNICODE` للمستخدمين العرب و`TEXT` للمستخدمين الإنجليز. 3. عند `200` تخزّن معرّف الرسالة. 4. يعلّم معالج webhook الصف `DELIVERED` أو `FAILED` أو `REJECTED`. 5. إذا لم تكن الحالة `DELIVERED` بعد انتظار قصير، يعرض التطبيق إعادة الإرسال، وقناة أخرى إن كانت مضبوطة. راجع البديل بين القنوات. 6. تحمي حدود طلبات الرموز لكل رقم ولكل عنوان IP من الإساءة؛ راجع [منع SMS pumping](/ar/blog/sms-pumping-fraud-prevention/). ## ما الأخطاء الشائعة؟ - **استدعاء `r.json()` على استجابة الإرسال.** إنها نص عادي. - **أسماء حقول خاطئة.** استخدم `senderId` و`destinationNumber` و`message`؛ فحقول مثل `to` و`from` و`text` ليست جزءًا من نقطة النهاية هذه. - **علامات الزائد والأصفار البادئة** في الأرقام. - **نسيان `UNICODE`** للعربية، فيتشوه النص. - **أسماء مرسل غير مسجلة.** بعض الدول تحظرها أو تستبدلها؛ راجع قواعد اسم المرسل لوجهتك، واطلب منا تولي التسجيل. - **اعتبار `200` تسليمًا.** - **الرمز في تطبيق جوال أو متصفح،** حيث يستطيع أي شخص استخراجه. - **الحدود:** يعرض هذا الدليل الطلب الشائع. أما الحقول الاختيارية مثل صيغ الجدولة فينبغي تأكيدها مع فريقنا. ## كيف تساعدك OmniChannels.ai؟ ترسل OmniChannels.ai رسائل A2P SMS عبر اتصال BroadNet المباشر بالمشغّلين، مع SMS ثنائية الاتجاه وأسماء المرسل وUnicode والعربية وHLR lookup وSMPP 3.4 للأحجام الكبيرة. وتستخدم واجهة REST على `https://api.broadnet.me` رمز Bearer وتغطي أيضًا واتساب وRCS وقنوات أخرى، مع توحيد حالات التسليم في صيغة webhook واحدة. ويجهّز فريقنا تسجيلات اسم المرسل معك. راجع [مرجع SMS API](/developers/sms/) أو قناة SMS.