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 را پخشمیکند.
#
توابع SmartAPISmartAPI توابع مختلفی دارد که هرکدام کار خاصی را برای شما انجام میدهد،در پایین به بررسی هرکدام میپردازیم.
#
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 میپردازیم.