​

SMS

​

أرسل SMS

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "مرحبًا من Orbit!"
  }'

import { Devotel } from '@devotel-orbit/node';

const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY });

// قنوات الجسم فقط توجَّه عبر المساعد العام المُنوَّه.
const message = await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  from: '+18005551234',          // مرسل صريح — احذف لاستخدام افتراضي المستأجر
  body: 'مرحبًا من Orbit!',
});

console.log(message.data.id);      // msg_a1b2…
console.log(message.data.status);  // 'queued'

// لا SDK؟ fetch العادي كافٍ — شكل الطلب ينتقل دون تغيير.
const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+14155552671',
    from: '+18005551234',
    body: 'مرحبًا من Orbit!',
  }),
});
const { data } = await res.json();
console.log(data.id, data.status); // نفس الغلاف كاستجابة curl أدناه

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # يقرأ ORBIT_API_KEY

message = client.messages.send_sms(
    to="+14155552671",
    body="مرحبًا من Orbit!",
    from_="+18005551234",  # مرسل صريح — احذف لاستخدام افتراضي المستأجر
)

print(message["data"]["id"])       # msg_a1b2…
print(message["data"]["status"])   # 'queued'

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "مرحبًا من Orbit!",
    From: "+18005551234",  // مرسل صريح — احذف لاستخدام افتراضي المستأجر
})
if err != nil {
    panic(err)
}

fmt.Println(msg.Data.ID)      // msg_a1b2…
fmt.Println(msg.Data.Status)  // "queued"

# غطاء هروب HTTP خام للغات بلا SDK مُنوَّه — أي عميل أو
# مكتبة يعمل طالما يمكنه ضبط رأس وجسم JSON.
send = client.request(
    "POST",
    "/messages/sms",
    json_body: {
        to: "+14155552671",
        from: "+18005551234",
        body: "مرحبًا من Orbit!",
    },
)

puts send.dig("data", "id")       # msg_a1b2…
puts send.dig("data", "status")   # 'queued'

​

الاستجابة

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "segments": 1,
    "encoding": "GSM-7"
  },
  "meta": {
    "request_id": "req_sms_send",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

• Node.js / fetch (TypeScript) — قيمة SDK أو res.json() تحمل الغلاف: message.data.id, message.data.status.
• Python — send_sms يعيد جسم JSON خام كقاموس: message["data"]["id"], message["data"]["status"].
• Go — SendSMS يفك الغلاف إلى struct مُنوَّه: msg.Data.ID, msg.Data.Status.
• Ruby / PHP (غطاء الهروب) — client.request يعيد جسم JSON خام: send.dig("data", "id") / $send['data']['id'].

​

أنماط شائعة

​

إرسال idempotent بـIdempotency-Key

const message = await orbit.messages.send(
  { channel: 'sms', to: '+14155552671', body: 'مرحبًا من Orbit!' },
  { idempotencyKey: 'job-7a3b9d-checkout-reminder' },  // مفتاح ثابت عبر المحاولات
);

message = client.messages.send_sms(
    to="+14155552671",
    body="مرحبًا من Orbit!",
    idempotency_key="job-7a3b9d-checkout-reminder",  # مفتاح ثابت عبر المحاولات
)

​

صفح GET /messages عبر استدعاءات القائمة في SDK

// حلقة مؤشر — تحكم صريح.
let cursor: string | undefined;
do {
  const page = await orbit.messages.list({ channel: 'sms', limit: 100, cursor });
  for (const message of page.data) {
    // استهلك رسالة واحدة لكل تكرار
  }
  cursor = page.meta.pagination.has_more
    ? page.meta.pagination.cursor
    : undefined;
} while (cursor);

// …أو دع المُنمِّك يُصفِّح لك:
for await (const message of orbit.messages.iter({ channel: 'sms' })) {
  console.log(message.id, message.status);
}

# يُغلّف Python SDK الموارد الأساسية فقط — صفّح عبر غطاء الهروب الذي
# يقبل قاموس `query` إلى جانب `json_body`.
cursor = None
while True:
    query = {"channel": "sms", "limit": 100}
    if cursor:
        query["cursor"] = cursor
    page = client.request("GET", "/messages", query=query)
    for message in page["data"]:
        # استهلك رسالة واحدة لكل تكرار
        pass
    pagination = page["meta"]["pagination"]
    if not pagination.get("has_more"):
        break
    cursor = pagination["cursor"]

​

مثال عمل: إرسال واستعلام ومعالجة الإخفاقات

​

1. أرسل الرسالة

curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "مرحبًا من Orbit 🚀 — نص مُنظَم: 160 حرفًا هنا كانا مقطعَي UCS-2"
  }'

​

2. اقرأ استجابة الإرسال

{
  "data": {
    "id": "msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9",
    "status": "queued",
    "channel": "sms",
    "segments": 2,
    "encoding": "UCS-2"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-09-06T12:00:00Z"
  }
}

​

3. استعلم الصف

curl https://api.orbit.devotel.io/api/v1/messages/msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "id": "msg_e4d5c6b7a8b9c0d1e2f3a4b5c6d7e8f9",
    "channel": "sms",
    "direction": "outbound",
    "to": "+14155552671",
    "from": "+18005551234",
    "status": "delivered",
    "segments": 2,
    "encoding": "UCS-2",
    "external_id": "dev-smpp-e9a8b7c6",
    "sent_at": "2026-09-06T12:00:01Z",
    "error_code": null,
    "error_message": null,
    "metadata": {}
  },
  "meta": {
    "request_id": "req_poll_002",
    "timestamp": "2026-09-06T12:00:02Z"
  }
}

​

4. تفرّع على الإخفاقات

​

أساسيات توصيل SMS

​

اختر نوع المرسل

​

التسجيل على لوحة القيادة

1. افتح Channels → SMS في لوحة القيادة.
2. انقر Attach Sender واخِر نوع المرسل أعلاه. يُحقِّق Orbit الصيغة (رقم E.164، معرّف أبجدي رقمي 3–11، أو مرجع مجمع) ويتحقق هل الوجهة التي اخترتها افتراضية تتطلب التسجيل.
3. أرسل رسالة اختبارية إلى رقم تملكه. يُظهر المحرر segments وencoding سطريًا، فترى الكلفة المقطعية المُقدَّرة قبل الإرسال.
4. إذا رفض منعك الوجهة الربط (US بلا حملة 10DLC، دولة مقيدة بلا موافقة معرّف مرسل)، يوجّهك المُرشد إلى تدفق التسجيل — انظر القسمَين التاليَين.

​

تسجيل 10DLC & أنواع الحملات (الولايات المتحدة)

​

الترميز والربط

​

GSM-7 مقابل UCS-2

• GSM-7 — أبجدية GSM سبعة-بت (ASCII زيادة قليل: @, £, €, بعض اليونانية). جسم يتسعها يحصل حتى 160 حرفًا لكل مقطع، أو 153 حرفًا على إرسال متعدد الأجزاء (7 لكل مقطع تذهب إلى رأس UDH للربط).
• UCS-2 — أي حرف خارج GSM-7 (emoji، CJK، اقتباسات ذكية، معظم الكتابات اللالاتينية) يقلب الرسالة كلها إلى ترميز 16-بت. جسم يحصل حتى 70 حرفًا لكل مقطع، أو 67 على متعدد الأجزاء.

segments = ceil(chars / per_segment_limit)
per_segment_limit = single_limit         إن اتسعت مقطعًا واحدًا
                  = single_limit - header  وإلا              (GSM-7: 153, UCS-2: 67)

​

مثال عمل

{
  "segments": 2,
  "encoding": "UCS-2"
}

​

حدود المعدل، الإنتاجية، ومجمعات المرسلين

1. حد الطلب جهة API. 100 طلب/دقيقة لكل مستأجر افتراضيًا على POST /messages/sms، مفنوح لكل منظمة. فوقه تتلقى 429 RATE_LIMITED؛ انظر دليل حدود المعدل للرؤوس ومعالجة المحاولة. جدول القنوات الكامل أدنى.
2. إنتاجية جهة المرسل. US 10DLC: سقف يومي، لكل رقم، على المقاطع، ضبطه طابق فحصك. في الموضع الآخر: أيًّا يدعمه مسار الوجهة لكل مرسل.

​

دورة حالة الرسائل

• submitted_no_receipt — المزود قبل الإرسال، لا DLR عاد داخل نافذة 30 دقيقة SMPP. مُعلَّم وسيط (is_terminal: false) لأن delivered متأخر أو إخفاق DLR ربما يأتيان ويكتبان فوقه. تعامل معه كـخارج مجهول، لا تسليمًا ولا إخفاقًا.
• expired — DLR وصل بعد اغلاق نافذة الوصول المتأخر. صف مغلق، نتيجة غير قابلة للمعرفة؛ يُفن-أوت على message.failed.
• cancelled — قابل للوصول منك فقط؛ لا webhook يشتعل له أبدًا.

​

استكشاف الأخطاء

​

التسعير

​

الميزات

• رسائل A2P وP2P — دعم تطبيق-إلى-شخص وشخص-إلى-شخص
• وصول عالمي — أكثر من 190 دولة عبر شبكة مجمّعات Devotel
• تقارير تسليم — webhooks حالة لحظية لكل رسالة
• رسائل مربوطة — SMS متعدد الأجزاء مُعامَل شفافًا (حتى 10 مقاطع)
• تحقق E.164 — تحقق صيغة الرقم الهاتف التلقائي
• دعم Unicode — GSM-7 وUCS-2 كاملين مع اكتشاف تلقائي وتنظيم اقتباسات ذكية
• معرّف مرسل — معرّفات مرسل أبجدية رقمية حيث تدعم التنظيمات المحلية، مقيدة بالتسجيل حيث يلزم

​

حدود المعدل