معلمات /createMessage

تم إيقافه

تم إيقاف /createMessage. يجب أن تستخدم عمليات الدمج الجديدة Messaging API v2 — راجع دليل الترحيل للحصول على تخطيط حقلي للمعلمات أدناه.

ستجد هنا أوصاف معلمات واجهة برمجة التطبيقات /createMessage.

• يجب تضمين المعلمات المطلوبة لإرسال طلب واجهة برمجة التطبيقات /createMessage بنجاح وبث إشعار فوري في الوقت المحدد.

• تسمح لك المعلمات الاختيارية بتخصيص خصائص الإشعارات الفورية.

ملاحظة

إذا كنت تستخدم /createMessage لإرسال رسائل SMS، يرجى الرجوع إلى معلمات إرسال رسائل SMS. لن يتم تمرير المعلمات الأخرى.

المعلمات المطلوبة

المعلمات المطلوبة إلزامية للاستخدام في طلبات /createMessage. وإلا، لن يتم تقديم الطلب.

application

رمز فريد لتطبيق تم إنشاؤه في حساب Pushwoosh الخاص بك. يمكن العثور على رمز التطبيق في الزاوية العلوية اليسرى من لوحة التحكم أو في استجابة لطلب /createApplication. رمز التطبيق هو مجموعة من 10 أحرف (حروف وأرقام) مفصولة بشرطات.

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

للحصول على رمز تطبيق تم إنشاؤه مسبقًا عبر واجهة برمجة التطبيقات، استدعِ /getApplications. في استجابة لطلب /getApplications، ستتلقى قائمة بجميع التطبيقات التي تم إنشاؤها في حساب Pushwoosh الخاص بك مع أسمائها ورموزها.

auth

رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh. انتقل إلى الإعدادات → الوصول إلى API وانسخ رمزًا ترغب في استخدامه أو أنشئ رمزًا جديدًا.

عند إنشاء رمز وصول، حدد أذوناته. حدد مربعات الاختيار لأنواع الأنشطة التي ستستخدم رمز API معها. يمكنك إنشاء رموز API خاصة بالتطبيق عن طريق تحديد مربعات اختيار التطبيقات.

content

السلسلة النصية أو الكائن الذي يحدد محتوى الرسالة. سيؤدي إرسال المعلمة “content” بقيمة من نوع سلسلة نصية إلى إرسال نفس الرسالة لجميع المستلمين.

String

"content": "Hello world!",

تُستخدم كائنات JSON لتحديد المحتوى باستخدام المحتوى الديناميكي (Dynamic Content)، على سبيل المثال، للرسائل متعددة اللغات.

Object

"content": {
  "en": "Hello!",
  "es": "¡Hola!",
  "de": "Hallo!"
},

notifications

مصفوفة JSON لخصائص الإشعارات الفورية. يجب أن تتضمن على الأقل المعلمتين المطلوبتين content وsend_date.

المعلمات الاختيارية للاستخدام داخل مصفوفة “notifications”:

• campaign
• capping_days
• capping_count
• conditions
• data
• devices
• dynamic_content
• filter
• ignore_user_timezone
• inbox_date
• inbox_image
• link
• minimize_link
• message_type
• platforms
• preset
• rich_media
• send_rate
• timezone
• template_bindings
• transactionId
• users

send_date

التاريخ والوقت الذي يتم فيه إرسال الرسالة. يمكن أن يكون أي تاريخ ووقت بالتنسيق YYYY-MM-DD HH:mm أو ‘now’. إذا تم تعيينه على ‘now’، فسيتم إرسال الرسالة فورًا بعد تقديم الطلب.

المعلمات الاختيارية

campaign

رمز الحملة (Campaign). للحصول على رمز الحملة، انتقل إلى الإحصائيات → الإحصائيات المجمعة وحدد الحملة التي ستستخدمها. سيكون رمز الحملة مرئيًا في نهاية عنوان URL للصفحة بالتنسيق XXXXX-XXXXX.

مثال:

URL: https://app.pushwoosh.com/applications/AAAAA-AAAAA/statistics/aggregated-message?campaignCode=XXXXX-XXXXX

رمز الحملة: XXXXX-XXXXX

للحصول على قائمة بالحملات مع رموزها، استدعِ /getCampaigns. في استجابة لطلب /getCampaigns، ستتلقى قائمة بجميع الحملات التي تم إنشاؤها لتطبيق معين في حساب Pushwoosh الخاص بك، مع رموزها وأسمائها وأوصافها.

capping_days

الفترة التي سيتم تطبيق تحديد التكرار عليها، بالأيام (بحد أقصى 30 يومًا). راجع تحديد التكرار (Frequency capping) للحصول على التفاصيل.

لا يتم تطبيق تحديد التكرار على الرسائل ذات message_type: transactional. في جميع الحالات الأخرى، يتم تطبيق تحديد التكرار، بما في ذلك الطلبات التي يتم فيها حذف message_type.

capping_count

الحد الأقصى لعدد الإشعارات الفورية التي يمكن إرسالها من تطبيق معين إلى جهاز معين خلال فترة “capping_days”. في حالة تجاوز الرسالة التي تم إنشاؤها حد “capping_count” لجهاز ما، فلن يتم إرسالها إلى ذلك الجهاز. راجع تحديد التكرار (Frequency capping) للحصول على التفاصيل.

conditions

الشروط هي مصفوفات مثل [tagName, operator, operand] تُستخدم لإرسال رسائل مستهدفة بناءً على الوسوم (Tags) وقيمها، حيث:

• tagName — اسم الوسم المراد تطبيقه،
• operator — عامل مقارنة قيمة (“EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN” | “NOTSET” | “ANY”)،
• operand — قيم الوسم من أي من الأنواع التالية: string | integer | array | date | boolean | list

وصف العامل

EQ	قيمة الوسم تساوي المعامل.
IN	قيمة الوسم تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة).
NOTEQ	قيمة الوسم لا تساوي المعامل.
NOTIN	قيمة الوسم لا تتقاطع مع المعامل (يجب أن يكون المعامل دائمًا مصفوفة).
GTE	قيمة الوسم أكبر من أو تساوي المعامل.
LTE	قيمة الوسم أصغر من أو تساوي المعامل.
BETWEEN	قيمة الوسم أكبر من أو تساوي قيمة المعامل الدنيا ولكنها أصغر من أو تساوي قيمة المعامل القصوى (يجب أن يكون المعامل دائمًا مصفوفة).
NOTSET	الوسم غير معين. لا يتم النظر في المعامل.
ANY	الوسم له أي قيمة. لا يتم النظر في المعامل.

وسوم السلاسل النصية

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN, NOTSET, ANY

المعاملات الصالحة:

EQ, NOTEQ	يجب أن يكون المعامل سلسلة نصية
IN, NOTIN	يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل ["value 1", "value 2", "value N"]
NOTSET	الوسم غير معين. لا يتم النظر في المعامل
ANY	الوسم له أي قيمة. لا يتم النظر في المعامل

وسوم الأعداد الصحيحة

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY

المعاملات الصالحة:

EQ, NOTEQ, GTE, LTE	يجب أن يكون المعامل عددًا صحيحًا
IN, NOTIN	يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل [value 1, value 2, value N]
BETWEEN	يجب أن يكون المعامل مصفوفة من الأعداد الصحيحة مثل [min_value, max_value]
NOTSET	الوسم غير معين. لا يتم النظر في المعامل
ANY	الوسم له أي قيمة. لا يتم النظر في المعامل

وسوم التاريخ

العوامل الصالحة: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE, NOTSET, ANY

المعاملات الصالحة:

• "YYYY-MM-DD 00:00" (سلسلة نصية)
• الطابع الزمني يونكس 1234567890 (عدد صحيح)
• "N days ago" (سلسلة نصية) للعوامل EQ, BETWEEN, GTE, LTE

وسوم القيم المنطقية

العوامل الصالحة: EQ, NOTSET, ANY

المعاملات الصالحة: 0, 1, true, false

وسوم القوائم

العوامل الصالحة: IN, NOTIN, NOTSET, ANY

المعاملات الصالحة: يجب أن يكون المعامل مصفوفة من السلاسل النصية مثل ["value 1", "value 2", "value N"].

هام

تذكر أنه لا ينبغي استخدام معلمتي “filter” و “conditions” معًا.
أيضًا، سيتم تجاهلهما كليهما إذا تم استخدام معلمة “devices” في نفس الطلب.

وسوم البلد واللغة

قيمة وسم اللغة هي رمز من حرفين صغيرين وفقًا لـ ISO-639-1. قيمة وسم البلد هي رمز من حرفين كبيرين وفقًا لـ ISO_3166-2.

على سبيل المثال، لإرسال إشعار فوري إلى المشتركين الناطقين بالبرتغالية في البرازيل، ستحتاج إلى تحديد الشرط التالي: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

conditions_operator

عامل منطقي لمصفوفات الشروط. القيم الممكنة: AND | OR. القيمة الافتراضية هي AND.

إذا كان العامل المطبق هو AND (عند عدم تحديد عامل، أو عندما تكون قيمة المعلمة ‘conditions_operator’ هي ‘AND’)، فإن الأجهزة التي تمتثل لجميع الشروط في نفس الوقت ستتلقى الإشعار الفوري.

إذا كان العامل هو OR، فإن الأجهزة التي تمتثل لأي من الشروط المحددة ستتلقى الرسالة.

data

سلسلة JSON أو كائن JSON يُستخدم لتمرير أي بيانات مخصصة في حمولة الإشعار الفوري؛ يتم تمريرها كمعلمة “u” في الحمولة (محولة إلى سلسلة JSON).

devices

مصفوفة من رموز الإشعارات الفورية (push tokens) أو معرفات الأجهزة (hwids) لإرسال إشعارات فورية مستهدفة. إذا تم تعيينها، فسيتم إرسال الرسالة فقط إلى الأجهزة الموجودة في القائمة.

dynamic_content

عناصر نائبة لـ المحتوى الديناميكي (Dynamic Content) لاستخدامها بدلاً من قيم وسوم الجهاز. المثال أدناه سيرسل رسالة “Hello, John!” إلى كل مستخدم تستهدفه. إذا لم يتم تعيينها، يتم أخذ قيم المحتوى الديناميكي من وسوم الجهاز.

"content": "Hello, {firstname|CapitalizeFirst}!",
"dynamic_content_placeholders": {
  "firstname": "John",
  "lastname": "Doe"
},

filter

اسم الشريحة (Segment) تمامًا كما تم إنشاؤه في لوحة تحكم Pushwoosh أو عبر طلب واجهة برمجة التطبيقات /createFilter. انتقل إلى قسم الجمهور → الشرائح وتحقق من قائمة الشرائح التي تم إنشاؤها.

للحصول على قائمة الشرائح عبر واجهة برمجة التطبيقات، استدعِ طريقة واجهة برمجة التطبيقات /listFilters. في استجابة لطلب /listFilters، ستتلقى قائمة بجميع الشرائح التي تم إنشاؤها في حساب Pushwoosh الخاص بك، مع أسماء الشرائح وشروطها وتواريخ انتهاء صلاحيتها.

ignore_user_timezone

إذا تم تعيينه على ‘true’، يرسل الرسالة في الوقت والتاريخ المحددين في معلمة “send_date” وفقًا لـ UTC-0.

إذا تم تعيينه على ‘false’، سيتلقى المستخدمون الرسالة في الوقت المحلي المحدد وفقًا لإعدادات أجهزتهم.

inbox_date

التاريخ الذي يجب أن تبقى فيه الرسالة في صندوق الوارد (Inbox) الخاص بالمستخدمين. إذا لم يتم تحديده، فستتم إزالة الرسالة من صندوق الوارد في اليوم التالي لتاريخ الإرسال.

ملاحظة

لحفظ الرسالة في صندوق الوارد، استخدم معلمة واحدة على الأقل من معلمات ‘inbox’: “inbox_date” أو “inbox_image”.

تنبيه

ستتم إزالة الرسالة من صندوق الوارد في الساعة 00:00:01 من التاريخ المحدد، لذا فإن التاريخ السابق هو آخر يوم يمكن للمستخدم رؤية الرسالة فيه في صندوق الوارد الخاص به.

inbox_image

عنوان URL للصورة المخصصة التي سيتم عرضها بجوار الرسالة في صندوق الوارد (Inbox).

ملاحظة

لحفظ الرسالة في صندوق الوارد، استخدم معلمة واحدة على الأقل من معلمات ‘inbox’: “inbox_date” أو “inbox_image”.

inbox_days

عمر رسالة صندوق الوارد بالأيام، حتى 30 يومًا. بعد هذه الفترة، ستتم إزالة الرسالة من صندوق الوارد. يمكن استخدامها بدلاً من معلمة inbox_date.

link

عنوان URL الذي سيتم فتحه بمجرد أن يفتح المستخدم إشعارًا فوريًا.

message_type

يحدد نوع رسالة الإشعار الفوري. القيم المتاحة هي marketing و transactional. راجع الرسائل التسويقية مقابل الرسائل الحركية للحصول على التفاصيل.

هذه المعلمة اختيارية. إذا تم حذفها، يتم التعامل مع الرسالة على أنها حركية ويتم تسليمها للجميع، بما في ذلك المجموعة الضابطة. لا يتم تسليم الرسائل التسويقية لأعضاء المجموعة الضابطة (control group).

minimize_link

مُختصِر لتقصير عنوان URL المقدم في معلمة “link”. يرجى ملاحظة أن حجم حمولة الإشعار الفوري محدود، لذا فكر في إنشاء عناوين URL قصيرة حتى لا تتجاوز الحد المسموح به. القيم المتاحة: 0 — لا تقصر، 2 — bitly. الافتراضي = 2. تم تعطيل مُختصِر عناوين URL من Google منذ 30 مارس 2019.

platforms

مصفوفة رموز المنصات لإرسال الرسالة إلى منصات محددة فقط.

تتضمن رموز المنصات المتاحة: 1 — iOS، 3 — Android، 7 — Mac OS X، 8 — Windows، 9 — Amazon، 10 — Safari، 11 — Chrome، 12 — Firefox، 14 — Email، 17 — Huawei، 18 — SMS، و 21 — WhatsApp.

preset

رمز الإعداد المسبق (Preset) الذي تم إنشاؤه في لوحة تحكم Pushwoosh أو عبر واجهة برمجة التطبيقات. للحصول على رمز الإعداد المسبق، انتقل إلى المحتوى → الإعدادات المسبقة، وقم بتوسيع الإعداد المسبق الذي ستستخدمه، وانسخ رمز الإعداد المسبق من تفاصيل الإعداد المسبق.

rich_media

رمز صفحة الوسائط الغنية (Rich Media) التي ستقوم بإرفاقها برسالتك. للحصول على رمز، انتقل إلى المحتوى → الوسائط الغنية، وافتح صفحة الوسائط الغنية التي ستستخدمها، وانسخ الرمز من شريط عنوان URL في متصفحك. الرمز هو مجموعة من 10 أحرف (حروف وأرقام) مفصولة بشرطات.

send_rate

التحكم في سرعة إرسال الإشعارات الفورية. القيم الصالحة هي من 100 إلى 1000 إشعار فوري/ثانية.

timezone

المنطقة الزمنية التي يجب أخذها في الاعتبار عند إرسال الرسالة في تاريخ ووقت معينين. إذا تم تعيينها، يتم تجاهل المنطقة الزمنية للجهاز. إذا تم تجاهلها، يتم إرسال الرسالة بتوقيت UTC. راجع https://php.net/manual/timezones.php للمناطق الزمنية المدعومة.

template_bindings

عناصر نائبة للقالب لاستخدامها في قالب المحتوى الخاص بك. راجع دليل قوالب Liquid للحصول على التفاصيل.

transactionId

معرف رسالة فريد لمنع تكرار الرسائل في حالة حدوث مشاكل في الشبكة. يمكنك تعيين أي معرف لرسالة تم إنشاؤها عبر طلب /createMessage أو /createTargetedMessage. يتم تخزينه على جانب Pushwoosh لمدة 5 دقائق.

use_latest_user_device

إذا تم تعيينه على true، فإنه يسلم إشعارًا فوريًا واحدًا لكل مستخدم بدلاً من واحد لكل جهاز: فقط الجهاز الذي لديه أحدث “آخر فتح للتطبيق” بين المنصات في platforms هو الذي يستقبله. إذا لم يكن لدى أي من أجهزة المستخدم على تلك المنصات هذه البيانات، فإن أول جهاز مطابق يحصل عليه بدلاً من ذلك، لذلك لا يتم إسقاط الإرسال أبدًا. لا تتأثر الأجهزة التي لا تحتوي على User ID. ينطبق بغض النظر عن كيفية استهداف الجمهور — بواسطة users أو filter أو conditions. يعمل بنفس طريقة use_latest_user_device في Messaging API v2. الافتراضي هو false (إرسال إلى كل جهاز).

users

مصفوفة من معرفات المستخدمين (userIds). User ID هو معرف مستخدم فريد يتم تعيينه بواسطة طلب واجهة برمجة التطبيقات /registerUser أو /registerDevice أو /registerEmail.