مشغل REST

👨‍💻️ ما هو REST trigger؟

نقطة نهاية API الخاصة بـ REST trigger للحملة تتيح لك إضافة مستلمين جدد إلى أي من حملاتك فورياً باستخدام HTTP POST بسيط إلى واجهة الـ trigger.

باستخدام نقطة نهاية REST trigger API يمكنك بسهولة دمج وأتمتة نظام الحملات في ngSurvey مع أي نظام طرف ثالث يحتاج إلى إرسال دعوات استبيان فورياً. على سبيل المثال، يمكنك ربط ngSurvey بنظام تذاكر يرسل دعوات استبيان رضا فور إغلاق التذكرة.

📨 إعداد الـ Trigger

لإعداد الـ trigger تحتاج إلى إنشاء حملة قيد التشغيل، وبمجرد إعداد هذه الحملة ستتمكن من الوصول إلى رابط الـ trigger من خلال شاشة REST trigger.

ستجد هناك رابط HTTP للـ trigger الذي يمكنك استخدامه لوضع مستلمين جدد في طابور الحملة. تُمكّنك شاشة trigger للحملة أيضاً من تغيير الرسالة الافتراضية التي ستُستخدم كقالب دعوة لجميع المستلمين المطلوب إدراجهم عبر الـ trigger.

🚀 كيفية استخدام REST trigger

يتطلب نقطة النهاية API إجراء HTTP POST مع ترويسة Authorization تحتوي على API key كقيمة مسبوقة بالبادئة Bearer.

يجب أن يتم تعريف مضمون HTTP POST الخاص بك باستخدام بنية JSON التالية

{
  "recipients": string[],
  "anonymous": boolean,
  "clearExistingBatches": boolean,
  "daysThreshold": number,
  "pipeParameters": { string:string },
  "mailingTemplateId": string,
  "message": {
    "mailingFrom": string,
    "mailingFromName": string
    "mailingSubject": string
    "mailingMessage": string
 }
}

🔅 خصائص Trigger API

• recipients هي قائمة المستلمين الذين يتم إضافتهم إلى دفعة الحملة. استخدم عناوين البريد الإلكتروني إذا كانت حملتك تعتمد على البريد الإلكتروني، أو أرقام الهواتف إذا كانت تعتمد على الرسائل النصية القصيرة، واستخدم Panelist Ids إذا كانت لديك حملة قائمة على اللوحة (panel).

• anonymous لن يربط بريد المستجيب بإجابات المستجيب وسيقوم بحذف البريد الإلكتروني من قاعدة البيانات بمجرد أن يكمل المستجيب الاستبيان. هذا الخيار صالح فقط إذا كنت تستخدم الـ trigger في حملة معتمدة على البريد الإلكتروني.

• clearExistingBatches سيحذف من دفعة الإرسال أي سجل سابق للمستلم. لاحظ أنه سيزيل فقط إدخال دفعة الإرسال ولن يزيل أي إجابات استبيان.

• daysThreshold اختياري. هو عدد الأيام التي بعدها يمكن إضافة المستلم إلى دفعة الإرسال مرة أخرى. اتركه null حتى يمكن إضافة مستلمين إلى دفعة الإرسال في أي وقت. يمكنك أيضاً تعيين قيمته إلى 0 لإضافة المستلم فقط إذا لم يكن هناك أي إدخال سابق في دفعة الإرسال.

• pipeParameters اختياري. يتيح لك تعريف معلمات اسم/قيمة ديناميكية سيتم استبدالها في رسالة الدعوة.

• mailingTemplateId اختياري. يتيح لك استخدام قالب مراسلة موجود كرسالة دعوة.

• message اختياري. يتيح لك تجاوز رسالة الدعوة الافتراضية للـ trigger برسالتك الخاصة. لاحظ أنه سيقوم أيضاً بإلغاء خاصية mailingTemplateId.

إذا كنت تستخدم piping أو قوالب المراسلة أو رسالة مخصصة لـ trigger، يرجى ملاحظة أن ngSurvey سينشئ إدخال رسالة دعوة جديد في قاعدة البيانات لكل مستلم. لذلك نوصي بتعيين clearExistingBatches إلى true إذا كنت تشغّل أتمتة بعدد كبير من الاستدعاءات إلى الـ trigger تتضمن نفس المستلمين مع مرور الوقت.

إذا كنت تشغّل أتمتة بعدد كبير من الاستدعاءات إلى الـ trigger تتضمن مستلمين متكررين، نوصي بتعيين خاصية clearExistingBatches للحفاظ على سجل إدخال إرسال دفعة واحد لكل مستلم في قاعدة بيانات ngSurvey.

🚰 قيم Piping

باستخدام خاصية pipeParameters الاختيارية يمكنك تحديد مجموعة قيم ستُحقن أثناء التشغيل في رسالة الدعوة التي ستُرسَل إلى المستلمين. يجب أن تكون وسوم الـ Pipe في رسالة الدعوة بتنسيق كما يلي: [*propertyname*]

  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  }

من أجل حقن قيمة prop1 في رسالة الدعوة الخاصة بك ستحتاج إلى إضافة الوسم التالي الذي سيتم استبداله بـ value1 أثناء التشغيل.

[*prop1*]

إذا كنت تطلق الدعوة من نظام تذاكر، يمكنك على سبيل المثال حقن رقم التذكرة في رابط دعوة الاستبيان داخل رسالة الدعوة وتخزين تلك التذكرة في حقل مخفي داخل الاستبيان.

مثال CURL / Body

curl -X POST "http://yoursite/api/Campaigns/yourcampaign/trigger" -H  "accept: */*" -H  "Authorization: Bearer YOURAPIKEY" -H  "Content-Type: application/json-patch+json" -d "{\"recipients\":[\"[email protected]\",\"[email protected]\"],\"anonymous\":false,\"clearExistingBatches\":false,\"daysThreshold\":null,\"pipeParameters\":{\"prop1\":\"value1\",\"prop2\":\"value2\",\"prop3\":\"value3\"},\"message\":null,\"mailingTemplateId\":null}"

{
  "recipients": ["[email protected]", "[email protected]"],
  "anonymous": false,
  "clearExistingBatches": false,
  "daysThreshold": null,
  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  },
  "message": null,
  "mailingTemplateId": null
}