# أحداث webhook في مُجيب: كل حدث وحقوله

> أحداث webhook في مُجيب بالتفصيل، أي متى يُرسل كل حدث وما الحقول التي يحملها وقيمها الممكنة، مع مثال JSON كامل لكل حدث ولحدث التجربة.

أحداث webhook في مُجيب 5، هي contact.created، booking.created، booking.cancelled، conversation.handoff وmessage.received. يصل كل حدث بالغلاف نفسه، وتختلف حقول `data` بحسب نوعه. هذه الصفحة مرجع لكل حقل؛ أما الإعداد وإعادة المحاولة والرد المطلوب ففي صفحة [webhook واتساب](https://docs.mujib.ai/developers/webhooks/).

القيم التي ليس لها معنى في حدث ما تصل `null` ولا تُحذف من الجسم. واكتب مستقبِلك بحيث يتجاهل أي حقل لا يعرفه.

## ما الحقول المشتركة بين كل الأحداث؟

كل حدث كائن JSON فيه خمسة حقول ثابتة، والتفاصيل كلها داخل `data`.

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `id` | نص (UUID) | معرّف الحدث، وهو نفسه في كل Webhook يستقبل الحدث ذاته |
| `type` | نص | نوع الحدث، ومطابق للترويسة `X-Mujib-Event` |
| `createdAt` | نص | وقت وقوع الحدث بتوقيت UTC، مثل `2026-01-01T09:30:00.000Z` |
| `workspaceId` | نص (UUID) | معرّف نشاطك في مُجيب، وهو ثابت في كل أحداثك |
| `data` | كائن | تفاصيل الحدث، كما في الأقسام التالية |

يقرأ مُجيب البيانات مرة واحدة بعد وقوع الحدث بلحظات، وتحمل كل إعادة محاولة للإرسال الجسم نفسه. وإذا حُذف ما يتعلق به الحدث قبل ذلك فلا يُرسل شيء.

## ما الحقول التي يحملها حدث `contact.created`؟

يُرسل حدث «عميل جديد» مرة واحدة لكل عميل جديد: عند أول رسالة من مُرسِل جديد على واتساب أو إنستغرام أو ماسنجر، أو عندما تراسل من هاتف نشاطك رقمًا ليس عميلًا بعد، أو عندما يضيف أحد الفريق عميلًا من اللوحة.

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `data.contact.id` | نص (UUID) | معرّف العميل في مُجيب |
| `data.contact.name` | نص أو `null` | اسم العميل المحفوظ |
| `data.contact.phone` | نص أو `null` | رقمه كما هو محفوظ، مثل `962790000000`. يكون غالبًا `null` لعملاء ماسنجر وإنستغرام |
| `data.contact.channel` | نص | القناة التي جاء منها: `whatsapp` أو `instagram` أو `facebook` لماسنجر، أو `manual` إذا أضافه الفريق |
| `data.contact.stage` | نص | مرحلة العميل: `new` أو `engaged` أو `qualified` أو `won` أو `lost` |
| `data.contact.createdAt` | نص | أول ظهور للعميل بتوقيت UTC |

```json
{
  "id": "5d7c1e2a-3b4f-4c6d-9e8f-0a1b2c3d4e5f",
  "type": "contact.created",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "contact": {
      "id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8",
      "name": "سارة",
      "phone": "962790000000",
      "channel": "whatsapp",
      "stage": "new",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  }
}
```

## ما الحقول التي يحملها حدثا `booking.created` و`booking.cancelled`؟

يحمل الحدثان الحقول نفسها في `data.booking`: يُرسل «حجز جديد» عندما يحجز الوكيل موعدًا أو يضيفه الفريق في التقويم، ويُرسل «انلغى حجز» عندما يُلغى موعد. الحجز المتكرر يرسل حدثًا لكل موعد فيه.

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `id` | نص (UUID) | معرّف الحجز |
| `status` | نص | `requested` أو `confirmed` أو `cancelled` أو `completed` أو `no_show` |
| `source` | نص | من أنشأه: `agent` للوكيل أو `staff` للفريق |
| `service` | نص | رمز نوع الزيارة كما عرّفه نشاطك |
| `startsAt` | نص | لحظة البداية بتوقيت UTC، مثل `2026-11-02T14:30:00Z` |
| `localTime` | نص | وقت البداية بتوقيت الفرع ومن دون منطقة زمنية، مثل `2026-11-02T17:30:00` |
| `timezone` | نص | المنطقة الزمنية للفرع، مثل `Asia/Amman` |
| `durationMinutes` | عدد أو `null` | مدة الموعد بالدقائق، و`null` تعني المدة الافتراضية لنشاطك |
| `branch` | كائن أو `null` | الفرع: `id` و`name` |
| `specialist` | نص أو `null` | اسم الأخصائي إن عُيّن |
| `customer` | كائن | `contactId` و`name` و`phone`. يكون `contactId` قيمة `null` إذا لم يرتبط الحجز بعميل في مُجيب |
| `createdAt` | نص | وقت إنشاء الحجز بتوقيت UTC |

```json
{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "type": "booking.created",
  "createdAt": "2026-11-01T08:15:02.441Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "booking": {
      "id": "b7e6d5c4-b3a2-4910-8f7e-6d5c4b3a2910",
      "status": "confirmed",
      "source": "agent",
      "service": "consultation",
      "startsAt": "2026-11-02T14:30:00Z",
      "localTime": "2026-11-02T17:30:00",
      "timezone": "Asia/Amman",
      "durationMinutes": 30,
      "branch": { "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "الفرع الرئيسي" },
      "specialist": "ليلى",
      "customer": { "contactId": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8", "name": "سارة", "phone": "962790000000" },
      "createdAt": "2026-11-01T08:15:01.982Z"
    }
  }
}
```

> **أي وقت أعرض؟**
>
> اعرض `localTime` لموظفي الفرع كما هو، واستخدم `startsAt` للحساب والمقارنة بين الفروع.
## ما الحقول التي يحملها حدث `conversation.handoff`؟

يُرسل حدث «تحويل لموظف» مرة واحدة لكل تحويل إلى موظف، ومنه التحويل الذي يحدث لأن الوكيل تعذّر عليه الرد.

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `data.conversation.id` | نص (UUID) | معرّف المحادثة |
| `data.conversation.channel` | نص | `whatsapp` أو `instagram` أو `facebook` |
| `data.conversation.reason` | نص أو `null` | سبب التحويل: رمز قصير أو جملة كتبها الوكيل بلغة المحادثة. اعرضه كما هو ولا تبنِ عليه شروطًا ثابتة |
| `data.contact` | كائن أو `null` | العميل: `id` و`name` و`phone` |

```json
{
  "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "type": "conversation.handoff",
  "createdAt": "2026-11-01T10:02:47.120Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "conversation": {
      "id": "f0e1d2c3-b4a5-4697-8879-6a5b4c3d2e1f",
      "channel": "whatsapp",
      "reason": "العميلة تطلب عرض سعر خاص لمجموعة"
    },
    "contact": { "id": "c1a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8", "name": "سارة", "phone": "962790000000" }
  }
}
```

## ما الحقول التي يحملها حدث `message.received`؟

يُرسل حدث «رسالة جديدة» مع كل رسالة يرسلها عميل على أي قناة، ويحمل نصها فقط من دون أي ملف.

| الحقل | النوع | المعنى |
| --- | --- | --- |
| `data.message.id` | نص (UUID) | معرّف الرسالة |
| `data.message.conversationId` | نص (UUID) | معرّف المحادثة |
| `data.message.channel` | نص | `whatsapp` أو `instagram` أو `facebook` |
| `data.message.type` | نص | نوع الرسالة، مثل `text` و`image` و`audio` و`video` و`document` و`location` |
| `data.message.text` | نص أو `null` | نص الرسالة، أو نص الرسالة الصوتية بعد تحويله إلى كتابة إن توفر، ويُقص بعد 4000 حرف. يكون `null` لبقية الأنواع |
| `data.message.createdAt` | نص | وقت استلام الرسالة بتوقيت UTC |
| `data.contact` | كائن أو `null` | العميل: `id` و`name` و`phone` |

```json
{
  "id": "8e9f0a1b-2c3d-4e5f-9a6b-7c8d9e0f1a2b",
  "type": "message.received",
  "createdAt": "2026-11-01T18:40:11.305Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "message": {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "conversationId": "f0e1d2c3-b4a5-4697-8879-6a5b4c3d2e1f",
      "channel": "instagram",
      "type": "text",
      "text": "هل يوجد موعد غدًا مساءً؟",
      "createdAt": "2026-11-01T18:40:11.298Z"
    },
    "contact": { "id": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f6a", "name": "سارة", "phone": null }
  }
}
```

> **نص العملاء بيانات شخصية**
>
> حدث الرسالة يحمل كلام عملائك كما كتبوه. اشترك فيه فقط إذا احتاجه نظامك، واحفظه بالعناية التي تحفظ بها محادثاتك.
## كيف يبدو حدث التجربة `webhook.test`؟

حدث التجربة يصل حين تضغط «أرسل تجربة»، وهو موقّع بالسر نفسه مثل الأحداث الحقيقية، فيصلح لاختبار التحقق من التوقيع.

- يصل إلى الـ Webhook الذي ضغطت فيه الزر وحده، بمحاولة واحدة بلا إعادة.
- لا يظهر في قائمة الأحداث التي تشترك فيها، ويظهر في السجل باسم «إرسال تجربة».

```json
{
  "id": "0f1e2d3c-4b5a-4968-8776-5a4b3c2d1e0f",
  "type": "webhook.test",
  "createdAt": "2026-11-01T12:00:00.000Z",
  "workspaceId": "7f3e9a10-2c4b-4d5e-8f60-71829a0b1c2d",
  "data": {
    "test": true,
    "message": "This is a test delivery from Mujib. Your endpoint received and can verify it."
  }
}
```

## الأسئلة الشائعة

### هل يوجد حدث لتغيير موعد الحجز؟

لا. تغيير الوقت أو الأخصائي لا يرسل حدثًا. لمعرفة آخر حالة للحجز اقرأه من واجهة مُجيب البرمجية بمعرّفه.

### لماذا يصل رقم الهاتف فارغًا أحيانًا؟

لأن ماسنجر وإنستغرام لا يعطيان رقم هاتف العميل، فيبقى phone قيمة null ما لم يُحفظ له رقم في مُجيب.

### هل تصل ردود الوكيل في حدث message.received؟

لا. الحدث للرسائل الواردة من العملاء وحدها، أما ردود الوكيل والفريق فلا تُرسل.

### ما الفرق بين id في الجسم والترويسة X-Mujib-Delivery؟

id يعرّف الحدث، وهو نفسه في كل Webhook يستقبله. أما X-Mujib-Delivery فيعرّف إرسالًا واحدًا إلى Webhook واحد، ويبقى ثابتًا في إعادة المحاولة.

---

المصدر: https://docs.mujib.ai/developers/webhook-events/ · آخر تحديث: 2026-11-04