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

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: نام کامپوننت جاری.
  • originated_call_id: شناسه یکتای تماس دو طرفه
نکته

originated_call_id یا شناسه یکتای تماس دو طرفه، فقط در زمان برقراری تماس دو طرفه ارسال می شود.

و در جواب، خروجی زیر را به‌صورت 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 می‌پردازیم.