> ## 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 أو مكالمة أو بريد إلكتروني

> أرسل أول رسالة SMS أو مكالمة صوتية أو بريد إلكتروني عبر Orbit في أقل من خمس دقائق باستخدام API أو SDK، مع مقتطفات جاهزة للنسخ واللصق بكل لغة.

# البداية السريعة

## الخطوة 1: إنشاء حساب

سجّل في [orbit.devotel.io/signup](https://orbit.devotel.io/signup). ستوجهك لوحة التحكم تلقائيًا إلى عنوان URL المفضل لمنطقتك. لا حاجة لبطاقة ائتمان — يكفي التحقق من بريدك الإلكتروني لفتح بيئة Sandbox في الخطوة التالية.

## الخطوة 2: الحصول على مفتاح API لتجريبي (Sandbox)

انتقل إلى **Settings > API Keys**، وأنشئ مفتاحًا جديدًا، واضبط وضعه على **Test**. مفاتيح Sandbox تبدأ بالبادئة `dv_test_sk_` وتعمل فورًا دون أي خطوة KYC أو موافقة، وتكلفتها **0\$** — كل إرسال تجريبي يُحاكى داخليًا ولا يصل أبدًا إلى مشغّل حقيقي ولا يلامس Stripe. احتفظ بالمفتاح على خادمك فقط.

(المفاتيح الحية تبدأ بالبادئة `dv_live_sk_` وتُحاسَب على تدفق حقيقي — راجع [الخطوة 5: الانتقال إلى الإنتاج](#step-5-go-live) عندما تكون مستعدًا لأرقام الإنتاج.)

## الخطوة 3: إرسال رسالتك الأولى (تجريبي)

نفس شكل نقطة النهاية `/messages/<channel>` يعمل عبر SMS وWhatsApp والبريد الإلكتروني وRCS وViber وقنوات المراسلة الأخرى — اختر القناة التي تريد دمجها أولًا. الصوت منفصل: تُنفَّذ المكالمات عبر `POST /voice/calls` (راجع مثال Voice أدناه). استخدم مفتاح `dv_test_sk_` من الخطوة 2 كقيمة `$ORBIT_API_KEY` أدناه — الإرسال مجاني وفوري، دون أي خطر على التدفق الحي.

### cURL

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155551234",
    "body": "Hello from Orbit!"
  }'
```

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "type": "template",
    "template": {
      "name": "hello_world",
      "language": { "code": "en" }
    }
  }'
```

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/email \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "from": "hello@yourdomain.com",
    "subject": "Welcome",
    "html": "<h1>Welcome to Acme</h1>"
  }'
```

### Node.js SDK

`@devotel-orbit/node` يستبدل تلك الاستدعاءات الثلاثة لـ curl بأساليب مُنوَّعة (typed) — المرجع الكامل في [Node.js SDK](/sdks/node).

```typescript theme={null}
import { Orbit } from '@devotel-orbit/node';

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
});

// SMS
await orbit.messages.send({
  channel: 'sms',
  to: '+14155552671',
  body: 'Hello from Orbit!',
});

// WhatsApp template
await orbit.messages.sendWhatsApp({
  to: '+14155552671',
  type: 'template',
  template: {
    name: 'hello_world',
    language: { code: 'en' },
  },
});

// Email
await orbit.messages.sendEmail({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  subject: 'Welcome',
  html: '<h1>Welcome to Acme</h1>',
});
```

### Python SDK

```bash theme={null}
# Not yet on PyPI — install from the workspace package:
#   pip install ./packages/sdk-python
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```python theme={null}
from orbit_sdk import OrbitClient, OrbitError

client = OrbitClient.from_env()

try:
    result = client.messages.send_sms(
        to="+14155552671",
        body="Hello from Orbit!",
    )
    print("queued:", result["data"]["id"])
except OrbitError as exc:
    print("send failed:", exc.code, exc.message)
```

<Note>
  Python SDK ذو نطاق أساسي وغير منشور — تعمل إرسالات SMS وWhatsApp والبريد الإلكتروني اليوم؛ الأسطح الأعمق (تسجيلات الصوت، المؤتمرات، IVR، dialer) خارج النطاق عمدًا. لذلك استخدم Node SDK أعلاه أو استدعِ REST API مباشرة عبر مخرج الطوارئ منخفض المستوى `client.request(method, path, ...)` — راجع [نطاق SDK حسب اللغة](/sdks#python-core-scope-not-full-parity).
</Note>

### Go SDK

```bash theme={null}
# Not yet on a public module proxy — go get the workspace module path:
#   go get github.com/devotel/orbit-go
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```go theme={null}
// go.mod: require github.com/devotel/orbit-go (module path, not yet on a public proxy)
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil {
		panic(err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	resp, err := client.Messages().SendSMS(ctx, orbit.SendSMSInput{
		To:   "+14155552671",
		Body: "Hello from Orbit!",
	})
	if err != nil {
		panic(err)
	}
	fmt.Println("queued:", resp.Data.ID)
}
```

<Note>
  Go SDK ذو نطاق أساسي وغير منشور — تعمل `client.Messages()` + `client.Voice()` اليوم؛ المؤتمرات الصوتية/IVR/dialer/التسجيلات خارج النطاق. لذلك استخدم Node SDK أو مخرج الطوارئ منخفض المستوى `client.Request(ctx, method, path, ...)` — راجع [نطاق SDK حسب اللغة](/sdks#go-core-scope-not-full-parity).
</Note>

### Ruby SDK

```bash theme={null}
# Not yet on RubyGems — add the workspace path to your Gemfile:
#   gem "orbit_sdk", path: "packages/sdk-ruby"
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```ruby theme={null}
require "orbit_sdk"

client = OrbitSdk::Client.from_env
begin
  result = client.messages.send_sms(
    to: "+14155552671",
    body: "Hello from Orbit!",
  )
  puts "queued: #{result.dig("data", "id")}"
rescue OrbitSdk::OrbitError => e
  warn "send failed: #{e.code} — #{e.message}"
end
```

<Note>
  Ruby SDK ذو نطاق أساسي وغير منشور — تعمل إرسالات `client.messages` + `client.voice` اليوم؛ التسجيلات/النصوص تفريغ/المؤتمرات/IVR/dialer خارج النطاق. لذلك استخدم Node SDK أو مخرج الطوارئ منخفض المستوى `client.request(method, path, **opts)` — راجع [نطاق SDK حسب اللغة](/sdks#ruby-core-scope-not-full-parity).
</Note>

### PHP SDK

```bash theme={null}
# Not yet on Packagist — vendor the SDK from the monorepo or call the
# REST API directly. Setup lives on the PHP SDK page:
#   https://orbit.devotel.io/sdks/php
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```php theme={null}
<?php
use Devotel\Orbit\Errors\OrbitError;
use Devotel\Orbit\OrbitClient;

try {
    $client = OrbitClient::fromEnv();
    $result = $client->messages->sendSms(
        to: '+14155552671',
        body: 'Hello from Orbit!',
    );
    printf("queued: %s\n", $result['data']['id'] ?? '?');
} catch (OrbitError $e) {
    fwrite(STDERR, "send failed: {$e->errorCode} — {$e->getMessage()}\n");
}
```

<Note>
  PHP SDK ذو نطاق أساسي وغير منشور — تعمل إرسالات `$client->messages` + `$client->voice` اليوم؛ المؤتمرات وIVR وdialer وSIP trunks والتسجيلات خارج النطاق. لذلك استخدم Node SDK أو مخرج الطوارئ منخفض المستوى `OrbitClient::request(method: ..., path: ..., ...)` — راجع [نطاق SDK حسب اللغة](/sdks#php-core-scope-not-full-parity).
</Note>

### Java SDK

```bash theme={null}
# Not yet on Maven Central — build + depend on the workspace module:
#   mvn -f packages/sdk-java/pom.xml install
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```java theme={null}
import io.devotel.orbit.OrbitClient;
import io.devotel.orbit.errors.OrbitError;

import java.util.Map;

OrbitClient client = OrbitClient.fromEnv();
try {
    Map<String, Object> result = client.messages.sendSms(
        "+14155552671",
        "Hello from Orbit!"
    );
    System.out.println("queued: " + result.get("data"));
} catch (OrbitError e) {
    System.err.println("send failed: " + e.getCode() + " — " + e.getMessage());
}
```

<Note>
  Java SDK ذو نطاق أساسي وغير منشور — تعمل إرسالات `client.messages` + `client.voice` اليوم؛ التسجيلات/النصوص تفريغ/المؤتمرات/IVR/dialer ومكونات قوالب WhatsApp خارج النطاق. لذلك استخدم Node SDK أو مخرج الطوارئ منخفض المستوى `client.request(method, path, ...)` — راجع [نطاق SDK حسب اللغة](/sdks#java-core-scope-not-full-parity).
</Note>

### C# SDK

```bash theme={null}
# Not yet on NuGet — add the workspace project reference:
#   dotnet add reference packages/sdk-csharp
export ORBIT_API_KEY=dv_test_sk_your_key_here
```

```csharp theme={null}
// xmlns/pep: the .NET client ships as Orbit.Sdk in the monorepo.
using Orbit.Sdk;
using Orbit.Sdk.Errors;

try
{
    var client = OrbitClient.FromEnv();
    var result = await client.Messages.SendSmsAsync(
        "+14155552671",
        "Hello from Orbit!"
    );
    if (result.TryGetProperty("data", out var data) &&
        data.TryGetProperty("id", out var id))
        Console.WriteLine($"queued: {id.GetString()}");
}
catch (OrbitError e)
{
    Console.Error.WriteLine($"send failed: {e.Code} — {e.Message}");
}
```

<Note>
  .NET SDK ذو نطاق أساسي وغير منشور — تعمل إرسالات `client.Messages` + `client.Voice` اليوم؛ التسجيلات/النصوص تفريغ/المؤتمرات/IVR/dialer خارج النطاق. لذلك استخدم Node SDK أو مخرج الطوارئ منخفض المستوى `client.RequestAsync(method, path, ...)` — راجع [نطاق SDK حسب اللغة](/sdks#net-core-scope-not-full-parity).
</Note>

### Voice

#### cURL

نفّذ مكالمة باستخدام `POST /voice/calls`:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/calls \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155551234",
    "agent_id": "agt_support_bot"
  }'
```

#### Node.js SDK

```typescript theme={null}
const call = await orbit.voice.calls.create({
  to: '+14155552671',
  from: '+14155551234',
  agent_id: 'agt_support_bot',
});
```

<Note>
  تغطي SDKs الستة الأخرى (Python, Go, Ruby, PHP, Java, C#) نقطة `POST /voice/calls` ضمن نطاقها الأساسي — راجع الأقسام الخاصة بكل لغة أعلاه. التسجيلات الصوتية والنصوص تفريغ والمؤتمرات وIVR وdialer خارج نطاق تلك SDKs؛ استخدم Node SDK أو REST API مباشرة عبر مخرج الطوارئ منخفض المستوى `request(...)` لكل لغة — راجع [نطاق SDK حسب اللغة](/sdks).
</Note>

> بدأت مع الصوت من الصفر؟ تابع [Voice Quickstart](/voice/quickstart) المخصص — يغطي توفير رقم، وتكوين وكيل مع موجه نظام، والاختبار بميكروفون المتصفح، واشتراك أحداث SSE، وكل ذلك في أقل من 5 دقائق.

> استبدل `$ORBIT_API_KEY` بالمفتاح من الخطوة 2 (أو صدّره في shell الخاص بك). لا تلصق مفتاحك مباشرة في المقتطفات المشتركة.

## الخطوة 4: تحقق من الاستجابة

```json theme={null}
{
  "data": {
    "id": "msg_abc123",
    "status": "queued",
    "channel": "sms"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}
```

تهانينا — لقد أرسلت رسالتك الأولى مع Orbit مجانًا في أقل من 5 دقائق. يحتفظ الإرسال التجريبي بحالة `test_sent` الصادقة بدلًا من ترقيتها إلى `delivered`/`failed` — لتشغيل نتيجة إيصال تسليم محددة عند الطلب (delivered, undelivered, expired و7 أخرى)، أرسل إلى رقم مستلم ذي الرقم الأخير المطابق؛ راجع [Sandbox Magic Numbers](/sandbox/magic-numbers). اربط webhook للتسليم تاليًا: راجع [Webhooks](/webhooks/overview).

## الخطوة 5: الانتقال إلى الإنتاج

تدفق Sandbox لا يصل أبدًا إلى مشغّل حقيقي، لذلك فهو أسرع طريقة لبناء واختبار تكاملك — لكن الانتقال إلى الإنتاج يتطلب شيئين إضافيين:

1. **التحقق من KYC.** أرسل مستندات عملك تحت **Settings > KYC**. بمجرد موافقة المسؤول على مؤسستك، يُفتح الإرسال الحي — لكن Orbit يعمل بنموذج الدفع حسب الاستخدام دون رصيد تجريبي تلقائي، لذا يبقى رصيدك الحي **0\$** حتى تضيف أموالًا تحت **Settings > Billing**. تتطلب SMS (أمريكية أو دولية) وWhatsApp والصوت كلها KYC معتمدًا ورصيدًا ممولًا قبل الإرسال.
2. **تسجيل 10DLC لـ SMS الأمريكية.** يتطلب إرسال SMS إلى أرقام أمريكية عبر التدفق الحي أيضًا تسجيل علامة + حملة 10DLC — خطوة امتثال إضافية مضافة إلى KYC، وليست بديلًا عنه. راجع [Sender ID Registration](/compliance/sender-id-registration).

بمجرد الموافقة على KYC، أنشئ مفتاحًا حيًا (البادئة `dv_live_sk_`) تحت **Settings > API Keys** واستبدل به مفتاح `dv_test_sk_` الذي استخدمته أعلاه — شكل الطلب لا يتغير.