# مشغل REST

## 👨‍💻️ ما هو REST trigger؟

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

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

## 📨 إعداد الـ Trigger 

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

![](/files/d5116c5669383b4676c94b5567df9a85cd72249e)

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

![](/files/bb176fec977fa33f135b5354a09c052f4387c5e5)

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

يتطلب نقطة النهاية API إجراء HTTP POST مع ترويسة Authorization تحتوي على [API key](/ar/personal-account/developer/api-connection-sample.md) كقيمة مسبوقة بالبادئة Bearer.

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

```javascript
{
  "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. 

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

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

## 🚰 قيم Piping

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

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

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

```javascript
[*prop1*]
```

{% hint style="info" %}
إذا كنت تطلق الدعوة من نظام تذاكر، يمكنك على سبيل المثال حقن رقم التذكرة في رابط دعوة الاستبيان داخل رسالة الدعوة وتخزين تلك التذكرة في حقل مخفي داخل الاستبيان.
{% endhint %}

##  مثال CURL / Body

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

```typescript
{
  "recipients": ["email1@domain.com", "email2@domain.ch"],
  "anonymous": false,
  "clearExistingBatches": false,
  "daysThreshold": null,
  "pipeParameters": {
    "prop1": "value1",
    "prop2": "value2",
    "prop3": "value3"
  },
  "message": null,
  "mailingTemplateId": null
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ngsurvey.com/ar/form-management/campaigns/rest-trigger.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.