Web Service تلفن ابری همکاران
از داخل CRM، ERP، وبسایت یا نرمافزار اختصاصی خود تماس ایجاد کنید، وضعیت داخلیها را ببینید، گزارشها و فایل ضبط مکالمات را دریافت کنید و تماسهای صوتی خودکار بسازید.
Web Service چیست؟
Web Service مجموعهای از APIهای مبتنی بر HTTP است که به نرمافزار شما اجازه میدهد با مرکز تماس تلفن ابری همکاران ارتباط مستقیم داشته باشد.
Base URL و احراز هویت
https://api.hamkaran.cloud/api/hamkaran/v1
کلید اختصاصی وبسرویس باید در Header درخواست با نام key ارسال شود.
key: YOUR_HAMKARAN_WEBSERVICE_KEY Accept: application/json
پاسخها و خطاهای عمومی
| وضعیت | معنا | اقدام |
|---|---|---|
| 200 | درخواست موفق | داده پاسخ را پردازش کنید. |
| 400 / 422 | پارامتر ناقص یا نامعتبر | Body و نوع دادهها را بررسی کنید. |
| 401 / 403 | کلید نامعتبر یا دسترسی غیرفعال | Webservice Key و فعالبودن ماژول را بررسی کنید. |
| 404 | رکورد یا فایل پیدا نشد | UID، Action ID یا محدوده دسترسی را بررسی کنید. |
| 500 | خطای داخلی سرویس | جزئیات درخواست و زمان رخداد را برای پشتیبانی ارسال کنید. |
دریافت گزارش تماسها
فهرست تماسهای ورودی و خروجی را همراه با وضعیت، مدت، داخلی، شناسه تماس، فایل ضبط و جزئیات رویدادها دریافت میکند.
| پارامتر Query | نوع | توضیح |
|---|---|---|
datefrom | date | تاریخ شروع بازه |
dateto | date | تاریخ پایان بازه |
page | integer | شماره صفحه |
source | string | فیلتر شماره مبدأ |
internalnumber | string | فیلتر داخلی |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/reports?datefrom=1405-04-01&dateto=1405-04-31&page=1&source=&internalnumber=201' \ --header 'key: YOUR_WEBSERVICE_KEY'
{
"data": {
"total": 21965,
"pages": 1464,
"page": "1",
"customer_code": 100,
"rows": [{
"eventtime": "1403-03-21",
"time": "21:12",
"status": "ANSWER",
"cid_num": "09121234567",
"exten": "201",
"type": "incoming",
"uniqueid": "1718041336.297594",
"duration": "00:21",
"file": "https://api.hamkaran.cloud/v1/recordpath/...",
"moreinfo": []
}]
}
}دریافت وضعیت داخلیها
وضعیت ثبت و فعالیت داخلیهای مرکز تماس را برای نمایش در CRM یا داشبورد اپراتورها برمیگرداند.
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/extension' \ --header 'key: YOUR_WEBSERVICE_KEY'
{
"status": "success",
"data": [
{"extension":"201","registered":true,"state":"NOT_INUSE"},
{"extension":"202","registered":true,"state":"INUSE"}
]
}دریافت فایل ضبط تماس با UID
فایل ضبط مکالمه مرتبط با شناسه یکتای تماس را برمیگرداند. پاسخ موفق بهصورت فایل باینری است.
| فیلد Body | الزامی | توضیح |
|---|---|---|
uid | بله | شناسه uniqueid دریافتشده از گزارش یا Webhook |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/get_record' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'uid="1718041336.297594"' \ --output call-record.wav
ایجاد تماس
برای قابلیت «کلیک برای تماس» استفاده میشود. ابتدا داخلی کارشناس زنگ میخورد و پس از پاسخ، تماس با مقصد برقرار میشود.
| فیلد | توضیح |
|---|---|
src | داخلی یا مبدأ مجاز |
dest | شماره مقصد |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/create_call' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'src="201"' \ --form 'dest="09121234567"'
{"status":"success","message":"Call initiated","action_id":"..."}قطع تماس فعال
یک تماس فعال را براساس شناسه یا کانال مرتبط قطع میکند.
| فیلد | توضیح |
|---|---|
uid یا شناسه تماس | شناسه تماس فعال که از پاسخ ایجاد تماس یا رویدادهای تماس دریافت شده است. |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/hang_up_call' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'uid="1718041336.297594"'
ارسال تماس از پیش ضبطشده
تماسی خودکار برقرار کرده و فایل صوتی تعیینشده را برای مخاطب پخش میکند.
| فیلد | الزامی | توضیح |
|---|---|---|
dest | بله | شماره مقصد |
src | بله | شماره یا خط مبدأ مجاز |
audio | بله | فایل صوتی یا شناسه فایل قابل استفاده |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/send-pre-recorded' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'src="02191010000"' \ --form 'dest="09121234567"' \ --form 'audio="welcome_message.wav"'
{"status":"success","actionId":"deecc277-22cd-4725-baec-4e752990009c"}دریافت جزئیات تماس از پیش ضبطشده
نتیجه تماس صوتی خودکار را با استفاده از actionId دریافت میکند.
| فیلد | الزامی | توضیح |
|---|---|---|
actionId | بله | شناسه برگشتی از API ارسال تماس صوتی |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/get-pre-recorded-call-detail' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'actionId="deecc277-22cd-4725-baec-4e752990009c"'
{
"status": "success",
"data": {
"id": 1,
"tenant_id": "123",
"src": "09191234567",
"dest": "09197654321",
"audio": "welcome_message.wav",
"action_id": "deecc277-22cd-4725-baec-4e752990009c",
"answered": 1,
"duration": 60,
"status": "completed",
"created_at": "2024-10-13 12:00:00",
"updated_at": "2024-10-13 12:02:00"
}
}گزارش داشبورد مرکز تماس
شاخصهای تجمیعی مرکز تماس مانند تعداد تماسها، تماسهای پاسخدادهشده و ازدسترفته و مدت مکالمه را دریافت میکند.
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/dashboard?datefrom=1405-04-01&dateto=1405-04-31' \ --header 'key: YOUR_WEBSERVICE_KEY'
گزارش صندوق صوتی
فهرست پیامهای صوتی مرکز تماس را همراه با مبدأ، صندوق، تاریخ، مدت و شناسه فایل دریافت میکند.
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/voicemails?page=1' \ --header 'key: YOUR_WEBSERVICE_KEY'
ارسال OTP صوتی
کد یکبارمصرف را از طریق تماس صوتی برای شماره مخاطب قرائت میکند.
| فیلد | توضیح |
|---|---|
dest | شماره تلفن مقصد |
code | کد یکبارمصرف |
src | شماره مبدأ مجاز، در صورت نیاز |
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/send-otp' \ --header 'key: YOUR_WEBSERVICE_KEY' \ --form 'dest="09121234567"' \ --form 'code="482913"'
نمونه استفاده در نرمافزار
Node.js
const response = await fetch(
"https://api.hamkaran.cloud/api/hamkaran/v1/reports?page=1",
{ headers: { key: process.env.HAMKARAN_WEBSERVICE_KEY, Accept: "application/json" } }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();PHP / Laravel
$response = Http::withHeaders([
'key' => config('services.hamkaran.key'),
'Accept' => 'application/json',
])->get('https://api.hamkaran.cloud/api/hamkaran/v1/reports', [
'page' => 1,
'internalnumber' => '201',
]);
$response->throw();
$data = $response->json();امنیت و محدودیتها
- کلید را فقط در سمت سرور نگهداری کنید.
- برای درخواستهای شبکه Timeout مشخص تعریف کنید.
- برای عملیات ایجاد تماس، از اجرای تکراری ناخواسته جلوگیری کنید.
- شمارهها را قبل از ارسال نرمالسازی کنید.
- گزارشها را صفحهبندی دریافت کنید و از دریافت بازههای بسیار بزرگ خودداری کنید.
- فایل ضبط را در فضای عمومی و بدون کنترل دسترسی ذخیره نکنید.
عیبیابی
| مشکل | راهحل |
|---|---|
| 401 یا 403 | Header با نام دقیق key و فعالبودن افزونه Web Service را بررسی کنید. |
| فایل ضبط 404 است | UID تماس، مالکیت تماس و فعالبودن ضبط را بررسی کنید. |
| تماس ایجاد نمیشود | داخلی مبدأ، شماره مقصد، ثبت داخلی و دسترسی تماس خروجی را بررسی کنید. |
| گزارش خالی است | فرمت تاریخ، شماره صفحه و فیلتر داخلی یا شماره را بررسی کنید. |
| Timeout | Timeout کلاینت را افزایش دهید و درخواستهای گزارش سنگین را به بازههای کوچکتر تقسیم کنید. |
