پنل پیامکی رایگان، هدیه ثبت‌نام شما در تلفنچی!

API و وب‌سرویس

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

در این صفحه
دسته‌بندی‌های مرکز آموزش
دریافت ایونت تماس

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

مقدمه

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

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

رویداد

توضیحات

ringing

هنگامی که تماسی در حال زنگ خوردن است — قبل از پاسخ دادن

hangup

پس از قطع شدن تماس — چه پاسخ داده شده باشد چه خیر


نحوه عملکرد

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

۱

تماسی برقرار یا دریافت می‌شود

۲

سیستم تلفنچی رویداد ringing را تشخیص می‌دهد

۳

یک درخواست POST با اطلاعات تماس به events_hook شما ارسال می‌شود

۴

پس از قطع تماس، رویداد hangup نیز به همان آدرس ارسال می‌شود

۵

سرور شما اطلاعات را پردازش کرده و پاسخ HTTP 200 برمی‌گرداند


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

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

‏این ساختار مربوط به وب‌هوک عمومی JSON است: درخواست با متد POST و هدر Content-Type: application/json ارسال می‌شود. فیلدهای تماس مستقیماً در ریشهٔ بدنه قرار دارند؛ لایهٔ data وجود ندارد. اتصال‌های آماده مانند دیدار می‌توانند قرارداد متفاوتی داشته باشند.

{
  "service_id": "3Ev15-example-service",
  "cuid": "173133386.125769",
  "src": "989120000000",
  "dest": "101",
  "type": "incoming",
  "event": "ringing",
  "trunk_number": "02100000000",
  "trunk_incoming": "example-trunk",
  "webservice_token": "EXAMPLE_TOKEN_REPLACE_ME",
  "events_hook": "https://example.com/webhook",
  "app_name": "dedicated",
  "date": "2026-11-11 10:00:00"
}

‏مقادیر این نمونه ساختگی‌اند. قالب و نوع مقادیر شماره‌ها را هنگام دریافت بررسی کنید و برای پردازش، آن‌ها را به رشته تبدیل کنید. شماره‌ها در لایهٔ ارسال عمومی با ستاره ماسک نمی‌شوند؛ مقدار شماره تابع اطلاعات رویداد تماس است.

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

‏رکوردهای لاگ ممکن است دارای uid، rid، message، created_at و یک بخش data باشند. این پوششِ لاگ، بدنهٔ درخواست وب‌هوک نیست. مقدار type در بدنهٔ تماس، نوع تماس است و نباید با مقدار info یا error در لاگ اشتباه گرفته شود.

‏فیلدهای بدنهٔ وب‌هوک در سطح ریشه

فیلد

توضیحات

service_id

شناسه سرویس تلفنچی مرتبط با این تماس

cuid / unique_id

‏شناسهٔ تماس؛ از cuid استفاده کنید. اگر unique_id نیز در رویداد وجود داشت، می‌توان آن را به‌عنوان نام جایگزین خواند؛ وجود هم‌زمان هر دو را الزامی نکنید.

src

‏شمارهٔ مبدأ؛ در تماس ورودی، شمارهٔ تماس‌گیرنده است. لایهٔ ارسال عمومی آن را ماسک نمی‌کند.

dest

‏مقصد تماس طبق رویداد؛ ممکن است شماره یا داخلی باشد. لایهٔ ارسال عمومی آن را ماسک نمی‌کند.

type

نوع تماس: "incoming" برای ورودی یا "outgoing" برای خروجی

event

وضعیت رویداد: "ringing" هنگام زنگ خوردن، "hangup" پس از قطع تماس

datetime

‏زمان وقوع رویداد با فرمت Y-m-d H:i:s، در صورت وجود در رویداد

trunk_number

شماره خط (ترانک) استفاده‌شده در این تماس

trunk_outgoing

‏نام ترانک خروجی؛ برای رویداد ورودی ممکن است به‌جای آن trunk_incoming وجود داشته باشد.

webservice_token

توکن امنیتی وب‌سرویس برای تأیید هویت درخواست

events_hook

آدرس URL وب‌هوک شما که این رویداد به آن ارسال شده است

app_name

نام اپلیکیشن یا سرویس ارسال‌کننده رویداد

date

تاریخ و زمان ثبت رویداد با فرمت Y-m-d H:i:s


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

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

‏توکن را از webservice_token در ریشهٔ پیام بخوانید. نمونهٔ زیر الگوی خواندن و اعتبارسنجی است؛ متغیر محیطی توکن و ثبت پایدار رویداد در صف را متناسب با برنامهٔ خود پیاده‌سازی کنید. پیش از ذخیرهٔ موفق رویداد، پاسخ موفق ندهید. برای نمایش مشتری هنگام زنگ‌خوردن، ترکیب type=incoming و event=ringing را بررسی کنید.

<?php
$payload = json_decode(file_get_contents('php://input'), true);
if (json_last_error() !== JSON_ERROR_NONE || !is_array($payload)) {
    http_response_code(400);
    exit('Invalid JSON');
}

// Configure this secret on your server; never put it in public frontend code.
$expected_token = getenv('TELEFONCHY_WEBSERVICE_TOKEN');
if (!is_string($expected_token) || $expected_token === '') {
    http_response_code(500);
    exit('Webhook token is not configured');
}
$received_token = $payload['webservice_token'] ?? null;
if (!is_string($received_token) || !hash_equals($expected_token, $received_token)) {
    http_response_code(403);
    exit('Unauthorized');
}

$event = $payload['event'] ?? '';
$cuid = $payload['cuid'] ?? $payload['unique_id'] ?? '';
$src = (string) ($payload['src'] ?? '');
$dest = (string) ($payload['dest'] ?? '');
$type = $payload['type'] ?? '';
$service_id = $payload['service_id'] ?? '';

if ($type === 'incoming' && $event === 'ringing') {
    // Enqueue the authenticated event durably here before acknowledging it.
    // Your worker can normalize $src and look up the customer in WooCommerce.
}

header('Content-Type: application/json; charset=utf-8');
http_response_code(200);
echo json_encode(['status' => 'ok']);

‏عیب‌یابی دریافت وب‌هوک

‏پاسخ HTTP 403 به‌تنهایی به معنی مسدودشدن توسط فایروال نیست؛ خود افزونه یا تابع permission_callback وردپرس نیز ممکن است آن را برگرداند. اگر JSON معتبر است ولی خطای «data دریافت نشد» می‌بینید، گیرنده را برای خواندن فیلدها از ریشهٔ پیام اصلاح کنید.

‏در تماس آزمایشی، زمان تماس، Content-Type، نوع رویداد و کد پاسخ گیرنده را بررسی کنید. برای بررسی ساختار، بدنهٔ درخواست را فقط با مخفی‌کردن توکن و شماره‌ها نگه دارید؛ نام فیلدها و لایه‌ها حفظ شوند. دریافت پاسخ موفق از API لیست تماس‌ها یا دریافت CDR، تحویل وب‌هوک incoming/ringing پیش از پاسخ را اثبات نمی‌کند.

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

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

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

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

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

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

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

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

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

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

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

‏برای ذخیرهٔ نسخهٔ PDF به‌روز این آموزش، از گزینهٔ چاپ مرورگر و ذخیره به‌صورت PDF استفاده کنید.

سوالات متداول

دیدگاه کاربران

نظرات و تجربه‌های شما

۰ دیدگاه

دیدگاه پس از بررسی و تأیید نمایش داده می‌شود.

هنوز دیدگاهی ثبت نشده است؛ اولین دیدگاه را شما بنویسید.