The Switchvox Extend API by David W. Podolsky Director of Engineering, Switchvox
Jan 02, 2016
The Switchvox Extend API
by David W. Podolsky
Director of Engineering, Switchvox
2Creative Innovation – Customer Satisfaction – Continual Quality Improvement
2
What I am going to talk about
Session 1 : Fundamentals and Components–What is the Switchvox Extend API?–Why is the Switchvox Extend API so important–The Components of the Extend API–Session 1.5 : Switchvox Developer Central and other Developer Tools
Session 2 : Developing Real-World Business Integrations–Introduction to the Doctor’s Office–Creating an Appointment Reminder System –Building a Patient Confirmation IVR–Constructing a Custom Switchboard Panel
Session 3 : The Future and Q/A–Whats coming up in Switchvox and the API –Questions and Answers
The Switchvox Extend APISession 1 : Fundamentals and
Components
by David W. Podolsky
Director of Engineering, Switchvox
4Creative Innovation – Customer Satisfaction – Continual Quality Improvement
4
Elevator Pitch
What is the Switchvox Extend API?
What is Switchvox Developer Central?
5Creative Innovation – Customer Satisfaction – Continual Quality Improvement
5
What is the Switchvox Extend API?
What is the Switchvox Extend API?
The Switchvox Extend API is the way for external applications to exchange information with a Switchvox PBX.
If a developer wants to get information from a Switchvox PBX or wants the Switchvox PBX to talk with an external application, they use the Extend API.
6Creative Innovation – Customer Satisfaction – Continual Quality Improvement
6
What is Switchvox Developer Central?
What is Switchvox Developer Central
Switchvox Developer Central is the online location for developers, resellers, and system integrators to learn, share, and explore ways to integrate a Switchvox PBX with other core business components.
If somone wants to integrate a key business component (say adding a “Call Me” box on their website or integrating a patient database) with a Switchvox phone system, they will go to Developer Central to find out how.
7Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Switchvox Extend GoalsWhats the point....
7
8Creative Innovation – Customer Satisfaction – Continual Quality Improvement
More Ideas...
Communication mechanism for external applications–Windows Applications–Customer Databases–Web Services–Switchvox Examples:
–Windows Switchvox Notifier–Mozilla Firefox Fire Dialer Plugin–Possible Mobile Applications??
Individual Customer Needs. Make it work with your business–Integrate your phone system with your business
Pull Client Records based on phone numbers Tie into Customer Database
–Customize the product for your Business Customer XYZ Switchboard Panel
8
9Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Goals of the Switchvox Extend API
Consolidation Tool for Resellers for Large # of Systems –Use the API to Query what you want to see across all systems
System Health Phone / Voip Provider Connectivity
Full Featured API for developers moving into vertical markets–Hotels ( wakeup calls)–Call Centers ( customer survey )
Create features we don’t even have in the product for customers Night Mode Autodialers IVR Confirmation System
Ways we haven’t even thought of how to use a phone system yet....
9
10Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
10
11Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Extend API Core Methods
What is is?–An XML-based Application Programming Interface (API) that lets your
application do the Switchvox tasks that you would normally do in the Admin or User Tool Suites. Example: Fetch call logs, download voicemail, change call rules, etc.
In Short–Lets your program talk to our PBX with an XML request and get an XML
response back.
Eating our Own Dog Food–We use our Core Methods on many pages and functions found directly in
our product. When you visit our “Manage Extension” page you are actually seeing a call to switchvox.extensions.search. When you are moving your call rules, you are actually calling switchvox.users.callRules.update.
11
12Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Connecting with the Core Methods
Access through an easy url : https://YOUR.PBX.IP/xml
You can even try it through your browser:
Uses Digest Authentication
–You can authenticate as an Administrator or an Extension
–What methods you can call depends on who you are and what permissions you have
12
13Creative Innovation – Customer Satisfaction – Continual Quality Improvement
What kind of information can I get / set?
Extensions–switchvox.extensions.getInfo–switchvox.extensions.search–switchvox.extensions.phones.sip.add–switchvox.extensions.getVoicemailInfo–switchvox.extensions.phones.bulk.upload
Call Logs & Reports–switchvox.callLogs.search–switchvox.callReports.search–switchvox.callReports.phones.search–switchvox.callReports.callQueues.search–switchvox.callReports.ivrs.search–switchvox.callReports.providers.search–switchvox.callReports.did.search
IVR Global Variables• switchvox.ivr.globalVariables.add• switchvox.ivr.globalVariables.getList• switchvox.ivr.globalVariables.remove• switchvox.ivr.globalVariables.update
System Status–switchvox.status.voipProviders.getList–switchvox.status.phones.getList–switchvox.status.telephonyCards.getList–switchvox.systemClock.getInfo
Hardware Status Information–switchvox.status.hardware.getList–switchvox.status.hardware.getMemoryInfo–switchvox.status.hardware.getDiskInfo–switchvox.status.hardware.getLoadInfo
Call Rule Sets• switchvox.users.callRuleSets.getList• switchvox.users.callRuleSets.update• switchvox.users.callRuleSets.remove• switchvox.users.callRuleSets.rules.getList
Call Creation• switchvox.call• switchvox.users.call
13
14Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Much More
Advanced Debugging• switchvox.debug.acli.startSession• switchvox.debug.acli.stopSession• switchvox.debug.acli.sessions.getList• switchvox.debug.acli.sessions.getInfo• switchvox.debug.acli.sessions.getLog• switchvox.debug.pri.startSession• switchvox.debug.pri.stopSession• switchvox.debug.pri.sessions.getList• switchvox.debug.pri.sessions.getInfo• switchvox.debug.pri.sessions.getLog• switchvox.debug.sessions.getTypes• switchvox.debug.sessions.getList• switchvox.debug.pcap.startSession• switchvox.debug.pcap.stopSession• switchvox.debug.pcap.sessions.getList• switchvox.debug.pcap.sessions.getInfo• switchvox.debug.pcap.sessions.getLog
• Access Control• switchvox.accessControl.getList• switchvox.accessControl.getInfo• switchvox.accessControl.add• switchvox.accessControl.remove• switchvox.accessControl.update• switchvox.accessControl.isAllowed
• User Call Creation• switchvox.users.call
• Scheduled Reports• switchvox.scheduler.add• switchvox.scheduler.getInfo• switchvox.scheduler.update• switchvox.scheduler.remove• switchvox.scheduledReports.add• switchvox.scheduledReports.getInfo• switchvox.scheduledReports.getList• switchvox.scheduledReports.update• switchvox.scheduledReports.remove
• Call Creation• switchvox.call
• Get My Info• switchvox.users.getMyInfo
• Call Logs / Reports• switchvox.users.callLogs.search
• Voicemail• switchvox.users.voicemail.getFolderList• switchvox.users.voicemail.getList• switchvox.users.voicemail.getFile• switchvox.users.fax.getFile• switchvox.users.voicemail.getQuota• switchvox.users.voicemail.getUsedSpace• switchvox.users.voicemail.move• switchvox.users.voicemail.forward• switchvox.users.voicemail.remove• switchvox.users.voicemail.markRead• switchvox.users.voicemail.markUnread
• Voicemail Greetings• switchvox.users.voicemailGreetings.add• switchvox.users.voicemailGreetings.getList• switchvox.users.voicemailGreetings.getFile• switchvox.users.voicemailGreetings.update• switchvox.users.voicemailGreetings.remove• switchvox.users.voicemailGreetings.getSettings• switchvox.users.voicemailGreetings.updateSettings• switchvox.users.voicemailGreetingTypes.getList• switchvox.users.voicemailGreetingTypes.activate
• Profile Extra Numbers• switchvox.users.profile.extraNumbers.add• switchvox.users.profile.extraNumbers.getList• switchvox.users.profile.extraNumbers.update• switchvox.users.profile.extraNumbers.remove
• User Call Creation• switchvox.users.call
• System Information• switchvox.users.info.getSoftwareVersion
PBX Updates– switchvox.info.getList– switchvox.info.getMaximumConcurrentCalls– switchvox.info.getPhoneConfigurationTokens– switchvox.info.getSoftwareVersion– switchvox.info.getUserExtensions– switchvox.updates.getList– switchvox.updates.getRenewalDate
Extension Groups– switchvox.extensionGroups.getLis
Outgoing Call Rules– switchvox.outgoingCallRules.getLis
– AND THE LIST KEEPS GROWING.... 14
15Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Sample Request
I want to get a list of all the IVR extensions on my system between extensions 800 and 900.
15
<request method="switchvox.extensions.search"> <parameters> <min_extension>800</min_extension> <max_extension>900</max_extension> <extension_types> <extension_type>ivr</extension_type> </extension_types> </parameters></request>
16Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Example Response
Returns 2 records. Extension 800 which is our Example IVR and also 808 which is our Sales IVR.
16
<response method="switchvox.extensions.search"> <result> <extensions page_number="1" total_pages="1" items_per_page="50" total_items="2"> <extension number="800" status="1" account_id="1153" can_dial_from_ivr="0" display="Example IVR" type="ivr" type_display="IVR" date_created="2008-10-30 20:26:28" ivr_menu_id="7" ivr_menu_name="Example IVR" ivr_menu_entry_point="Beginning" /> <extension number="808" status="1" account_id="1152" can_dial_from_ivr="0" display="Sales" type="ivr" type_display="IVR" date_created="2009-08-26 08:50:05" ivr_menu_id="8" ivr_menu_name="Sales" ivr_menu_entry_point="Beginning" /> </extensions> </result></response>
17Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Developer Central Test Suite
http://developers.digium.com/switchvox/?pageView=testSuite
17
18Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
18
19Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Call Creation API
Actually part of the Core Methods
The Switchvox Extend XML API includes two methods that let you originate phone calls using Switchvox.
switchvox.call–Creates a call in the system between two extensions or external numbers.
switchvox.users.call– Creates a call in the system between the user's extension and another
extension or external number.
19
20Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Sample Request / Sample Response
I want to get a list of all the IVR extensions on my system between extensions 800 and 900.
20
<request method="switchvox.call"> <parameters> <dial_first>95554578299</dial_first> <dial_second>800</dial_second> <dial_as_account_id>1107</dial_as_account_id> </parameters></request>
<response method="switchvox.call"><result>
<call_info dialed_first="101" dialed_second="104" > <variables></variables></call_info>
</result></response>
21Creative Innovation – Customer Satisfaction – Continual Quality Improvement
What you can build
The Call Creation API is used as the back-end calling mechanism in Digium Switchvox's Firefox Fire Dialer, in our Microsoft Outlook Plugin, and Microsoft Office Smart Tags plugin.
We are going to use this API when developing our appointment reminder system for our doctor’s office in our second session.
21
22Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Applications
Plenty of Real World Buiness Opportunities for this.
–Doctors Office - Appointment confirmation system
–Web Store - Order confirmation System
–Sales Lead Generator - Let Us Call you box
–Switchvox - Subscription Reminders
Plenty of Non Real World Business Opportunities as well
22
23Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
23
24Creative Innovation – Customer Satisfaction – Continual Quality Improvement
IVR Web Integration
About IVRS–Interactive Voice Response, or IVR, is an automated menu system (also
known as an auto-attendant) that you can program to greet and interact with your callers. An IVR can provide information to the caller, collect information from the caller, and send the caller to the right extension.
Switchvox IVR Integration–With Switchvox, you can create actions within an IVR that let the caller
interact with a Web-based application.
–Upload, download, and play sound files, and send call-specific data to the application.
IVR Integration Examples–Authenticate Callers against a backend database–Store information inputted / spoken by the user in a database–Read back customer information ( bank totals, delivery dates, etc)–Transfer calls to the last sales rep they talked with–Let patients confirm appointment dates over the phone
(We are going to build this)
24
25Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The IVR Web Service Actions
There a ton of IVR Actions with Switchvox, and below are the ones we use to contact Web Services.
Send Call Values to URL
–Post information about the current call to a Web-based application, and collect XML data to store in IVR variables.
Upload Recorded Sound –Upload a recorded sound to a Web-based application.
Play Sound From URL–Download a sound from a URL, then play that sound to your caller
25
26Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
26
27Creative Innovation – Customer Satisfaction – Continual Quality Improvement
PBX Event Notifications
Switchvox lets you know when something is happening, what event is happening, and information surrounding the event.
On Incoming Call
On Route to Extension
On New Voicemail
On Checked Voicemail
On Agent Logged In
On Agent Logged Out
On Call Hangup
Lets you build what Switchvox does not have
27
28Creative Innovation – Customer Satisfaction – Continual Quality Improvement
PBX Notification Example
Example
Call Routing Engine based on a web service with a backend database
http://192.168.0.100/route.cgi?cid_number=%CALLER_ID_NUMBER%&cid_name=%CALLER_ID_NAME%
Switchvox receives a call, substitutes the variables with their actual values, and sends the request to the URL. In this example, a request would look like this:
http://192.168.0.100/route.cgi?cid_number=8585551212&cid_name=BOB+JOHNSON
After the URL is requested, route.cgi looks up the number 8585551212, decides to route the call to extension 333, and returns the following XML:
<call_info> <transfer_extension>333</transfer_extension> </call_info>
Switchvox receives this XML, and transfers the call to extension 333.
28
29Creative Innovation – Customer Satisfaction – Continual Quality Improvement
PBX Event Notifications
On Incoming Call–Triggered at the beginning of an incoming call.
On Route to Extension–Triggered when a call hits an extension.
On New Voicemail–Triggered when a voicemail message is left for an extension (including a
message forwarded from another extension).
On Checked Voicemail–Triggered when an extension checks its voicemail.
On Agent Logged In–Triggered when a queue member logs into a queue.
On Agent Logged Out–Triggered when a queue member logs out of a queue.
On Call Hangup–Triggered when a call is hung up.
29
30Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Future Additions
On Outgoing Call–Triggers when an outgoing call is made on the system
On Call Answered–Triggers when the call is actually answered
30
31Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
31
32Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Custom Switchboard Panels
Make your own Switchboard panels that refresh on every incoming call.
Bring up useful customer information before call is even answered
Integrate with existing external services
32
33Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Future
Switchboard panels not just in iFrames
Can register for any event that normal panels can–new queue call–queue member login / logout–new call in parking lot–drop targets for transfering a call–all calling events–etc, etc, etc
Leads to building our existing panels when the way you want it
33
34Creative Innovation – Customer Satisfaction – Continual Quality Improvement
The Components of the Switchvox Extend API
Extend API Core Methods
Extend API for Call Creation
IVR Web Integration
PBX Event Notifications
Custom Switchboard Panels
34
The Switchvox Extend APISession 1.5 : Developer Central
by David W. Podolsky
Director of Engineering, Switchvox
36Creative Innovation – Customer Satisfaction – Continual Quality Improvement
Switchvox Developer Central
http://developers.digium.com/switchvox/
36