# GET /asterisk/channel/status

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">GET</td><td dir="ltr">/api/v2/asterisk/channel/status</td><td dir="ltr">AsteriskAmiController@getChannelStatus</td><td dir="ltr">authWithJwt</td><td dir="rtl">بررسی وضعیت یک کانال مشخص در Asterisk AMI براساس نام کانال</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **getChannelStatus** به سرور AMI وصل می‌شود و وضعیت دقیق یک Channel مشخص را برمی‌گرداند. درخواست، نام کانال در حال برقراری تماس (مثل `SIP/2001‑0000004e`) را دریافت کرده و با ارسال دستور `ChannelStatus` به AMI، اطلاعات فعلی (نظیر CallerID، state، context، application و duration) را بازمی‌گرداند.

<div id="bkmrk-%D8%AE%D9%88%D8%A7%D9%86%D8%AF%D9%86%E2%80%AF%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%E2%80%AFchann" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">1. خواندن پارامتر `channel` از query string.
2. فراخوانی `Ami::sendAction('ChannelStatus', ['Channel' => $channel])`.
3. در صورت یافتن کانال فعال، پاسخ ساخته می‌شود با فیلدهای State، CallerID، Duration و Application.
4. در صورت نبود کانال یا خطا، پاسخ با status=false و کد ۴۰۴ بازگردانده می‌شود.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%85%D8%AD%D9%84-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>محل</td><td>نوع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>channel</td><td>Query</td><td>string</td><td>بله</td><td>نام کانال مثلاً `SIP/2001‑0000004e`</td></tr></tbody></table>

</div>### ساختار خروجی موفق

```
{
  "status": true,
  "message": "Channel found",
  "data": {
    "channel": "SIP/2001-0000004e",
    "caller": "09132223344",
    "context": "from-internal",
    "state": "Up",
    "application": "Dial",
    "duration": "00:02:34"
  }
}
```

### ساختار خروجی خطا

```
{
  "status": false,
  "code": 404,
  "error": "Channel not found or inactive"
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C%E2%80%AF%D8%A8%D9%87%E2%80%AF%D8%A7%DB%8C%D9%86%E2%80%AF%D9%85%D8%B3%DB%8C%D8%B1%E2%80%AF%D9%81" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- دسترسی به این مسیر فقط برای کاربران دارای نقش مدیریت تلفنی فعال می‌باشد.
- در پاسخ هیچ دادهٔ حساس مثل authkey یا secret خطوط نمایش داده نمی‌شود.
- درخواست‌های بیش از ۳ در هر ۵ ثانیه rate‑limit می‌شوند.

</div>### نکات عملکردی

<div id="bkmrk-%D9%85%DB%8C%D8%A7%D9%86%DA%AF%DB%8C%D9%86%E2%80%AF%D8%AA%D8%A7%D9%94%D8%AE%DB%8C%D8%B1%E2%80%AF%D9%BE%D8%A7%D8%B3%D8%AE%3A" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- میانگین تأخیر پاسخ: ~۴۰ میلی‌ثانیه.
- در صورت Load بالا، از cache با TTL=2 ثانیه برای کانال استفاده می‌شود.

</div>### Dependencies

<div id="bkmrk-use%E2%80%AFapp%5Cservices%5Cami" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use App\\Services\\Ami;
- use Illuminate\\Http\\Request;
- use Exception;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-401-%D8%AA%D9%88%DA%A9%D9%86" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>401</td><td>توکن JWT نامعتبر</td><td>Middleware</td></tr><tr><td>404</td><td>کانال پیدا نشد</td><td>AMI Response</td></tr><tr><td>500</td><td>خطای ارتباط با AMI</td><td>Exception</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%E2%80%AFchannel%E2%80%AF%D8%B1%D8%A7%E2%80%AF%D9%88" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- پارامتر `channel` را ورودی user‑validated قرار دهید تا از injection در AMI Action جلوگیری شود.
- فقط در محیط داخلی به AMI دسترسی دهید.

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86%E2%80%AF%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%E2%80%AF%3Ffiel" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن پارامتر `?fields=state,duration` برای واکنش سریع‌تر.
- اتصال real‑time با socket برای به‌روزرسانی‌های وضعیت کانال.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D8%AB%D8%A8%D8%AA%E2%80%AF%D8%AF%D8%B1%E2%80%AF%D8%AC%D8%AF%D9%88%D9%84%E2%80%AFsystem_l" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت در جدول `system_logs` با کلید `ami_channel_status`.
- فیلدها: `operator_id, channel, result, timestamp`.

</div>### جمع‌بندی

**getChannelStatus** ابزار پایش دقیق و بلادرنگ هر کانال در سیستم تماس VoIP است و به ادمین‌ها امکان عیب‌یابی سریع ارتباطات را می‌دهد.

<div id="bkmrk-asterisk-get-channel-status" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>