دریافت ایونت تماس

مقدمه

ایونت تماس یکی از قابلیت‌های تعبیه‌شده در سیستم تلفن ابری تلفنچی است که به شما امکان می‌دهد رویدادهای تماس را به‌صورت لحظه‌ای دریافت کنید. برخلاف روش polling (که نیاز به درخواست مکرر دارد)، در این روش سیستم تلفنچی به‌صورت خودکار اطلاعات را به آدرس وب‌هوک شما ارسال می‌کند.

دو نوع رویداد ارسال می‌شود:

نحوه عملکرد

پس از ثبت آدرس وب‌هوک در پنل کاربری تلفنچی، هر بار که یک تماس رخ می‌دهد سیستم به‌صورت خودکار یک درخواست POST حاوی اطلاعات تماس به آدرس شما ارسال می‌کند. جریان کلی به این شکل است:

⚠ نکته: سرور شما باید در کمترین زمان ممکن پاسخ HTTP 200 برگرداند. پردازش‌های سنگین را به صف (queue) بسپارید تا از timeout جلوگیری شود.

ساختار داده دریافتی (Payload)

اطلاعات به‌صورت JSON در بدنه درخواست POST ارسال می‌شود:

{

  "uid": "3Ev15-2841c6b5-1111-4c1c-bffe-8f5f1d4a9fec",

  "rid": "OTCL-bd07341f-1111-4c19-bdad-c18044bf105d",

  "message": "request sent",

  "data": {

    "service_id": "3Ev15-114h-1414-bffe-8f5f1d4a9fasd",

    "cuid": "173133386.125769",

    "unique_id": "173133386.125769",

    "src": "89**3",

    "dest": "912****975",

    "type": "outgoing",

    "event": "ringing",

    "datetime": "2024-11-18 16:55:37",

    "trunk_number": "021******75",

    "trunk_outgoing": "pishgaman",

    "webservice_token": "123ghj564-02be-44c9-bb3f-121039ghjghjf9",

    "events_hook": "your_url",

    "app_name": "parsvt",

    "date": "2024-11-18 16:55:38"

  },

  "created_at": "2024-11-18 16:55:38",

  "type": "info"

}

توضیحات فیلدهای خروجی

فیلدهای اصلی

فیلدهای بخش data

امنیت و اعتبارسنجی

برای اطمینان از اینکه درخواست‌های دریافتی واقعاً از تلفنچی ارسال شده‌اند و جعلی نیستند، می‌توانید از فیلد webservice_token در بدنه درخواست استفاده کنید:

<?php

// اعتبارسنجی درخواست ورودی از تلفنچی

$payload = json_decode(file_get_contents('php://input'), true);




$received_token = $payload['data']['webservice_token'] ?? '';

$expected_token = '{YOUR_WEBSERVICE_TOKEN}'; // توکن ذخیره‌شده در سرور شما




if ($received_token !== $expected_token) {

    http_response_code(403);

    exit('Unauthorized');

}




// پردازش رویداد

$event = $payload['data']['event']; // 'ringing' یا 'hangup'

$cuid  = $payload['data']['cuid'];

$src   = $payload['data']['src'];

$dest  = $payload['data']['dest'];

$type  = $payload['data']['type']; // 'incoming' یا 'outgoing'




// پاسخ سریع به تلفنچی

http_response_code(200);

echo json_encode(['status' => 'ok']);




// پردازش‌های سنگین را در صف قرار دهید

// ...

موارد استفاده رایج

نمایش لحظه‌ای وضعیت تماس

با دریافت رویداد ringing می‌توانید بلافاصله اطلاعات تماس‌گیرنده را روی صفحه نمایش دهید — مثلاً نام مشتری از CRM — قبل از اینکه اپراتور تلفن را بردارد.

ثبت خودکار تماس‌ها در CRM

با دریافت رویداد ringing می‌توان تماس را در CRM ثبت کرد و با hangup، زمان پایان مکالمه را به‌روز نمود.

سیستم اعلان و هشدار

در صورتی که تماس مهمی از مشتری خاص دریافت شد، می‌توان بر اساس src پیام فوری به تیم مربوطه ارسال کرد.

گزارش‌گیری بلادرنگ

با پردازش رویدادهای ringing و hangup می‌توان داشبورد زنده‌ای از وضعیت تماس‌های جاری ساخت.

ردیابی مسیر تماس

با ذخیره cuid در هر رویداد می‌توان کل چرخه یک تماس (زنگ، پاسخ، قطع) را ردیابی و تحلیل کرد.

دانلود فایل این آموزش به صورت PDF