أدخِل الرسائل النصية
إلى خدمتك.

البدء السريع

1. أنشئ مفتاح API

   بعد التسجيل والموافقة وتسجيل الدخول عبر OTP، افتح إدارة مفاتيح API لإصدار المفتاح.

2. جهّز رصيدك

   تستخدم الواجهة رصيد حسابك وأسعاره كما هي. يُخصم المبلغ عند قبول طلب الإرسال.

3. أرسل الرسائل وتابع النتائج

   احفظ معرّف الحملة وتابع النتائج عبر واجهة الاستعلام عن الحالة.

الدول المدعومة

GET/api/v1/messages/countries

تحقّق عبر API من الدول المفعّلة والأسعار المطبّقة فعليًا. حدّد الدولة في طلب الإرسال عبر country، واستخدم أرقامًا من الدولة نفسها في كل طلب. لا يُقبل الإرسال إلى الدول التي لم يُحدَّد لها سعر.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

المصادقة بمفتاح API

أضف الترويسة التالية إلى كل طلب API خارجي. لا حاجة إلى ملفات تعريف ارتباط تسجيل الدخول أو رموز OTP.

Authorization: Bearer hex_live_ضع_مفتاحك_هنا

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

أرسل إلى 1,000 رقم دفعة واحدة

أرسل نص رسالة واحدًا إلى عدة أرقام. نتحقق من الطلب ونضيفه إلى قائمة الإرسال ثم نرد فورًا. لإرسال محتوى مختلف لكل رقم، استخدم طلبات منفصلة بقيمة Idempotency-Key جديدة لكل منها.

إذا وُجد رقم غير صالح أو مكرّر واحد على الأقل، يُرفض الطلب بأكمله دون إرسال أو خصم. يُتحقق من التكرار بعد تحويل الأرقام إلى التنسيق الدولي.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

كيف تُحسب التكلفة

عدد الأرقام × عدد الأجزاء (segments) × سعر الحساب — هكذا تُحسب التكلفة. تتسع رسالة UCS-2 لـ 70 حرفًا في الجزء الأول، ثم 67 حرفًا لكل جزء. وتتسع أحرف GSM-7 الأساسية لـ 160 حرفًا، ثم 153 حرفًا لكل جزء. تُحتسب أحرف الامتداد بخانتين، والرموز التعبيرية حسب طولها في UTF-16. القيمتان unitPrice وcost بالـ USDT. السعر الوارد في الاستجابة هو السعر المطبّق فعليًا، والقيمة 0.025 أعلاه مجرد مثال.

تحقّق من نتيجة الإرسال لكل رقم

استخدم قيمة id التي أعادتها واجهة الإرسال. لا يمكن الاستعلام إلا عن الحملات المُرسَلة عبر API من الحساب نفسه. يُرجع الاستعلام النتائج المحفوظة؛ إذا احتجت أحدث نتائج المشغّل، فاستدعِ واجهة تحديث الحالة التالية أولًا.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

قيمة limit من 1 إلى 1,000 (الافتراضي 100)، وoffset من 0 إلى 1,000 (الافتراضي 0). إذا كانت nextOffset تساوي null فهذه الصفحة الأخيرة. يعرض summary عدد الأرقام حسب كل حالة. تُعاد قيمة to بالتنسيق الدولي دون +، والأوقات بالمللي ثانية وفق Unix. قد يختلف ترتيب النتائج عن ترتيب الإرسال الأصلي، لذا ميّز كل رسالة بقيمة id الخاصة بها.

احصل على أحدث حالة استلام

تُحدَّث النتائج المحفوظة بالاستعلام عن سجلات المشغّل. لا حاجة إلى نص للطلب. بعد التحديث، اقرأ النتائج مجددًا عبر GET. يمكن تحديث الحملة نفسها مرة كل 30 ثانية. تتوفر سجلات المشغّل لمدة 48 ساعة بعد الإرسال. في البيئات المُعدّة بخطافات ويب، قد تنعكس النتائج تلقائيًا.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

تمثل updated عدد الصفوف المحدَّثة، وقد تكون 0 إذا كانت الرسائل لا تزال في الانتظار أو لا توجد نتائج جديدة. نوصي باستدعاء GET بفاصل 10 ثوانٍ على الأقل، وطلب refresh عند الحاجة فقط.

تعرّف على رموز الحالة

حالة طلب الإرسال state

PREPARING قيد التحضير · RUNNING قيد المعالجة · PAUSED متوقف مؤقتًا · DONE اكتملت معالجة القائمة · CANCELED ملغى

قد يضيف المشغّلون رموز حالة جديدة، لذا تعامل أيضًا مع قيم status غير المعروفة. يمكنك معرفة سبب الفشل من statusName وdescription وerror.

كيف تتعامل مع الأخطاء

{ "error": "الرصيد غير كافٍ. اشحن رصيدك ثم أعد الطلب.", "code": "INSUFFICIENT_CREDITS" }

يمكن لكل مفتاح API إرسال ما يصل إلى 120 طلبًا في الدقيقة، تشمل الإرسال والاستعلام والتحديث. عند بلوغ الحد، تحقّق من الترويسة Retry-After. هذه الواجهة مخصّصة للتكامل بين الخوادم، ولا تدعم استدعاءات CORS من المتصفح.

اتصل عبر Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

أنشئ مفتاح الطلب مرة واحدة لكل عملية، واستخدم القيمة نفسها عند إعادة المحاولة إذا لم تصل الاستجابة. إعادة إرسال عملية ناجحة بمفتاح جديد تُعامَل كإرسال منفصل.