إرسال الرسائل واستلامها

تنقلك هذه الجولة من مفتاح API إلى تدفق رسائل ثنائي الاتجاه يعمل: تُرسل رسالة صادرة، تتتبع تسليمها، وتستقبل الرد على خادمك. نستخدم SMS كمثال جارٍ؛ وينطبق نمط الخطوات الثلاث نفسه (إرسال → تتبع → استلام) على WhatsApp وRCS وViber والبريد الإلكتروني، كلٌ على نقطة نهاية خاصة به. ما ستفعله:

إرسال رسالة
تتبع التسليم
استلام الرسائل الواردة
الرد على رسالة واردة

المتطلبات المسبقة

مفتاح API من الإعدادات → مفاتيح API. استخدم مفتاح sandbox (dv_test_sk_…) أثناء البناء — إرسالات sandbox مجانية ومُحاكاة، وتُرجع إيصالات تسليم محددة مسبقاً بحيث تختبر مسارَي النجاح والفشل معاً. استبدل مفتاحًا حياً (dv_live_sk_…) عند الإنتاج.
رقم مُرسل قادر على الإرسال عبر القناة التي تستخدمها. بالنسبة إلى SMS هذا رقم مملوك لك يدعم SMS (ابحث عنه واشترِه عبر Numbers API، أو من Dashboard → Numbers). إذا حذفت from يختار Orbit مُرسِلًا مناسباً للوجهة.
عنوان HTTPS عام لخطوة الاستلام. أي أداة تمديد أنفاق (tunneling) تعمل أثناء التطوير.

تذهب كل الطلبات إلى عنوان أساسي واحد — يستخدم sandbox المضيف نفسه، ويُختار بمفتاحك وليس باسم مجال مختلف:

https://api.orbit.devotel.io/api/v1

يحمل كل طلب مفتاحك في رأس X-API-Key.

1. إرسال رسالة

أرسل SMS باستخدام POST /messages/sms. الحقول to وbody فقط مطلوبة؛ وfrom اختياري.

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" \
  -H "Idempotency-Key: order-conf-98421" \
  -d '{
    "to": "+14155552671",
    "from": "+18005551234",
    "body": "Your order #1234 has shipped. Reply STATUS for tracking."
  }'

الاستجابة هي 202 Accepted — تُحفظ الرسالة نهائياً وتُضاف إلى الطابور للتسليم، ولم تُسلَّم بعد إلى مشغل الشبكة. تعيش الحقول تحت data؛ ويحمل meta الـrequest_id الذي يجب عليك تسجيله لدعم العمليات.

{
  "data": {
    "id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "status": "queued",
    "channel": "sms",
    "direction": "outbound",
    "segments": 1
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-07-20T00:00:00Z"
  }
}

الـid (msg_ متبوعاً بـ32 محرفاً سداسياً عشرياً) هو المقبض الذي تعتمد عليه كل المكالمات التابعة” — استعلامات الوضع، وويب هوكات التسليم، وأثر الرسالة كلها تعمل به. تضيف استجابات sandbox "test_mode": true إلى meta.

أرسل دائماً Idempotency-Key عند الإرسال. إعادة تشغيل المفتاح نفسه والنص نفسهما خلال 24 ساعة تعيد الاستجابة الأصلية بدلاً من إرسال نسخة مكررة؛ وإعادة تشغيله بنص مختلف تعيد 409 IDEMPOTENCY_KEY_REUSED.

القنوات الأخرى

كل قناة لها نقطة نهاية خاصة بها تحت بادئة /messages، وهيئة نص مُفَصَّلَة لتلك القناة. لا يوجد مسار واحد متعدد الأشكال بحسب القناة (polymorphic) — اختر نقطة النهاية المطابقة لقناتك:

القناة	نقطة النهاية	المرجع
SMS	`POST /messages/sms`	Messaging API
WhatsApp	`POST /messages/whatsapp`	قناة WhatsApp
RCS	`POST /messages/rcs`	قناة RCS
Viber	`POST /messages/viber`	قناة Viber
البريد الإلكتروني	`POST /messages/email`	قناة البريد الإلكتروني

2. تتبع التسليم

تتقدم الرسالة المعلَّقة في الطابور عبر دورة حياة من الحالات قبل الوصول إلى المستلم:

queued → sending → sent → delivered   (or failed / undelivered)

لديك طريقتان للمتابعة: استطلاع (Poll) الرسالة بواسطة المعرف:

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

الاشتراك في webhooks (موصى به — بلا استطلاع). ينطلق حدث واحد لكل انتقال في الحالة، ويحمل كل منها معرّف الرسالة id والحالة status الجديدة:

message.sent — قبِلها مشغل الشبكة
message.delivered — تأكَّد تسليمها إلى الجهاز
message.failed — فشل نهائي (يُميِّز الـstatus في الحمولة بين failed وundelivered وexpired وsubmitted_no_receipt؛ ويحمل error_code / error_message سبب المزود عند وجوده)

سجِّل نقطة webhook مرة واحدة، ثم دع الأحداث تتدفق:

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.sent", "message.delivered", "message.failed", "message.received"],
    "secret": "whsec_your_signing_secret"
  }'

يبدو حدث التسليم كالتالي:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-07-20T12:00:00Z",
  "data": {
    "message_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "channel": "sms",
    "status": "delivered",
    "is_terminal": true,
    "timestamp": "2026-07-20T12:00:00Z"
  }
}

تحقّق من رأس X-Orbit-Signature قبل الوثوق في أي حمولة، وأزل التكرارات باستخدام معرّف الحدث id — التسليم يُنفَّذ مرة واحدة على الأقل (at-least-once). راجع أمان webhooks لأجل مقتطف التحقق.

3. استلام الرسائل الواردة

عندما يردُّ شخص على رقمك (أو يراسله أولاً)، يسجِّل Orbit رسالة واردة و — إن كنت مشتركاً في message.received في الخطوة السابقة — يُرسل POST إلى عنوان webhook لديك:

{
  "id": "evt_def456",
  "type": "message.received",
  "created_at": "2026-07-20T12:01:00Z",
  "data": {
    "message_id": "msg_inb_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "STATUS"
  }
}

الرسالة الواردة أيضاً قابلة للاستعلام — اسرد كل ما استلمته بفلتر direction=inbound:

curl "https://api.orbit.devotel.io/api/v1/messages?direction=inbound&channel=sms" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

التوجيه الوارد تلقائي للأرقام المملوكة لك في Orbit — يُلتَقط أي رد على أرقامك المرسلة وباشتراك message.received تُسلَّم إلى webhook الخاص بك. لا حاجة لربط عنوان وارد خاص لكل رقم.

4. الرد على رسالة واردة

الرد هو مجرد إرسال آخر، موجَّه إلى from الوارد. بدِّل to وfrom وأعِد استدعاء POST /messages/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": "Order #1234 is out for delivery, arriving today by 5pm."
  }'

تتشارك كلتا الرسالتين محادثة واحدة؛ وما أن يتكوّن الخيط يمكنك سحب الدردشة الكاملة عبر فلتر conversation_id في GET /messages.

الأخطاء الشائعة

كل خطأ يستخدم الهيئة نفسها — طابِق على error.code (ثابت بأحرف كبيرة)، وسجّل meta.request_id:

الرمز	HTTP	المعنى	الحل
`INVALID_API_KEY`	401	مفتاح مُلغى، بيئة خاطئة، أو خطأ إملائي	تحقق من الإعدادات → مفاتيح API
`INVALID_PHONE_NUMBER`	422	`to` ليس E.164 صالحاً أو غير قابل للوصول	تحقّق من الرقم قبل الإرسال
`NOT_SMS_CAPABLE`	422	المرسل لا يدعم SMS (مثلاً toll-free بلا 10DLC)	سجِّل الرقم أو غيَّرْه
`INSUFFICIENT_BALANCE`	402	رصيد المحفظة دون حد القناة الأدنى	اشحن محفظتك
`RATE_LIMITED`	429	إرسالات كثيرة جداً	راعِ `details.retry_after` (بالثواني)
`VALIDATION_ERROR`	422	هيئة النص خاطئة	اقرأ `details.issues` لكل حقل

القائمة الكاملة: رموز الأخطاء.

الخطوات التالية

مرجع Messaging API — كل نقطة نهاية وكل حقل رسالة
دورة حيات حالة الرسالة — مجموعة الحالات الكاملة لكل قناة
نظرة عامة على Webhooks — إعادات المحاولة، وضمانات التسليم، وفهرس الأحداث
تكامل API — sandbox، وidempotency، والتصفّح، وSDKs عبر كل القنوات
حدود المعدل — حدود لكل قناة ورؤوس إعادة المحاولة

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

إرسال الرسائل واستلامها

إرسال الرسائل واستلامها

المتطلبات المسبقة

1. إرسال رسالة

القنوات الأخرى

2. تتبع التسليم

3. استلام الرسائل الواردة

4. الرد على رسالة واردة

الأخطاء الشائعة

الخطوات التالية

​إرسال الرسائل واستلامها

​المتطلبات المسبقة

​1. إرسال رسالة

​القنوات الأخرى

​2. تتبع التسليم

​3. استلام الرسائل الواردة

​4. الرد على رسالة واردة

​الأخطاء الشائعة

​الخطوات التالية

إرسال الرسائل واستلامها

المتطلبات المسبقة

1. إرسال رسالة

القنوات الأخرى

2. تتبع التسليم

3. استلام الرسائل الواردة

4. الرد على رسالة واردة

الأخطاء الشائعة

الخطوات التالية