تماس سریع (Click To Call)

تماس سریع تلفنچی

با وب‌سرویس تماس سریع Telefonchy می‌توانید از داخل CRM، نرم‌افزار پشتیبانی یا سامانهٔ اختصاصی خود، برقراری تماس از یک داخلی مشخص به شمارهٔ مقصد را درخواست کنید.

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

نکته مهم: پاسخ موفق API فقط به معنی ثبت و صف‌شدن درخواست تماس است؛ این پاسخ به‌تنهایی پاسخ‌دادن اپراتور یا برقراری کامل مکالمه را تضمین نمی‌کند. برای پیگیری، request_id را ذخیره و وضعیت آن را استعلام کنید.

پیش‌نیازها

• سرویس Telefonchy و وب‌سرویس فعال

• توکن وب‌سرویس متعلق به مالک service_id

• داخلی فعال و آنلاین متعلق به همان سرویس

• شمارهٔ مقصد معتبر و مسیر خروجی در دسترس

• ارسال درخواست از Backend امن، نه مستقیماً از مرورگر کاربر

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

1. سامانهٔ شما درخواست تماس سریع را به Telefonchy ارسال می‌کند.

2. Telefonchy اعتبار توکن، سرویس و داخلی را بررسی می‌کند.

3. یک request_id برای رهگیری درخواست ایجاد می‌شود.

4. درخواست به مرکز تماس مربوط به سرویس ارسال می‌شود.

5. ابتدا داخلی اپراتور زنگ می‌خورد.

6. پس از پاسخ اپراتور، تماس با شمارهٔ مقصد برقرار می‌شود.

7. با مسیر استعلام وضعیت می‌توانید cuid و آخرین وضعیت پردازش تماس را دریافت کنید.

ایجاد تماس سریع

نشانی و روش درخواست

GET https://panel.telefonchy.com/webservice/v1/smartcall

پارامترها باید در Query String ارسال شوند. برای این مسیر، بدنهٔ JSON یا Form Data ارسال نکنید.

هدرهای درخواست

پارامترهای Query String

توکن باید متعلق به مالک service_id باشد و داخلی نیز باید به همان سرویس تعلق داشته باشد.

نمونهٔ cURL

curl --get 'https://panel.telefonchy.com/webservice/v1/smartcall' \
  --header 'Accept: application/json' \
  --header 'webservice-token: YOUR_WEBSERVICE_TOKEN' \
  --data-urlencode 'service_id=YOUR_SERVICE_ID' \
  --data-urlencode 'exten=YOUR_EXTENSION' \
  --data-urlencode 'to=09330393515'

نمونهٔ PHP

<?php

$query = http_build_query([
    'service_id' => 'YOUR_SERVICE_ID',
    'exten'      => 'YOUR_EXTENSION',
    'to'         => '09330393515',
]);

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => 'https://panel.telefonchy.com/webservice/v1/smartcall?' . $query,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT        => 20,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_HTTPHEADER     => [
        'Accept: application/json',
        'webservice-token: YOUR_WEBSERVICE_TOKEN',
    ],
]);

$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);

curl_close($curl);

if ($response === false) {
    throw new RuntimeException($error ?: 'Click-to-call request failed.');
}

$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

if ($httpCode < 200 || $httpCode >= 300 || ($result['code'] ?? null) !== 200) {
    throw new RuntimeException($result['message'] ?? 'Click-to-call request was rejected.');
}

print_r($result);

نمونهٔ پاسخ موفق

{
  "status": "Ok",
  "code": 200,
  "message": null,
  "data": {
    "status": "success",
    "request_id": "ctc_8c47d6ac-60df-4218-a570-4cdf4629aa32",
    "originated_call_id": "orig.call.1966cd3a-050e-426a-9180-1ba69bcb185c",
    "cuid": null,
    "call_status": "queued",
    "caller": "188464",
    "callee": "09330393515",
    "server_id": 2,
    "failure_reason": null
  }
}

مهم‌ترین فیلدهای پاسخ

• request_id: شناسهٔ اصلی رهگیری درخواست؛ آن را در سامانهٔ خود ذخیره کنید.

• originated_call_id: شناسهٔ درخواست در مرکز تماس؛ برای بررسی فنی و لاگ‌ها کاربرد دارد.

• cuid: شناسهٔ تماس پس از ورود به مسیر پردازش؛ ممکن است در پاسخ اولیه null باشد.

• call_status: آخرین وضعیت درخواست؛ در پاسخ اولیه معمولاً queued است.

• failure_reason: علت خطا در صورت بروز مشکل.

• created_at و updated_at: زمان ایجاد و آخرین به‌روزرسانی درخواست با قالب ISO 8601.

استعلام وضعیت تماس سریع

برای استعلام وضعیت، request_id دریافتی از پاسخ ایجاد تماس را در مسیر زیر قرار دهید:

GET https://panel.telefonchy.com/webservice/v1/smartcall/status/{request_id}

در این درخواست فقط هدر webservice-token لازم است.

نمونهٔ cURL

curl 'https://panel.telefonchy.com/webservice/v1/smartcall/status/ctc_8c47d6ac-60df-4218-a570-4cdf4629aa32' \
  --header 'Accept: application/json' \
  --header 'webservice-token: YOUR_WEBSERVICE_TOKEN'

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

برای تماس بدون پاسخ، وضعیت ممکن است روی مرحله‌ای مانند dialing باقی بماند. برای نتیجهٔ نهایی تماس، مدت مکالمه، فایل ضبط‌شده یا وضعیت CDR، پس از ایجاد cuid از APIهای گزارش تماس استفاده کنید.

پیشنهاد برای Polling

پس از دریافت پاسخ ایجاد تماس، وضعیت را هر ۲ تا ۳ ثانیه استعلام کنید. برای جلوگیری از درخواست اضافی، Polling را پس از رسیدن به وضعیت موردنظر یا پس از یک بازهٔ محدود، مانند ۳۰ تا ۶۰ ثانیه، متوقف کنید.

خطاهای رایج

• ارسال‌نشدن service_id، exten یا to

• ارسال‌نشدن یا نامعتبر بودن webservice-token

• تعلق‌نداشتن توکن یا داخلی به سرویس انتخاب‌شده

• غیرفعال‌بودن سرویس، وب‌سرویس یا داخلی

• آفلاین‌بودن Softphone اپراتور

• در دسترس نبودن مرکز تماس یا مسیر خروجی

• نامعتبر بودن شمارهٔ مقصد

نکات امنیتی و عملیاتی

• توکن وب‌سرویس را فقط در Backend نگه دارید.

• توکن را در JavaScript مرورگر، اپلیکیشن عمومی یا مخزن کد منتشر نکنید.

• درخواست تماس را از سرور خود به Telefonchy ارسال کنید.

• از HTTPS استفاده کنید و بررسی گواهی SSL را در محیط عملیاتی غیرفعال نکنید.

• شمارهٔ مقصد، service_id و exten را پیش از ارسال اعتبارسنجی کنید.

• request_id، originated_call_id و cuid را در سامانهٔ خود ذخیره کنید.

• برای جلوگیری از تماس تکراری، دکمهٔ تماس را پس از کلیک موقتاً غیرفعال کنید.

• در Retry خودکار محتاط باشید؛ Timeout الزاماً به معنی ثبت‌نشدن تماس نیست.

دانلود راهنمای این پست مرکز آموزش به صورت PDF (کلیک کنید)