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 میپردازیم.