پرش به مطلب اصلی

Smart API

SmartAPI کامپوننتی نیمه‌تعاملی است که درجهت اجرای ترکیبی از دستورات در سرور استفاده می‌شود. دستورها را ازطریق وب‌‌سرویس دریافت و آنها را به‌ترتیب روی تماس‌‌ها اعمال‌ می‌کند و درصورت ایجاد خطا در یک دستور، اجرای بقیه دستورات نیز متوقف‌ می‌شود. درنظر داشته‌باشید می‌توان برای این کامپوننت‌ چندین خروجی با نام‌‌های متفاوت ایجاد و انتقال تماس به این خروجی‌‌ها را نیز مدیریت کرد.

پارامتر کامپوننت​

  • API Address: آدرس وب‌‌سرویس برای دریافت رشته دستورات اجرایی.

پارامتر‌های مسیر‌دهی در کامپوننت​

  • Case: شناسه خروجی.توسط تابع Exit (درجواب وب‌سرویس)استفاده‌ می‌شود.
  • Text: نامی است که تنها برای نمایش در ظاهر کامپوننت استفاده‌ می‌شود و‌ می‌توان برای سهولت در دسترسی از آن بهره برد.
هشدار

درصورت بروز خطا در اجرای دستورات و یا عدم دریافت پاسخ صحیح از طرف وب‌‌سرویس، تماس از خروجی e خارج‌ می‌شود.

قالب وب‌‌سرویس​

با‌توجه به مقادیر منوی تنظیمات مربوط به API Method & API Version، آدرس وب‌سرویس فراخوانی شده و داده‌های زیر همراه با آن ارسال می‌گردند.

  • src: شماره تماس‌‌گیرنده (Caller یا CID).
  • dst: شماره واردشده (Callee یا DID یا Exten).
  • data: داده‌‌ای که تماس‌‌گیرنده در مسیر تماس وارد کرده است (مثلاً داده‌‌ای که در IVR وارد کرده است).
  • unique_id: شناسه یکتای تماس.
  • app_name: نام کامپوننت جاری.

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

{
  "ok": "1",
  "commands": "PlayAnnouncement('announce01'); SayNumber(5201); PlayAnnouncement('announce02');"
}

دستور فوق ابتدا فایل صوتی announce01 را پخش‌می‌کند و سپس عدد پنج هزار و دویست‌ویک را می‌خواند و در مرحله آخر فایل صوتی announce02 را پخش‌می‌کند.

توابع SmartAPI​

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

PlayAnnouncement​

خواندن آوای‌صوتی (فایل صوتی باید قبلا در قسمت آوا‌ها آپلود شده باشد). ورودی تابع، نام آوا یا شناسه آن است (برای شناسه، عبارت :id را قرار دهید).

Format: PlayAnnouncement(<file:string >);

PlayAnnouncement('id:5be6a5f294c28e3f068b4575');

PlayAnnouncement ('filename-nasim');

Playback​

آوا‌های پیش‌فرض سرور را اجرا‌ و در ورودی، نام آوا را دریافت‌ می‌کند.

Format: Playback(<default-file-name:string >);

Playback('hello-world');

SayNumber​

یک شماره را به‌صورت پیوسته‌ می‌خواند (در مثال زیر‌ می‌خواند: پنج هزار و دویست و یک).

Format: SayNumber(<number:int>);

SayNumber(5201);

SayDigit​

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

Format: SayDigit(<number:int>);

SayDigit(1239);

SayDuration​

مدت زمان را می‌خواند (در مثال زیر می‌خواند: شش روز و شانزده ساعت و پنجاه و یك ثانیه).

Format: SayDuration(<time:string(d.HH:MM:SS)>);

SayDuration('6.16:0:51');

SayClock​

ساعت را می‌خواند (در مثال زیر : دوازده ساعت و چهارده دقیقه و نه ثانیه).

Format: SayClock(<time:string(HH:MM:SS)>);

SayClock('12:14:09');
نکته

ورود ثانیه در این تابع اختیاری می‌باشد.

SayDate​

تاریخ را‌ می‌خواند (در مثال زیر می‌خواند: بیست و یک، اردیبهشت، یک هزار و سیصد و نود و پنج).

Format: SayDate(<date:string(YYYY-MM-DD)>, <calendar:string(gregorian/jalali/hijri)>);

SayDate('1395-02-21', 'jalali');

GetData​

دریافت عدد از کاربر.

Format: GetData(<file:string>, <timeout:int>, <max-digit:int>);

GetData('filename-please-enter-number', 10, 1);

با استفاده از عبارت :id در ابتدای نام فایل، می‌توان شناسه آوا را وارد كرد.

نکته

برای خواندن چند فایل در تابع GetData، از عملگر & به روش زیر استفاده می شود.

GetData('filename01&filename03&filename03', 10, 1);

MusicOnHold​

نام کلاس آوای انتظار و مدت زمان (به ثانیه) پخش آن را دریافت می کند.

Format: MusicOnHold (<class_name:string >, <duration:int >);

MusicOnHold(‘default’, 60);

SetExten​

مقدار Exten را اعمال می کند(برای اتصال به داخلی).

Format: SetExten(<exten:string>);

SetExten(‘200’);

SetLimitOnCall​

برای تماس بعدی محدودیت زمانی اعمال می‌کند. (پارامتر ورودی به ثانیه می باشد).

Format: SetLimitOnCall(<limit:int>);

SetLimitOnCall(150);

ClearUserData​

این دستور داده‌هایی که مراحل قبل در Smart API وارد شده‌اند را پاک می‌کند(برای مثال زمانی که setExten را فرخوانی می‌کنید در مواردی باید این تابع نیز فرخوانی شود).

Exit​

انتخاب یكی از مسیرهای خروجی برای خروج از كامپوننت. این تابع همیشه آخرین تابع در اجراست، درنظر داشته باشید بعد از آن تابع دیگری اجرا نخواهد شد و تماس از کامپوننت SmartApi خارج‌ می‌شود. درصورتی‌‌كه case وجود نداشته باشد، اجرا با خطا مواجه می‌شود.

Format: Exit(<case:string>);

Exit('3');

در‌جهت آشنایی بیشتر در بخش مثال‌های کاربردی به بررسی پیاده‌سازی سناریو با استفاده از smartapi می‌پردازیم.