The Switchvox Extend API by David W. Podolsky Director of Engineering, Switchvox

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




4

Elevator Pitch

What is the Switchvox Extend API?

What is Switchvox Developer Central?


5



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.


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.


Switchvox Extend GoalsWhats the point....

7


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


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


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



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


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

https://YOUR.PBX.IP/xml


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


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


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>


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>


Developer Central Test Suite

http://developers.digium.com/switchvox/?pageView=testSuite

17

http://developers.digium.com/switchvox/?pageView=testSuite





IVR Web Integration



18


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


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>


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


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





IVR Web Integration



23


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


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





IVR Web Integration



26



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


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

http://192.168.0.100/route.cgi?cid_number=%CALLER_ID_NUMBER%25&cid_name=%CALLER_ID_NAME%25

http://192.168.0.100/route.cgi?cid_number=8585551212&cid_name=BOB+JOHNSON



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


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





IVR Web Integration



31



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


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





IVR Web Integration



34

The Switchvox Extend APISession 1.5 : Developer Central




Switchvox Developer Central

http://developers.digium.com/switchvox/

36

http://developers.digium.com/switchvox/

Documents

The Switchvox Extend API by David W. Podolsky Director of Engineering, Switchvox