Developers — AwnCare

نظرة عامة

الاستقبال هو الموصّل الوارد الشامل. وجّه إليه أي أداة تستطيع إرسال طلب HTTP POST، فيصبح كل طلب رسالة في صندوق الوارد أو تذكرة دعم.

بخلاف الويبهوك الصادر (الذي يُشعرك)، يستقبل الاستقبال بيانات منك. يوفّره تكامل الويبهوك في مركز التكاملات.

إنشاء النقطة

من لوحة التحكم، افتح التكاملات، وأضِف موصّل الويبهوك، وانسخ عنوان نقطته وسرّها. لكل تكامل معرّفه وسرّه.

احرس السر

يُمرَّر السر كمعامل استعلام ويصرّح للنقطة. أبقِ العنوان الكامل خاصًا وبدّله إن تسرّب.

النقطة والحمولة

أرسل POST مع معرّف التكامل في المسار والسر في سلسلة الاستعلام.

POST/api/webhooks/integrations/{id}?secret=…

الحمولة

جسم JSON يصف المُرسِل والمحتوى.

الحقل	النوع	الوصف
`type`	`"message" \| "ticket"`	message (الافتراضي) يوجّه إلى الوارد؛ ticket يفتح تذكرة دعم.
`body`مطلوب	`string`	جسم الرسالة أو التذكرة. مطلوب.
`subject`	`string`	موضوع اختياري؛ للرسائل يُضاف إلى بداية الجسم.
`visitor.name`	`string`	اسم المُرسِل.
`visitor.email`	`string`	بريد المُرسِل (يُستخدم لمطابقة أو إنشاء جهة الاتصال).
`visitor.phone`	`string`	هاتف المُرسِل.
`visitor.externalId`	`string`	معرّف ثابت من نظامك؛ الطريقة المفضّلة لمطابقة جهة الاتصال.
`meta`	`object`	بيانات وصفية حرة مرفقة بالعنصر المستقبَل.

يُحلّ المُرسِل عبر externalId ثم البريد ثم الهاتف. وبدون أيٍّ منها، يُنشئ كل طلب زائرًا مجهولًا جديدًا.

إرسال رسالة

عيّن type إلى "message" (الافتراضي) لتوجيه الجسم إلى محادثة في صندوق الوارد المشترك.

bash

curl -X POST \
  "https://awn.care/api/webhooks/integrations/int_abc?secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "visitor": {
      "name": "Sara",
      "email": "[email protected]",
      "phone": "+966500000000",
      "externalId": "usr_10294"
    },
    "subject": "Order #1043",
    "body": "أين طلبي؟"
  }'

تُعيد استجابة 200 معرّفَي المحادثة والرسالة المُنشأين.

json

{
  "ok": true,
  "kind": "message",
  "conversationId": "cnv_8f2a",
  "messageId": "msg_10"
}

إنشاء تذكرة

عيّن type إلى "ticket" لفتح تذكرة دعم بدلًا من ذلك. يكون الموضوع افتراضيًا أول 80 حرفًا من الجسم.

bash

curl -X POST \
  "https://awn.care/api/webhooks/integrations/int_abc?secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ticket",
    "visitor": { "name": "Sara", "email": "[email protected]" },
    "subject": "Cannot log in",
    "body": "500 error on sign-in since this morning."
  }'

تُعيد استجابة 200 معرّف التذكرة الجديدة ورقمها.

json

{
  "ok": true,
  "kind": "ticket",
  "ticketId": "tkt_5",
  "ticketNumber": 1043
}

Zapier و Make والمخصّص

تعمل أي منصة تستطيع إرسال POST بجسم JSON — أضِف إجراء ويبهوك، والصق عنوان النقطة (مع السر)، واربط حقولك.

في Zapier أو Make، اختر إجراء ويبهوك "POST JSON" واربط حقول مُشغّلك بـ visitor و subject و body.