وب‌سرویس مرکز تماس

https://api.hamkaran.cloud/api/hamkaran/v2

key: YOUR_WEBSERVICE_KEY
Accept: application/json
Content-Type: application/json

export HAMKARAN_WEBSERVICE_KEY='YOUR_WEBSERVICE_KEY'

curl --request GET 'https://api.hamkaran.cloud/api/hamkaran/v2/extension' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json'

{
  "status": "success",
  "data": [
    {
      "extension": "200",
      "registered": true,
      "state": "NOT_INUSE",
      "observed_at": 1789545600
    }
  ]
}

Idempotency-Key: crm-ticket-4821-call-001

{
  "message": "The given data was invalid.",
  "errors": {
    "timeout": ["The timeout must be between 5 and 60."]
  }
}

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/reports' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'date_from=2026-09-09' \
  --data-urlencode 'date_to=2026-09-16' \
  --data-urlencode 'internalnumber=200' \
  --data-urlencode 'direction=in' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'sort=date' \
  --data-urlencode 'order=desc'

{
  "data": [
    {
      "call_id": "11111111-1111-4111-8111-111111111111",
      "caller": "9120000001",
      "callee": "200",
      "call_date": "2026-09-16 10:30:00",
      "direction": "in",
      "answered": 1,
      "wait_sec": 12,
      "ring_sec": 6,
      "bill_sec": 45,
      "duration_sec": 57,
      "hangup_cause": "NORMAL_CLEARING",
      "identity": {"name": "مخاطب نمونه", "source": "contacts"},
      "destination_identity": null,
      "recordings": []
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/call' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'call_id=11111111-1111-4111-8111-111111111111'

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/dashboard' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'date_from=2026-09-09' \
  --data-urlencode 'date_to=2026-09-16'

curl --fail-with-body --request POST \
  'https://api.hamkaran.cloud/api/hamkaran/v2/get_record' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"call_id":"11111111-1111-4111-8111-111111111111"}' \
  --output call-record.wav

{
  "call_id": "11111111-1111-4111-8111-111111111111",
  "track": "mixed"
}

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/voicemails' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'page=1'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/create_call' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-call-001' \
  --data '{"src":"200","dest":"09120000001","timeout":30}'

{
  "operation_id": "22222222-2222-4222-8222-222222222222",
  "action_id": "22222222-2222-4222-8222-222222222222",
  "actionId": "22222222-2222-4222-8222-222222222222",
  "status": "queued",
  "result": null
}

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/operations' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'operation_id=22222222-2222-4222-8222-222222222222'

{
  "operation_id": "22222222-2222-4222-8222-222222222222",
  "action_id": "22222222-2222-4222-8222-222222222222",
  "actionId": "22222222-2222-4222-8222-222222222222",
  "status": "succeeded",
  "result": {
    "call_id": "11111111-1111-4111-8111-111111111111",
    "state": "accepted",
    "job_id": "33333333-3333-4333-8333-333333333333"
  }
}

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/hang_up_call' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-hangup-001' \
  --data '{"call_id":"11111111-1111-4111-8111-111111111111"}'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/play_audio_on_channel' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-audio-001' \
  --data '{
    "call_id":"11111111-1111-4111-8111-111111111111",
    "leg_id":"44444444-4444-4444-8444-444444444444",
    "audio":"welcome.wav"
  }'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/transfer' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-transfer-001' \
  --data '{
    "call_id":"11111111-1111-4111-8111-111111111111",
    "leg_id":"44444444-4444-4444-8444-444444444444",
    "dest":"201",
    "mode":"attended"
  }'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/conference_start' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-room-001' \
  --data '{
    "call_id":"11111111-1111-4111-8111-111111111111",
    "leg_id":"44444444-4444-4444-8444-444444444444"
  }'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/conference_invite' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-ticket-4821-invite-001' \
  --data '{
    "call_id":"11111111-1111-4111-8111-111111111111",
    "leg_id":"44444444-4444-4444-8444-444444444444",
    "dest":"09120000001"
  }'

{
  "call_id": "11111111-1111-4111-8111-111111111111",
  "leg_id": "55555555-5555-4555-8555-555555555555",
  "muted": true
}

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/send-pre-recorded' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: reminder-order-4821-001' \
  --data '{"src":"02190000000","dest":"09120000001","audio":"reminder.wav","timeout":30}'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/get-pre-recorded-call-detail' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"actionId":"22222222-2222-4222-8222-222222222222"}'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/send-otp' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: verification-session-4821-001' \
  --data '{"src":"02190000000","dest":"09120000001","code":"048291","timeout":30}'

curl --request POST 'https://api.hamkaran.cloud/api/hamkaran/v2/queue_control' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "id":"66666666-6666-4666-8666-666666666666",
    "extension":"200",
    "action":"join",
    "queue_code":"21"
  }'

curl --get 'https://api.hamkaran.cloud/api/hamkaran/v2/queue_operation' \
  --header "key: $HAMKARAN_WEBSERVICE_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'id=66666666-6666-4666-8666-666666666666'

import { setTimeout as sleep } from 'node:timers/promises';

const base = 'https://api.hamkaran.cloud/api/hamkaran/v2';
const key = process.env.HAMKARAN_WEBSERVICE_KEY;
if (!key) throw new Error('HAMKARAN_WEBSERVICE_KEY is required');

async function request(path, { body, requestId } = {}) {
  const response = await fetch(base + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      key,
      Accept: 'application/json',
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(requestId ? { 'Idempotency-Key': requestId } : {}),
    },
    ...(body ? { body: JSON.stringify(body) } : {}),
    signal: AbortSignal.timeout(15000),
  });
  const data = await response.json();
  if (!response.ok) {
    // Do not log request headers or OTP values.
    throw new Error('HTTP ' + response.status + ': ' + (data.message || 'API error'));
  }
  return data;
}

// Persist this value with the CRM task. Reuse it after a network timeout.
const requestId = 'crm-ticket-4821-call-001';
let operation = await request('/create_call', {
  body: { src: '200', dest: '09120000001', timeout: 30 },
  requestId,
});

for (let attempt = 0; attempt < 10; attempt++) {
  if (!['queued', 'running'].includes(operation.status)) break;
  await sleep(5000);
  operation = await request(
    '/operations?' + new URLSearchParams({ operation_id: operation.operation_id })
  );
}

console.log({
  operation_id: operation.operation_id,
  status: operation.status,
  call_id: operation.result?.call_id,
});

// "succeeded" + "accepted" is not proof of an answered call.
// Continue with call.connected / call.cdr webhooks.
// If still queued/running, retain operation_id and check later.
// Never automatically redial an "unknown" operation.

import { writeFile } from 'node:fs/promises';

const query = new URLSearchParams({
  date_from: '2026-09-09',
  date_to: '2026-09-16',
  page: '1',
  limit: '25',
});
const report = await request('/reports?' + query);
console.log({ total: report.total, page: report.page });

const callId = '11111111-1111-4111-8111-111111111111';
const response = await fetch(base + '/get_record', {
  method: 'POST',
  headers: { key, 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ call_id: callId }),
  signal: AbortSignal.timeout(30000),
});
if (!response.ok) throw new Error('Recording HTTP ' + response.status);
await writeFile('call-record.wav', Buffer.from(await response.arrayBuffer()));
// Store recordings in private storage. For large files, stream to disk.

return [
    // Other service configurations...
    'hamkaran' => [
        'key' => env('HAMKARAN_WEBSERVICE_KEY'),
        'base_url' => 'https://api.hamkaran.cloud/api/hamkaran/v2',
    ],
];

use Illuminate\Support\Facades\Http;

$base = config('services.hamkaran.base_url');
$key = config('services.hamkaran.key');
$requestId = 'crm-ticket-4821-call-001'; // Persist with the CRM task.

$response = Http::withHeaders([
    'key' => $key,
    'Accept' => 'application/json',
    'Idempotency-Key' => $requestId,
])->connectTimeout(3)->timeout(15)->post($base . '/create_call', [
    'src' => '200',
    'dest' => '09120000001',
    'timeout' => 30,
]);

$response->throw();
$operation = $response->json();
$operationId = $operation['operation_id'];

// In a later queued job, query the same operation.
// Do not keep a web request blocked while waiting for a call.
$result = Http::withHeaders([
    'key' => $key,
    'Accept' => 'application/json',
])->connectTimeout(3)->timeout(15)->get($base . '/operations', [
    'operation_id' => $operationId,
])->throw()->json();

// queued/running: schedule another bounded check.
// unknown: reconcile with call events before any new request.
// succeeded: inspect result; accepted is not an answered call.

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$headers = [
    'key' => config('services.hamkaran.key'),
    'Accept' => 'application/json',
];
$base = config('services.hamkaran.base_url');

$report = Http::withHeaders($headers)->timeout(20)
    ->get($base . '/reports', [
        'date_from' => '2026-09-09',
        'date_to' => '2026-09-16',
        'internalnumber' => '200',
        'page' => 1,
        'limit' => 25,
    ])->throw()->json();

$recording = Http::withHeaders($headers)->timeout(30)
    ->post($base . '/get_record', [
        'call_id' => '11111111-1111-4111-8111-111111111111',
        // 'track' => 'mixed', // Optional conference mix.
    ])->throw();

// Use a private disk; do not publish the recording URL.
Storage::disk('local')->put('private/calls/example.wav', $recording->body());