معرفی و تنظیمات

معرفی Simotel API

SA مجموعه ای از APIها هستند که با ارسال درخواست از سمت وب‌سرویس به سمت سیموتل شروع می‌شوند، این سرویس در قالب استاندارد REST API ایجاد گردیده است. برای مثال با ارسال درخواست تماس دوطرفه از سمت وب‌سرویس به سمت سیموتل، پس از دریافت درخواست مرکز تماس شروع به ایجاد تماس دوطرفه می‌کند.

تنظیمات راه‌اندازی Simotel API

• ایجاد حساب برای درخواست دهنده.
• تعیین IP‌های مجاز به ارسال درخواست.

ایجاد حساب

به بخش Maintenance > API Accounts مراجعه فرمایید. با کلیک بر روی ➕ امکان ساخت کاربر جدید فراهم می‌شود، پارامترهای این بخش به شرح زیر می‌باشند:

• Authentication: سیموتل از روش‌های مختلفی برای احراز هویت کاربر درخواست دهنده استفاده می‌کند، امن‌ترین روش؛ استفاده از BasicAuth (نام‌کاربری و رمزعبور) به همراه API Key (Token) است.

• Username: نام‌کاربری کاربر ساخته شده.

• Password: رمزعبور کاربر ساخته شده.

• Token: رشته‌ای که در جهت احرازهویت قوی‌تر تولید می‌شود.

• Enabled: امکان فعال یا غیر‌فعال‌سازی کاربر را در اختیار شما قرار می‌دهد.

• Request: میزان سطح دسترسی کاربر به APIها را مشخص می‌کند، برای مثال در صورت نیاز به افزودن کاربر با استفاده از API حتما باید تیک /pbx/users/add فعال شود.

ایجاد دسترسی برای IP

به بخش Maintenance > Settings مراجعه فرمایید. در پایین صفحه بخش Simotel API دو بخش مشاهده می‌شود:

• Allow All IPs: با زدن تیک این بخش دسترسی تمامی IPها برای ارسال درخواست به سمت سیموتل باز می‌شود.

• Allowed IPs: در صورتی‌که IP خاصی مد نظر است در این بخش وارد کنید و در نهایت دکمه Enter را بزنید.

اعتبارسنجی

اعتبارسنجی به یکی از سه روش زیر انجام می‌گردد:

• HTTP Basic authentication: استاندارد Basic authentication روشی عمومی برای اعتبارسنجی در وب‌سرویس‌ها است. بازیابی اطلاعات دسترسی در این روش، به دلیل امنیت پایین آن بسیار ساده است و توصیه می‌گردد که حداقل به‌صورت SSL استفاده گردد. اطلاعات مربوط به یوزر و پسورد با فرمت base64 در هدر درخواست به‌صورت زیر قرار میگیرد.

Authorization: Basic dGVzdDpBYTEyMzQ1Ng

Basic Auth را می‌توان در آدرس به‌صورت زیر نیز ارسال کرد

https: //username: password@www. example. com

• API Key: در این روش که برای بهبود امنیت روش قبلی ایجاد‌شده و به‌صورت گسترده در APIها استفاده می‌گردد، کلیدی یکتا ایجاد می‌گردد و در هدر درخواست به‌صورت زیر اضافه می‌شود.

X-APIKEY: SAMPLE_API_KEY

• HTTP Basic authentication & API Key: در این روش از ترکیب دو روش بالا استفاده می‌گردد.

Authorization: Basic dGVzdDpBYTEyMzQ1Ng

X-APIKEY: SAMPLE_API_KEY

نمونه Header

Authorization: Basic dGVzdDpBYTEyMzQ1Ng==
X-APIKEY: SAMPLE_API_KEY
Content-Type: application/JSON

• Authorization: اعتبار سنجی Basic Authentication.
• X-APIKEY: اعتبار سنجی API-key.
• Content-Type: فرمت بدنه پیام. در تمام درخواست‌ها به غیر از سرویس‌های دانلود و استریم، فرمت بدنه پیام application/JSON است.

پیام‌های رایج در پاسخ به درخواست

انواع پاسخ هایی که در سرویس‌های SA دریافت می‌شود به شرح زیر است.

پارامترهای Pagination

این پارمترها نحوه نمایش اطلاعات بازیابی شده از مرکزتماس را مشخص می‌کنند، از آنجایی که این پارمتر‌ها در اکثر APIهای مربوط به جست‌وجو موجود می‌باشند در اینجا یکبار به‌صورت جزئی مورد بررسی قرار می‌گیرند.

لیست APIهایی که از این پارامترها پشتیبانی می‌کنند

1. pbx/faxes/

2. voicemails/inbox/

3. reports/quick/

4. reports/cdrreports/queue/

5. reports/queue/

6. reports/queue_details/

7. reports/agent/

8. reports/poll/

9. autodialer/campaigns/

10. autodialer/contacts/

11. autodialer/groups/

12. autodialer/reports/

start

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

count

چه تعداد از داده‌های بازیابی شده توسط مرکز تماس به سمت وب‌سرویس ارسال شود.

sorting

مرتب سازی داده‌ها براساس کدام ستون و به ترتیب صعودی یا نزولی باشد (مقدار ۱ برابر با صعودی و مقدار ۱- برابر با نزولی است).

• مثال) بازیابی اطلاعات بخش گروه‌ها به نوعی که

  1. از ۴امین رکورد، اطلاعات بازیابی شده توسط مرکزتماس به سمت وب‌سرویس ارسال شوند.

  2. به‌طور کلی ۲ رکورد از داده‌های بازیابی شده بازگردانده شود.

  3. گزارش بازگشتی براساس تاریخ و به‌صورت صعودی مرتب باشد.

{
    "alike": "true",
    "conditions": {"name": "","description": ""},
    "pagination": {"start": 4,"count": 2,"sorting": {"date": 1}}
}

{
    "success": 1,
    "message": "",
    "data": {
        "pagination": {
            "start": 4,
            "count": 2,
            "sorting": {
                "date": 1
            },
            "total": 17
        },
        "data": [
            {
                "_id": "5cab4ed776c2c0747f3a7f7b",
                "name": "nasim-contact-update-980119",
                "description": "",
                "count": 109,
                "date": "1398-01-19 18: 08: 31"
            },
            {
                "_id": "5cac595276c2c011a94f4b43",
                "name": "nasimcontact-step2",
                "description": "",
                "count": 101,
                "date": "1398-01-20 13: 05: 30"
            }
        ]
    }
}

پارامترهای ضروری و منطقی

درآینده در جداول با ستونی به نام پارمترهای ضروری[**]/منطقی[*] مواجه می‌شویم که مقادیر آن مشخص کننده

1. پارامترهای ضروری: حتما باید این مقادیر در درخواست وب‌سرویس به سمت سیموتل ارسال شوند و در غیر این صورت سیموتل در پاسخ خطا برمی‌گرداند.

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