Webhooks

ما الذي ستحققه

كلما أنهى أحد وكلائك مكالمة، سترسل Phynxa ملخصها ونصها المكتوب وتفاصيلها إلى عنوان ويب تتحكم فيه. ويمكنك أيضًا أن تُبلَّغ عند بدء المكالمة وفي كل مرة تُنفَّذ فيها أداة.

المتطلبات المسبقة

• نقطة اتصال http أو https عامة تقبل الطلب وتردّ بحالة 2xx. وتُرفَض العناوين الخاصة والداخلية.
• دور owner أو admin.

الإعداد خطوة بخطوة

1. افتح Tools وتبويب Webhooks، واختر New webhook.
2. أدخل Name (لمرجعك أنت، مثل CRM sync) وحدّد Agents الذين ينبغي أن يرسلوا إليه. يستخدم الوكيل Webhook واحدًا، لذا فتحديد وكيل لديه آخر ينقله إلى هذا.
3. اختر إنشاءه. تُفتح صفحة الـ Webhook.
4. تحت Where to send it، اختر Method (الافتراضي POST) وأدخل URL، مثل https://yoursite.com/hooks/calls.
5. اضبط Signing secret. وهو اختياري لكنه موصى به: فهو يتيح لك إثبات أن كل طلب جاء من Phynxa. راجع تحقق من توقيعات Webhook.
6. تحت What to send، حدّد الأجزاء التي تريدها (انظر أدناه). وتحت Limits اضبط Timeout وAttempts.
7. اختر Save changes.
8. في كل وكيل، فعّل Webhook تحت Tools، Built-in، واخترْه تحت Send to.

ما الذي يحمله كل تسليم

يُرسَل اسم الحدث ومعرّف المكالمة دائمًا. حدّد أيًّا مما يلي لإضافته:

وإذا لم يُحدَّد شيء، يُرسَل كل شيء.

أنواع الأحداث

يستطيع الـ Webhook استقبال ثلاثة أحداث. حدّد ما تريده تحت Events؛ وCall completed محدَّد في أي Webhook جديد.

تنطبق تحديدات What to send على كل حدث، لكن على الأجزاء التي يملكها ذلك الحدث فقط: فـ call.started فيه تفاصيل المكالمة ولا شيء يُضاف إليه نص مكالمة. أما tool.called فيحمل دائمًا كتلة tool.

كيف تتصرف الأحداث المباشرة:

• بالترتيب. call.started ثم أي tool.called ثم call.completed.
• لا تعطّل المتصل أبدًا. تُرسَل في الخلفية. ولا تستطيع نقطة اتصال بطيئة أو غير متاحة أن تجعل المتصل ينتظر. وإن زاد عدد الأحداث المنتظرة لمكالمة واحدة على 50، يُهمَل الأحدث. وعند انتهاء المكالمة تنتظر Phynxa بضع ثوانٍ ما في الطابور ثم ترسل call.completed.
• بلا كلفة إن لم تستخدمها. الوكيل الذي لم يحدّد Webhook الخاص به هذه الأحداث لا يبذل أي عمل إضافي أثناء المكالمة.
• المحاولات. تنطبق Attempts، لكن الحدث المباشر ينتظر ردًّا 5 ثوانٍ على الأكثر مهما كانت قيمة Timeout.
• أي المكالمات. يُقرأ الـ Webhook عند بدء المكالمة، فيسري تحديد الحدث على المكالمات التي تبدأ بعد الحفظ. والـ Webhook الموقوف لا يرسل شيئًا.

call.started:

{
  "event": "call.started",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound",
    "from_number": "+971501234567",
    "to_number": "+97145551234",
    "started_at": "2026-10-12T09:14:03.120000+00:00"
  }
}

tool.called:

{
  "event": "tool.called",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound"
  },
  "tool": { "id": "5d1f0c7a", "name": "check_order", "ok": true, "duration_ms": 420 }
}

مثال على الحمولة

مع تحديد كل الأجزاء (القيم مثال):

{
  "event": "call.completed",
  "call_id": "b130a71059eb44e3bfff982ecc035585",
  "call": {
    "id": "b130a71059eb44e3bfff982ecc035585",
    "agent_id": "230af209-7759-45af-839e-55cf5dcda8fd",
    "agent_name": "Reception Marina",
    "direction": "inbound",
    "from_number": "+971501234567",
    "to_number": "+97145551234",
    "started_at": "2026-10-12T09:14:03.120000+00:00",
    "ended_at": "2026-10-12T09:15:41.880000+00:00",
    "seconds": 98.8,
    "turns": 9,
    "p50_latency_ms": 820,
    "p95_latency_ms": 1311,
    "outcome": "completed"
  },
  "review": {
    "summary": "Caller asked to book a cleaning on Thursday afternoon and was booked for 2:30 pm.",
    "intent": "book an appointment",
    "sentiment": "positive",
    "outcome": "appointment_booked",
    "score": 5,
    "status": "complete"
  },
  "transcript": [
    { "role": "assistant", "text": "Thank you for calling Acme Dental. How can I help?", "at": "2026-10-12T09:14:04+00:00" },
    { "role": "user", "text": "Hi, can I book a cleaning this Thursday?", "at": "2026-10-12T09:14:09+00:00" }
  ],
  "action_items": ["Send a reminder the day before"],
  "entities": { "name": "Sara K.", "email": "sara@example.com" }
}

ملاحظات على الحقول:

• direction هو inbound أو outbound أو web (اختبار في المتصفح).
• role في النص المكتوب هو assistant (الوكيل) أو user (المتصل).
• review.status هو complete أو pending (لم تنتهِ المراجعة) أو off (Call summary معطّل للوكيل). وتحتفظ المفاتيح الأخرى بشكلها في كل حال.
• outcome داخل review هو أحد resolved أو needs_followup أو information_given أو appointment_booked أو no_answer أو abandoned أو unclear.
• مع تحديد Summary فقط تتلقى event وcall_id وreview، ولا شيء غير ذلك.

تفاصيل الطلب

ترسل Phynxa طلبًا إلى URL الخاص بك بهذه الترويسات:

إعادة المحاولة وما يُعدّ مسلَّمًا

• مسلَّم: تردّ نقطة الاتصال الخاصة بك بحالة 2xx.
• تُعاد المحاولة: انتهاء المهلة وأخطاء الاتصال وردود 5xx، حتى عدد محاولات Attempts (من 1 إلى 5؛ وتبدأ الـ Webhooks الجديدة بـ 3)، مع وقفة قصيرة بينها.
• لا تُعاد المحاولة: ردّ 4xx. تفترض Phynxa أن نقطة الاتصال لديك رفضت الطلب وستظل ترفضه.
• Timeout: المدة التي تنتظر فيها Phynxa ردًّا، حتى 60 ثانية (وتبدأ الـ Webhooks الجديدة بـ 10).
• لا تُتَّبَع إعادة التوجيه.

والـ Webhook المتعطل لا يفقد سجل المكالمة أبدًا: فالمكالمة تُخزَّن في History في كل حال.

تحقق من عمليات التسليم

تحت Recent deliveries (آخر 50 محاولة) يعرض كل صف الحدث، وهل نجح، ورمز الحالة، والوقت الذي استغرقه، وأي خطأ. وفي الوكيل، يسرد تبويب Logs عمليات التسليم للـ Webhook الذي يرسل إليه.

الاختبار

في صفحة الـ Webhook اختر Send test. فهو يرسل عينة لكل حدث حدّدته (عينة نهاية المكالمة إن لم تحدّد شيئًا)، تحمل الأجزاء التي حدّدتها فقط، وموقَّعة تمامًا كعينة حقيقية. ويعرض النتيجة، وإن فشلت عينة فإنه يذكر الحدث. وكل عينة صف تحت Recent deliveries. احفظ أولًا: فالاختبار يستخدم النسخة المحفوظة.

النتيجة المتوقعة

تتلقى نقطة الاتصال الخاصة بك الطلب، وتردّ بـ 2xx، ويظهر الصف تحت Recent deliveries ناجحًا.

استكشاف الأخطاء

راجع مشكلات تسليم Webhook.

أدلة ذات صلة

• تحقق من توقيعات Webhook
• REST API