الخدمة 6

Webhook المحادثات

WEBHOOKPOST على URL تحدده إنصاف

هنا Velents هي التي ترسل POST إلى سيرفر إنصاف مع كل event في محادثة الـ chat widget.

التفعيل: أضف data-webhook إلى الـ embed snippet الموجود عندكم دون تغيير الباقي.

•القيمة يجب أن تكون JSON صحيحاً بين single quotes. الـ JSON الخاطئ يُتجاهل ويبقى الـ widget شغالاً.
•الـ objects والـ arrays المتداخلة في headers / body تُحذف، والأرقام والـ booleans تتحول إلى strings.
•التغيير يؤثر على المحادثات الجديدة فقط.
•الـ snippet عام (public)، فلا تضع أي secret في headers أو body.
•قيم data-var-* ترجع في conversation.values، ويمكنك ربط المحادثة بالمستخدم عندك من خلالها.
•طريقة الإرسال: POST JSON مع headers الخاصة بك + X-Velents-Authorization. كل event يُرسل مرة واحدة دون retry؛ أي رد غير 2xx يضيع. أرجع فوراً ونفّذ العمل async.

إعدادات data-webhook

الحقل	النوع	مطلوب	الشرح
`link`	HTTPS URL	إجباري	الـ URL نفسه. إن كان فارغاً يُستخدم webhook الـ agent إن وجد.
`body`	object	اختياري	keys تُدمج في الـ payload. القيم strings.
`headers`	object	اختياري	headers مع كل request. القيم strings.
`events`	string[]	اختياري	Message أو Update أو Ended. فارغ = الكل.

embed snippet

<script src="https://assets.velents.ai/loader.global.js"
  data-auth-token="<token>"
  ...
  data-webhook='{
    "link": "https://your-server.com/velents/webhook",
    "body": {},
    "headers": { "X-Client-Id": "acme" },
    "events": ["Message", "Update", "Ended"]
  }'>
</script>

Events

event.type	يُرسل عند	result.message	result.history
`onMessage`	رسالة من العميل، أو رد لم تتغير معه الـ extracted data	الرسالة	غير موجود
`onUpdate`	رد تغيّرت معه الـ extracted data	الرد	الـ transcript كامل
`onEnded`	انتهاء المحادثة	سبب الإنهاء	الـ transcript كامل

حقول الـ Payload

Field	الشرح
`agent.id, agent.public`	id الـ AI agent والـ public id الخاص به.
`conversation.id`	الـ key الذي تخزّن عليه كل شيء.
`conversation.channel_id`	id القناة (web chat, WhatsApp, ...)، أو null لتجارب الـ dashboard.
`conversation.created_by_id, agent_batch_id`	المستخدم الذي أنشأ المحادثة، والـ batch إن بدأت من batch (أو null).
`conversation.phone`	هاتف العميل إن كانت القناة فيها هاتف، null على الـ web widget.
`conversation.values`	قيم data-var-*.
`result.message`	الرسالة: message, media_url[], type (text / image / audio / document), role, timestamp, metadata.tool_calls[].
`result.goals`	البيانات المستخرجة حتى الآن، غير موجود حتى يُستخرج شيء.
`result.history[]`	الـ transcript، الأقدم أولاً، وكل عنصر فيه message و role و timestamp. في onUpdate و onEnded فقط.

حالات المحادثة (conversation.status)

Status	المعنى
`active`	الـ AI يتولاها
`human_pending`	بانتظار موظف
`human_responses`	موظف يتولاها
`payment_pending`	متوقفة لعدم وجود رصيد
`completed`	الـ AI أغلقها
`expired`	أُغلقت دون أن تكتمل
`ended`	أُغلقت
`pending_safha, inactive, draft, WhatsAppInit`	حالات أخرى

payload

{
  "event": { "type": "onUpdate", "about": "conversation" },
  "agent": { "id": 12, "public": "boddy_acme_Agent_12" },
  "conversation": {
    "id": 991, "channel_id": 3, "created_by_id": 5, "agent_batch_id": null, "phone": null,
    "status": "active", "values": { "customer_name": "Sara" }, "created_at": "2026-10-17 10:00:00"
  },
  "result": {
    "message": {
      "message": "Sure, your order ships tomorrow.", "media_url": [], "type": "text",
      "role": "agent", "timestamp": "2026-10-17 10:00:05", "metadata": { "tool_calls": [] }
    },
    "goals": { "customer_name": "Sara", "order_number": "A-1043" },
    "history": [
      { "role": "customer", "message": "Where is my order A-1043?", "timestamp": "2026-10-17T10:00:01.123000" },
      { "role": "agent", "message": "Sure, your order ships tomorrow.", "timestamp": "2026-10-17T10:00:05.456000" }
    ]
  }
}

→ الإبلاغ عن نتيجة خاطئة صفحة — OCR واستخراج المستندات ←