أنواع الأحداث
كل حدث يمكن لنقطة استقبال الاشتراك فيه. جسم كل طلب هو كائن الحدث، وdata.object هو المورد نفسه الذي تُرجعه الواجهة.
message.*5
message.receivedالعنصر: messageأرسل عميل رسالة إلى أحد أرقامك. data.object هي الرسالة الواردة message.
{
"id": "evt_01j9x7q8r9s0t1v2w3x4y5z6a7",
"object": "event",
"type": "message.received",
"version": "2",
"created_at": "2026-10-01T09:29:12Z",
"livemode": true,
"workspace_id": "ws_12",
"data": {
"object": {
"id": "imsg_88213",
"object": "message",
"livemode": true,
"direction": "inbound",
"channel": "whatsapp",
"from": "+966501234567",
"to": "+966112345678",
"type": "text",
"text": {
"body": "مرحبا، أين طلبي؟"
},
"status": "received",
"error": null,
"reference": null,
"conversation_id": null,
"provider_message_id": "wamid.HBgMOTY2NTAxMjM0NTY3FQIAEhgUM0E",
"contact": {
"name": "Sara"
},
"context": null,
"created_at": "2026-10-01T09:29:10Z",
"updated_at": "2026-10-01T09:29:12Z"
}
}
}message.sentالعنصر: messageأرسل واتساب رسالتك. data.previous_attributes.status هي الحالة السابقة.
message.deliveredالعنصر: messageوصلت رسالتك إلى هاتف العميل.
{
"id": "evt_01j9x7r2m3n4p5q6r7s8t9v0w1",
"object": "event",
"type": "message.delivered",
"version": "2",
"created_at": "2026-10-01T09:30:04Z",
"livemode": true,
"workspace_id": "ws_12",
"data": {
"object": {
"id": "msg_48213",
"object": "message",
"livemode": true,
"direction": "outbound",
"channel": "whatsapp",
"from": "+966112345678",
"to": "+966501234567",
"type": "text",
"text": {
"body": "أهلًا سارة! طلبك جاهز للاستلام 🎉"
},
"status": "delivered",
"error": null,
"reference": "order-10482",
"conversation_id": "conv_311",
"provider_message_id": "wamid.HBgMOTY2NTAxMjM0NTY3FQIAERgSMEM4",
"created_at": "2026-10-01T09:30:00Z",
"updated_at": "2026-10-01T09:30:04Z"
},
"previous_attributes": {
"status": "sent"
}
}
}message.readالعنصر: messageفتح العميل رسالتك. يصل فقط إذا كان العميل يشارك إشعارات القراءة.
message.failedالعنصر: messageتعذّر تسليم رسالتك. يحمل data.object.error رمز واتساب والسبب (مثل 131026 غير قابلة للتسليم، و131047 خارج نافذة الـ24 ساعة).
contact.*5
contact.createdالعنصر: contactأُضيفت جهة اتصال واتساب، من المنصة أو الاستيراد أو تدفق أو الواجهة. data.object هي جهة الاتصال contact مع وسومها وحقولها المخصصة.
{
"id": "evt_01j9x8a1b2c3d4e5f6g7h8j9k0",
"object": "event",
"type": "contact.created",
"version": "2",
"created_at": "2026-10-01T10:02:03Z",
"livemode": true,
"workspace_id": "ws_12",
"data": {
"object": {
"id": "ct_1052",
"object": "contact",
"phone": "+966501234567",
"email": "sara@example.com",
"first_name": "سارة",
"last_name": "القحطاني",
"language": "ar",
"country": "SA",
"city": "الرياض",
"gender": null,
"birth_date": null,
"notes": null,
"opted_in": true,
"consent": {
"source": "website_form",
"captured_at": "2026-10-01T10:02:00Z"
},
"opted_out_at": null,
"bot_enabled": true,
"tags": [
{
"id": "tag_12",
"name": "عملاء VIP"
}
],
"fields": {
"loyalty_points": "120"
},
"created_at": "2026-10-01T10:02:00Z",
"updated_at": "2026-10-01T10:02:00Z"
}
}
}contact.updatedالعنصر: contactتغيّرت بيانات جهة اتصال أو وسومها أو حقولها المخصصة. عدة تغييرات سريعة على جهة الاتصال نفسها تصل كحدث واحد يحمل الحالة النهائية.
contact.deletedالعنصر: contactحُذفت جهة اتصال. data.object هي {id, object: "contact", deleted: true}: حُذفت البيانات، فاحذف نسختك أيضًا.
{
"id": "evt_01j9x8b1c2d3e4f5g6h7j8k9m0",
"object": "event",
"type": "contact.deleted",
"version": "2",
"created_at": "2026-10-02T08:00:00Z",
"livemode": true,
"workspace_id": "ws_12",
"data": {
"object": {
"id": "ct_1052",
"object": "contact",
"deleted": true
}
}
}contact.opted_outالعنصر: contactطلبت جهة اتصال إيقاف رسائل الأعمال (أرسلت "إيقاف" أو ألغى أحدهم اشتراكها). تُلغى رسائل الحملات المجدولة لها، فأوقف مراسلتها من أنظمتك أيضًا.
contact.opted_inالعنصر: contactوافقت جهة اتصال كانت قد ألغت اشتراكها على رسائل الأعمال من جديد (أرسلت "ابدأ" أو سُجّلت موافقتها). يوضّح consent.source كيف تمت الموافقة.
template.*1
template.status_changedالعنصر: templateاعتمد واتساب أحد قوالبك أو رفضه أو أوقفه مؤقتًا أو عطّله. data.object هو القالب template، وdata.previous_attributes.status حالته السابقة، وrejection_reason سبب الرفض إن ذكره واتساب.
campaign.*6
campaign.startedالعنصر: campaignبدأت حملة الإرسال، أو جُدولت له. data.object هي الحملة campaign.
campaign.pausedالعنصر: campaignتم إيقاف حملة مؤقتًا، مثلًا لأن Meta قيّد رقم الإرسال. يوضح hold_reason السبب، واستأنفها عبر POST /v1/campaigns/{id}/resume بعد إصلاحه. data.object هي الحملة campaign.
campaign.resumedالعنصر: campaignعادت حملة متوقفة إلى الإرسال. data.object هي الحملة campaign.
campaign.completedالعنصر: campaignانتهت حملة: أُرسل لكل مستلم أو فشل. تحمل stats الأرقام النهائية. data.object هي الحملة campaign.
campaign.failedالعنصر: campaignتعذّر إرسال حملة، مثلًا لأن Meta أوقف التسليم لسبب يتعلق بالفوترة. data.object هي الحملة campaign.
campaign.cancelledالعنصر: campaignأُلغيت حملة، ولن تُرسل رسائلها غير المرسلة. data.object هي الحملة campaign.
flow.*5
flow.run.startedالعنصر: flow_runبدأ تدفق لعميل، من الواجهة أو مشغّل أو صندوق الوارد. data.object هو flow_run.
flow.run.handed_offالعنصر: flow_runحوّل تدفق العميل إلى فريقك، والمحادثة تحتاج الآن إلى موظف. data.object هو flow_run.
flow.run.completedالعنصر: flow_runوصل تدفق إلى نهايته لعميل. تحمل variables كل ما جمعه. data.object هو flow_run.
flow.run.expiredالعنصر: flow_runتوقف تدفق عن انتظار عميل لم يرد في الوقت المحدد. data.object هو flow_run.
flow.responseالعنصر: flow_responseأرسل عميل نموذج واتساب (Flow). تحمل answers ما أدخله. data.object هو flow_response.
conversation.*5
conversation.createdالعنصر: conversationبدأ عميل محادثة جديدة مع مساحة العمل. data.object هي المحادثة conversation.
conversation.needs_agentالعنصر: conversationمحادثة تنتظر موظفًا، لأن الروبوت حوّلها أو لأن العميل طلب ذلك. نبّه فريقك أو أسندها عبر POST /v1/conversations/{id}/assign.
{
"id": "evt_01j9x9c1d2e3f4g5h6j7k8m9n0",
"object": "event",
"type": "conversation.needs_agent",
"version": "2",
"created_at": "2026-10-01T09:29:15Z",
"livemode": true,
"workspace_id": "ws_12",
"data": {
"object": {
"id": "conv_311",
"object": "conversation",
"channel": "whatsapp",
"customer": {
"contact_id": "ct_1052",
"address": "+966501234567",
"name": "سارة القحطاني"
},
"number_id": "num_3",
"state": "needs_agent",
"open": true,
"assignee": null,
"unread": true,
"label": null,
"last_customer_message_at": "2026-10-01T09:29:10Z",
"last_agent_message_at": null,
"reply_window_expires_at": "2026-10-02T09:29:10Z",
"resolved_at": null,
"snoozed_until": null,
"created_at": "2026-10-01T09:28:00Z",
"updated_at": "2026-10-01T09:29:12Z"
}
}
}