دریافت صوت مکالمه

مقدمه

یکی از قابلیت‌های کاربردی سیستم تلفن ابری تلفنچی، امکان ضبط خودکار مکالمات و دسترسی برنامه‌نویسی به آن‌هاست. اگر در کسب‌وکار خود نیاز دارید مکالمات تیم پشتیبانی یا فروش را بررسی کنید، گزارش‌های کیفی تهیه کنید، یا فایل‌های صوتی را در سیستم‌های دیگر (مثل CRM) ذخیره کنید، این endpoint دقیقاً همان چیزی است که نیاز دارید.

با استفاده از API دانلود فایل صوتی تلفنچی می‌توانید به‌صورت کاملاً خودکار و بدون نیاز به ورود به پنل، فایل ضبط هر مکالمه را دریافت کنید.

پیش‌نیازها

قبل از استفاده از این endpoint، به موارد زیر نیاز دارید:

۱. توکن وب‌سرویس (webservice-token): این توکن را از بخش تنظیمات پنل کاربری تلفنچی دریافت کنید. توکن در تمام درخواست‌های API به‌عنوان header ارسال می‌شود.

۲. شناسه فایل صوتی (file_id): این مقدار در خروجی API لیست تماس‌ها (/webservice/v1/calls) در فیلد file_id هر تماس موجود است.

۳. شناسه یکتای تماس (cuid): این مقدار نیز از همان API لیست تماس‌ها و از فیلد cuid قابل دریافت است.

نکته مهم: قبل از فراخوانی این endpoint، ابتدا باید لیست تماس‌ها را دریافت کرده و file_id و cuid تماس موردنظر را استخراج کنید. در صورتی که فیلد file_record در لیست تماس‌ها خالی یا null باشد، به این معناست که آن تماس ضبط نشده و فایل صوتی برای آن وجود ندارد.

مشخصات Endpoint

[GET] https://panel.telefonchy.com/webservice/v1/calls/record

Header

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

پارامترها به‌صورت query string در انتهای URL ارسال می‌شوند:

نمونه کدها

cURL

ساده‌ترین روش برای تست این endpoint استفاده از cURL در خط فرمان است:

bash

curl -i -H "webservice-token: {YOUR_TOKEN}" \
  'https://panel.telefonchy.com/webservice/v1/calls/record?file_id={FILE_ID}&cuid={CUID}'

برای ذخیره مستقیم فایل صوتی روی سیستم:

bash

curl -H "webservice-token: {YOUR_TOKEN}" \
  'https://panel.telefonchy.com/webservice/v1/calls/record?file_id={FILE_ID}&cuid={CUID}' \
  --output call_record.mp3

PHP

روش ساده — دریافت و ذخیره فایل:

php

<?php
$file_id = '{FILE_ID}';
$cuid    = '{CUID}';
$token   = '{YOUR_TOKEN}';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => "https://panel.telefonchy.com/webservice/v1/calls/record?file_id={$file_id}&cuid={$cuid}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "webservice-token: {$token}",
    ],
]);

$response = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($http_code === 200 && $response) {
    file_put_contents("call_{$cuid}.mp3", $response);
    echo "فایل صوتی با موفقیت ذخیره شد.";
} else {
    echo "خطا در دریافت فایل. کد وضعیت: " . $http_code;
}

روش پیشرفته — پخش مستقیم در مرورگر (Streaming):

اگر می‌خواهید فایل صوتی را بدون ذخیره روی سرور، مستقیماً برای کاربر پخش کنید:

php

<?php
$file_id = '{FILE_ID}';
$cuid    = '{CUID}';
$token   = '{YOUR_TOKEN}';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL            => "https://panel.telefonchy.com/webservice/v1/calls/record?file_id={$file_id}&cuid={$cuid}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        "webservice-token: {$token}",
    ],
]);

$response  = curl_exec($curl);
$http_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

if ($http_code === 200 && $response) {
    header('Content-Type: audio/mpeg');
    header('Content-Disposition: inline; filename="call_record.mp3"');
    header('Content-Length: ' . strlen($response));
    echo $response;
} else {
    http_response_code(404);
    echo "فایل صوتی یافت نشد.";
}

روش پیشرفته — دانلود اجباری برای کاربر:

php

<?php
// همان کد بالا، فقط هدر Content-Disposition را تغییر دهید:
header('Content-Disposition: attachment; filename="call_' . $cuid . '.mp3"');

خروجی

در صورت موفقیت‌آمیز بودن درخواست، محتوای باینری فایل صوتی به‌عنوان پاسخ برگردانده می‌شود. این فایل معمولاً با فرمت MP3 ارائه می‌شود و می‌توانید آن را:

• روی سرور ذخیره کنید و مسیر آن را در دیتابیس نگه دارید

• مستقیماً برای کاربر stream کنید بدون نیاز به ذخیره موقت

• در یک پلیر HTML5 پخش کنید با استفاده از تگ <audio>

• به سیستم‌های دیگر ارسال کنید مثل فضای ابری یا CRM

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

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

یکپارچه‌سازی با CRM: با ذخیره فایل صوتی در کنار اطلاعات مشتری در CRM، تیم فروش به تاریخچه کامل ارتباطات دسترسی خواهد داشت.

پشتیبان‌گیری خودکار: می‌توانید یک job زمان‌بندی‌شده (cron job) بنویسید که هر شب لیست تماس‌های روز را دریافت کرده و فایل‌های صوتی را روی سرور یا فضای ابری ذخیره کند.

تحلیل محتوای مکالمات: با ترکیب این API و سرویس‌های تبدیل گفتار به متن (Speech-to-Text)، می‌توانید محتوای مکالمات را به‌صورت خودکار تحلیل کنید.

دانلود این پست به صورت PDF