> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> أرسل أول رسالة SMS أو WhatsApp عبر Orbit API واستقبل الردود الواردة عبر webhook في جولة شاملة واحدة لبدء سريع من طرف إلى طرف، مع أمثلة برمجية.

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

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

**ما ستفعله:**

1. [إرسال رسالة](#1-إرسال-رسالة)
2. [تتبع التسليم](#2-تتبع-التسليم)
3. [استلام الرسائل الواردة](#3-استلام-الرسائل-الواردة)
4. [الرد على رسالة واردة](#4-الرد-على-رسالة-واردة)

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

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

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

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

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

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

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

```bash theme={null}
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` الذي يجب عليك تسجيله لدعم العمليات.

```json theme={null}
{
  "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`.

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

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

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

| القناة            | نقطة النهاية              | المرجع                                              |
| ----------------- | ------------------------- | --------------------------------------------------- |
| SMS               | `POST /messages/sms`      | [Messaging API](/api-reference/endpoints/messaging) |
| WhatsApp          | `POST /messages/whatsapp` | [قناة WhatsApp](/channels/whatsapp)                 |
| RCS               | `POST /messages/rcs`      | [قناة RCS](/channels/rcs)                           |
| Viber             | `POST /messages/viber`    | [قناة Viber](/channels/viber)                       |
| البريد الإلكتروني | `POST /messages/email`    | [قناة البريد الإلكتروني](/channels/email)           |

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

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

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

لديك طريقتان للمتابعة:

**استطلاع** (Poll) الرسالة بواسطة المعرف:

```bash theme={null}
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 مرة واحدة، ثم دع الأحداث تتدفق:

```bash theme={null}
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"
  }'
```

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

```json theme={null}
{
  "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](/webhooks/security) لأجل مقتطف التحقق.

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

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

```json theme={null}
{
  "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`:

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

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

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

الرد هو مجرد إرسال آخر، موجَّه إلى `from` الوارد. بدِّل `to` و`from` وأعِد استدعاء `POST /messages/sms` مجدداً:

```bash theme={null}
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` لكل حقل         |

القائمة الكاملة: [رموز الأخطاء](/reference/error-codes).

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

* [مرجع Messaging API](/api-reference/endpoints/messaging) — كل نقطة نهاية وكل حقل رسالة
* [دورة حيات حالة الرسالة](/api-reference/messages-status-lifecycle) — مجموعة الحالات الكاملة لكل قناة
* [نظرة عامة على Webhooks](/webhooks/overview) — إعادات المحاولة، وضمانات التسليم، وفهرس الأحداث
* [تكامل API](/guides/api-integration) — sandbox، وidempotency، والتصفّح، وSDKs عبر كل القنوات
* [حدود المعدل](/guides/rate-limits) — حدود لكل قناة ورؤوس إعادة المحاولة