Monster App Choices: When to use SmartPBX v. Callflows v. APIs

Monster App Choices
SmartPBX vs Advanced Callflows vs APIs

User Story

• A new user wants to understand what application to use for getting started with and managing and maintaining their account.  They are confused about whether to use SmartPBX, Advanced Callflows or system APIs.
• A new user is looking to understand how these applications interact with each other.

Overview

It’s important to understand both SmartPBX and Callflows access the same back end database and use the same APIs to transfer data.   Edits from one app will reflect in the others the next time you load it.  Some apps however, do not provide access to certain settings, either because it is considered more complex and requires admin level understanding, or the setting was added as a new feature not yet updated in an older app.   

This document will share recommendations on when to use each configuration method. In addition it will review some 2600Hz history to give context to the applications and how they evolved. 

 In short

A summary chart of what functionality can be managed in each app is available at the end of this document.  For a detailed overview comparing access to each setting in Callflows v. SmartPBX, go HERE. 

Set up your Initial Account with Account Manager

This will be accomplished with your Account administrator.  Once your initial account has been set up, you will want to personalize it according to your office requirements.   

Get Started with your personalizations with SmartPBX       

Once your account has been set up by an administrator it’s best for as much configuration to be exposed in SmartPBX as possible for End Users to see.   Spend some time stepping through the application and working with the features available for you.  We have a series of User Guides available also, HERE

NOTE:
Make sure you associate a  “Main Extension” to your user name in SmartPBX.  This is required for the comm.io app, and is not available to add in Callflows.  (This is an example of the newer app supporting newer features). If you have set up your user in Callflows already and want to use the comm.io softphone, refer to the comm.io installation and setup document, HERE.

Advanced Functions using Callflows

If it’s not possible to complete your objectives using SmartPBX, use Advanced Callflows.  Some common advanced functions callflows excels at include:

• Creating sub-menus for incoming calls (e.g. Spanish speaking and English speaking).   We have a document HERE that outlines this setup.
• Creating secondary, tertiary, etc. callflows. For example for multiple locations/companies in a single account.
• Creating custom feature codes

Using APIs to develop further customizations

Both SmartPBX and Advanced Callflows ultimately use the same APIs, they are just viewed in different ways. If there’s some function in the Kazoo GUI that you need to do very often, often enough that it’s not efficient to use the GUI, this is an occasion where you use APIs. 

Some common uses for accessing the API directly include:

• Processes not supported by SmartPBX or Callflows
• Integrations with other programs that also use APIs. 
  Examples include billing programs, integration with Salesforce or web pages, etc.
• Repetitive processes that can run in the background and do not need user input (for example, some billing functions).

To start learning the API syntax, watch the network tab and see what APIs are being called while you complete your task in the GUI. Then check the documentation to be sure you fully understand what the API call is actually doing. And write your code to replicate it.  All the documentation for our APIs is available HERE.   

Anything that can be done in our GUI can be done via API as well. Simply open your browser’s development tools feature, watch the network tab and see what APIs are being called while you complete your task in the GUI.  Reconcile this with the API the documentation to be sure you fully understand what the API call is actually doing. And write your code to replicate it.

Notes: 

• Not all APIs are considered stable and available for end user use. Please be sure your API is supported before using them.
• Please take special care and do extensive testing if you want your application to work with SmartPBX.
• When developing using the API always develop against a sandbox environment. Never code against a production cluster.

An example configuration using multiple KAZOO applications

Below are some example configurations where more than one application is accessed.  These include helpful tips on the most efficient ways to achieve this.

• Build a sub-menu into your main number incoming call routing
  If you want to build a sub-menu into your main number config (for example to support multiple languages or departments), this is not possible to do in SmartPBX. 

Here’s a trick we use to streamline this process:

• First, in SmartPBX. build all your ring groups for the sub-menu
   
• Second, in Callflows, build the callflow for the sub-menu.
  Instead of building the menu options all from scratch, use the SmartPBX ring groups you just made.
   
• Third,  while still in Callflows, name the callflow and enable the “List this callflow in Main Number” check box. This will allow you to use the advanced callflow as an option back in SmartPBX’s main number section. With this example, your end users will be able to change the members and order of the sub-menu’s options via the SmartPBX groups section. This keeps the complexity of Advanced Callflows abstracted away from user, and allows them to manage the details of the process using a familiar interface, SmartPBX.

Sample of application best uses

Background of KAZOO’s development and updates

When the KAZOO project first started over 10 years ago, everything was done via json APIs -- there was no GUI (Graphic User Interface). The expectation was the KAZOO platform would serve as a robust engine for companies to use as their back-end and that those companies would build their own GUI to best fit their customer’s needs. 

KAZOO is extremely robust and with this comes complexity however, and many of our clients didn’t want to spend time diving into API docs before they even knew if a project would work for them.  They wanted a quick and easy way to set up an account to test our wares.  

To support these developers 2600Hz made a very basic GUI for the APIs to enable a quick and easy setup for a testing environment.   This original GUI didn’t expose all of the APIs or even all the features of the APIs but it gave developers a head start.  Once they felt confident in the platform, developers used it to enable them to build custom GUIs. 

This served our clients who are sophisticated programmers in their own right well, and they created unique applications as we imagined, and still do.  Their solutions are elegant overlays to the KAZOO engine.  As we grew however, resellers started using the original tool to set up and maintain end user accounts; they requested we provide a more friendly way to enable their end users  to personalize and change their account details without constant support.

This was the driving force behind our Monster-UI framework and SmartPBX application. SmartPBX was built as a general use GUI for Kazoo, one that resellers could hand off to end users.   In making the system more friendly to non-programmers however, we reduced the configuration offerings to a core that most accounts need.  To continue to keep some more complex features accessible for advanced administrator use we ported in the old UI as the Callflows app.   

Some challenges remain with this multi-tiered approach.  Because SmartPBX and Advanced Callflows share the same APIs, you could see callflows created by SmartPBX in the Callflows app, setting an expectation that users could also edit them.  We needed a way to track where the input came from and how to edit it.  To solve this, 2600Hz added metadata to the json API indicating what app that created the callflow. And elements made in SmartPBX were hidden from Advanced Callflows.

This is the state the system exists in today. While most now use Monster UI and SmartPBX, some companies still use Kazoo strictly as a back-end system and use their own GUIs. Developers are still welcome to use the APIs to build their own GUIs. For those developers wanting to use the APIs, but also wanting to use Advanced Callflows, SmartPBX and other Monster UI apps. This is possible as well.  When doing this, however, please take great care in your code to match the formatting that Monster UI apps use as closely as possible. Remember not every single feature of the APIs is available in SmartPBX or even in Advanced Callflows, and SmartPBX expects very particular formatting to work correctly. In all scenarios, thoroughly test your code against a sandbox environment before deploying to production systems.

Additional Resources

	SmartPBX User Guide
	Account Settings Access: Callflows v. SmartPBX
	Advanced Callflow configurations and setup

API References

docs.2600hz.com