# نظرة عامة على Messaging API v2

Messaging API v2 هي نقطة نهاية REST/JSON واحدة لإنشاء رسائل صادرة عبر كل قناة يدعمها Pushwoosh:

- إشعارات الدفع: iOS, Android, Huawei, Baidu, macOS, Amazon, Windows, Safari, Chrome, Firefox, IE
- البريد الإلكتروني
- الرسائل القصيرة (SMS)
- Telegram, Kakao, LINE, WhatsApp, Viber

يتم تحديد **القناة** حسب نوع الحمولة (`payload` لإشعارات الدفع / الرسائل القصيرة / تطبيقات المراسلة، و`email_payload` للبريد الإلكتروني).

يتم تحديد **الاستهداف** حسب نوع الطلب (`segment` لشرائح الجمهور، و`transactional` لقوائم الأجهزة أو المستخدمين الصريحة).

## عنوان URL الأساسي

```
https://api.pushwoosh.com
```

إذا كنت تستخدم منطقة مخصصة أو نشرًا خاصًا، فتأكد من عنوان URL الأساسي الدقيق مع مدير نجاح العملاء في Pushwoosh.

## المصادقة

يجب أن يتضمن كل طلب ترويسة `Authorization` مع [رمز وصول API](/ar/developer/api-reference/api-access-token/#server-api-token) من جانب الخادم لـ Pushwoosh:

```
Authorization: Token YOUR_API_TOKEN
```

استخدم نفس الرمز الذي تصدره بالفعل لمكالمات API من خادم إلى خادم. لا تكشف عن هذا الرمز في تطبيقات العميل.

## الطرق (Methods)

- [`Notify`](/ar/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. إنشاء وإرسال رسالة واحدة (لشريحة أو تعاملية).
- [`Cancel`](/ar/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. إلغاء رسالة تم إنشاؤها مسبقًا ولم يتم تسليمها بعد.
- [`Update`](/ar/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. استبدال رسالة لا تزال مجدولة بتعريف جديد.

## تنسيق الطلب والاستجابة

- نوع المحتوى: `application/json`.
- تستخدم أسماء الحقول `snake_case`. تظهر مجموعات `oneof` ككائنات متداخلة مع مجموعة مفاتيح واحدة بالضبط.
- يتم تحويل قيم Enum إلى أسماء سلاسلها النصية (على سبيل المثال، `"IOS"`، `"MESSAGE_TYPE_MARKETING"`).
- تعيد الاستجابات الناجحة HTTP 200 مع جسم JSON؛ تستخدم الأخطاء غلاف الخطأ القياسي لـ gRPC-Gateway — `{ "code": ..., "message": ..., "details": [...] }`.

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

```bash title="إرسال إشعار دفع إلى شريحة"
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello from v2!" },
              "android": { "body": "Hello from v2!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## إرسال البريد الإلكتروني عبر SMTP

إذا كانت الخدمة تتحدث بالفعل ببروتوكول SMTP، فيمكنك إرسال بريد إلكتروني تعاملي عبر [بوابة SMTP](/ar/developer/api-reference/smtp-gateway/) بدلاً من استدعاء `Notify` مباشرة. تقوم البوابة بإعادة توجيه كل رسالة إلى واجهة برمجة التطبيقات هذه كـ `Notify` تعاملي، لذا تنطبق نفس قواعد المصادقة وحمولة البريد الإلكتروني.

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

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="مرجع الحمولة (Payload)" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="مرجع حمولة البريد الإلكتروني" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="بوابة SMTP" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="الترحيل من الإصدار v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>