نظرة عامة على واجهة برمجة تطبيقات المراسلة v2

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

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

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

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

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

https://api.pushwoosh.com

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

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز وصول لواجهة برمجة التطبيقات (API access token) من جانب الخادم الخاص بـ Pushwoosh:

Authorization: Token YOUR_API_TOKEN

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

الأساليب (Methods)

Notify: POST /messaging/v2/notify. لإنشاء وإرسال رسالة واحدة (شريحة أو تعاملية).

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

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

بداية سريعة

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 بدلاً من استدعاء Notify مباشرة. تقوم البوابة بإعادة توجيه كل رسالة إلى واجهة برمجة التطبيقات هذه كطلب Notify تعاملي، لذا تنطبق نفس قواعد المصادقة وحمولة البريد الإلكتروني.

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

Notify

مرجع الحمولة (Payload)

مرجع حمولة البريد الإلكتروني

بوابة SMTP

الترحيل من v1