تلفن ابری همکارانمرجع مستندات توسعه‌دهندگان
Web Service API v1WebhookCID Lookupورود به پنل
● مستندات رسمی توسعه‌دهندگان

Web Service تلفن ابری همکاران

از داخل CRM، ERP، وب‌سایت یا نرم‌افزار اختصاصی خود تماس ایجاد کنید، وضعیت داخلی‌ها را ببینید، گزارش‌ها و فایل ضبط مکالمات را دریافت کنید و تماس‌های صوتی خودکار بسازید.

Base URL: api.hamkaran.cloudفرمت داده: JSONاحراز هویت: Webservice Keyنسخه: v1

Web Service چیست؟

Web Service مجموعه‌ای از APIهای مبتنی بر HTTP است که به نرم‌افزار شما اجازه می‌دهد با مرکز تماس تلفن ابری همکاران ارتباط مستقیم داشته باشد.

مدیریت تماسایجاد تماس، قطع تماس و اجرای تماس صوتی خودکار.
گزارش و پایشدریافت تماس‌ها، داشبورد، وضعیت داخلی و صندوق صوتی.
اتصال به CRMکلیک برای تماس، ذخیره ضبط و ثبت خودکار سوابق.
در Web Service، نرم‌افزار شما درخواست را به تلفن ابری ارسال می‌کند. برای دریافت خودکار اتفاقات تماس، از Webhook استفاده کنید.

Base URL و احراز هویت

Base URL
https://api.hamkaran.cloud/api/hamkaran/v1

کلید اختصاصی وب‌سرویس باید در Header درخواست با نام key ارسال شود.

Authentication Header
key: YOUR_HAMKARAN_WEBSERVICE_KEY
Accept: application/json
کلید وب‌سرویس محرمانه است. آن را در JavaScript مرورگر، اپلیکیشن عمومی یا مخزن کد قرار ندهید. درخواست‌ها را از سرور Backend ارسال کنید.

پاسخ‌ها و خطاهای عمومی

وضعیتمعنااقدام
200درخواست موفقداده پاسخ را پردازش کنید.
400 / 422پارامتر ناقص یا نامعتبرBody و نوع داده‌ها را بررسی کنید.
401 / 403کلید نامعتبر یا دسترسی غیرفعالWebservice Key و فعال‌بودن ماژول را بررسی کنید.
404رکورد یا فایل پیدا نشدUID، Action ID یا محدوده دسترسی را بررسی کنید.
500خطای داخلی سرویسجزئیات درخواست و زمان رخداد را برای پشتیبانی ارسال کنید.
GET

دریافت گزارش تماس‌ها

/reports

فهرست تماس‌های ورودی و خروجی را همراه با وضعیت، مدت، داخلی، شناسه تماس، فایل ضبط و جزئیات رویدادها دریافت می‌کند.

پارامتر Queryنوعتوضیح
datefromdateتاریخ شروع بازه
datetodateتاریخ پایان بازه
pageintegerشماره صفحه
sourcestringفیلتر شماره مبدأ
internalnumberstringفیلتر داخلی
cURL
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'
Response
{
  "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": []
    }]
  }
}
GET

دریافت وضعیت داخلی‌ها

/extension

وضعیت ثبت و فعالیت داخلی‌های مرکز تماس را برای نمایش در CRM یا داشبورد اپراتورها برمی‌گرداند.

cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/extension' \
  --header 'key: YOUR_WEBSERVICE_KEY'
Response نمونه
{
  "status": "success",
  "data": [
    {"extension":"201","registered":true,"state":"NOT_INUSE"},
    {"extension":"202","registered":true,"state":"INUSE"}
  ]
}
POST

دریافت فایل ضبط تماس با UID

/get_record

فایل ضبط مکالمه مرتبط با شناسه یکتای تماس را برمی‌گرداند. پاسخ موفق به‌صورت فایل باینری است.

فیلد Bodyالزامیتوضیح
uidبلهشناسه uniqueid دریافت‌شده از گزارش یا Webhook
cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/get_record' \
  --header 'key: YOUR_WEBSERVICE_KEY' \
  --form 'uid="1718041336.297594"' \
  --output call-record.wav
فایل فقط زمانی قابل دریافت است که تماس متعلق به همان مرکز تماس باشد و ضبط مکالمه برای آن تماس وجود داشته باشد.
POST

ایجاد تماس

/create_call

برای قابلیت «کلیک برای تماس» استفاده می‌شود. ابتدا داخلی کارشناس زنگ می‌خورد و پس از پاسخ، تماس با مقصد برقرار می‌شود.

فیلدتوضیح
srcداخلی یا مبدأ مجاز
destشماره مقصد
cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/create_call' \
  --header 'key: YOUR_WEBSERVICE_KEY' \
  --form 'src="201"' \
  --form 'dest="09121234567"'
Response نمونه
{"status":"success","message":"Call initiated","action_id":"..."}
POST

قطع تماس فعال

/hang_up_call

یک تماس فعال را براساس شناسه یا کانال مرتبط قطع می‌کند.

فیلدتوضیح
uid یا شناسه تماسشناسه تماس فعال که از پاسخ ایجاد تماس یا رویدادهای تماس دریافت شده است.
cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/hang_up_call' \
  --header 'key: YOUR_WEBSERVICE_KEY' \
  --form 'uid="1718041336.297594"'
POST

ارسال تماس از پیش ضبط‌شده

/send-pre-recorded

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

فیلدالزامیتوضیح
destبلهشماره مقصد
srcبلهشماره یا خط مبدأ مجاز
audioبلهفایل صوتی یا شناسه فایل قابل استفاده
cURL
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"'
Response نمونه
{"status":"success","actionId":"deecc277-22cd-4725-baec-4e752990009c"}
POST

دریافت جزئیات تماس از پیش ضبط‌شده

/get-pre-recorded-call-detail

نتیجه تماس صوتی خودکار را با استفاده از actionId دریافت می‌کند.

فیلدالزامیتوضیح
actionIdبلهشناسه برگشتی از API ارسال تماس صوتی
cURL
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"'
Response
{
  "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"
  }
}
GET

گزارش داشبورد مرکز تماس

/dashboard

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

cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/dashboard?datefrom=1405-04-01&dateto=1405-04-31' \
  --header 'key: YOUR_WEBSERVICE_KEY'
GET

گزارش صندوق صوتی

/voicemails

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

cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/voicemails?page=1' \
  --header 'key: YOUR_WEBSERVICE_KEY'
نام دقیق Endpoint گزارش صندوق صوتی را هنگام انتقال نهایی از پروژه فعلی Apidog با Route فعال محیط Production تطبیق دهید.
POST

ارسال OTP صوتی

/send-otp

کد یک‌بارمصرف را از طریق تماس صوتی برای شماره مخاطب قرائت می‌کند.

فیلدتوضیح
destشماره تلفن مقصد
codeکد یک‌بارمصرف
srcشماره مبدأ مجاز، در صورت نیاز
cURL
curl --location 'https://api.hamkaran.cloud/api/hamkaran/v1/send-otp' \
  --header 'key: YOUR_WEBSERVICE_KEY' \
  --form 'dest="09121234567"' \
  --form 'code="482913"'
Endpoint و پارامترهای OTP باید پیش از انتشار با نسخه فعال مستندات و سرویس Production تأیید شوند.

نمونه استفاده در نرم‌افزار

Node.js

JavaScript
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

PHP
$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 یا 403Header با نام دقیق key و فعال‌بودن افزونه Web Service را بررسی کنید.
فایل ضبط 404 استUID تماس، مالکیت تماس و فعال‌بودن ضبط را بررسی کنید.
تماس ایجاد نمی‌شودداخلی مبدأ، شماره مقصد، ثبت داخلی و دسترسی تماس خروجی را بررسی کنید.
گزارش خالی استفرمت تاریخ، شماره صفحه و فیلتر داخلی یا شماره را بررسی کنید.
TimeoutTimeout کلاینت را افزایش دهید و درخواست‌های گزارش سنگین را به بازه‌های کوچک‌تر تقسیم کنید.
پشتیبانی فنی: برای فعال‌سازی کلید، بررسی دسترسی یا دریافت نمونه پاسخ متناسب با مرکز تماس خود، از پنل تلفن ابری همکاران تیکت ثبت کنید.