رفتن به مطلب اصلی
Version: v6.4.0 مرکز‌تماس

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