Knowlarity Sr Integration Guide Jan 2013 2 4w4c56

Knowlarity-SR Integration Guide January 2013

Knowlarity SuperReceptionist Integration Guide Author: Product Team Knowlarity Communications Pvt Ltd

Page 1

Table of Contents Overview ....................................................................................................................................................... 3 Integration Points with Knowlarity SuperReceptionist................................................................................. 3 What to do API for dynamic call forwarding......................................................................................... 4 Call Data Post API .................................................................................................................................. 4 Kpopup .................................................................................................................................................. 4 Click2call API ......................................................................................................................................... 5 Click2call Widget ................................................................................................................................... 5 Technical Details and APIs ............................................................................................................................ 5 What to do API: call forwarding number(s) .......................................................................................... 5 Call Data Post API: ................................................................................................................................. 5 KPopup Integration: .............................................................................................................................. 6 Click2Call Integration: ........................................................................................................................... 7 How to integrate? ......................................................................................................................................... 7 Configuring your SR ................................................................................................................. 8

Page 2

Overview Knowlarity provides integration framework for third party applications to integrate with its cloud telephony product SuperReceptionist (SR). This document describes that framework. The framework allows third party apps integrate into the flow of the incoming calls in SR based on the app’s requirements and decide what action needs to be performed at the end of the call. For example, a customer might call an SR number of a company for inquiring about a new product. The SR number when integrated with the company’s CRM can in real time query the CRM app to decide which agent to connect the calling customer to. And at the end of the call create an entry in the CRM with call details. Knowlarity also allows third party apps to receive real time events streamed on the interface (UI) of the app and show a popup or message about incoming calls with status. This is very powerful, as it allows the agent to know who is calling with details from the app (e.g. lead status of calling customer) before the agent picks up the call on his / her mobile or landline phone. Details of SuperReceptionist can be found at: www.SuperReceptionist.in.

Integration Points with Knowlarity SuperReceptionist Here are the integration points of SuperReceptionist with 3rd party apps: -

What to do API for call forwarding agents: 3rd party app API which returns in real time the phone number of agents to transfer a particular call to Call Data Post API: 3rd party app API to post the call details after a call is finished Kpopup: Ability to show real time event of an incoming call from within the 3rd party app Click2call API: Ability to place an outgoing call from within the 3rd party app and the call data posted back to the 3rd party app Click2call Widget: Widget to place on website, where customers can enter a number to call back. The widget then initiates the call and connects to the SR number.

Page 3

What to do API for dynamic call forwarding Knowlarity SuperReceptionist allows its customers to create their own IVR flow for incoming calls. Customers can set up rules for: 1. Before answer: Welcome sound to play OR missed call OR direct phone transfer etc. 2. After answer (for a pressed option 0-9): Phone transfer (one or multi agents), fax, conference, voicemail or sound play For phone transfer rule, in “before answer” or “after answer”, an API call can be made to return phone numbers of agents to transfer to. This API is provided by 3rd party apps where it can return a single number or multiple numbers. Certain business logic can be build into this API to decide what agent to connect the call to. For example: A customer calls a company’s SR number to discuss pricing of a product he had enquired about 2 days ago. The CRM can decide based on the caller ID whether to transfer the call to the agent to whom the customer lead is assigned to. The CRM would then return the agent’s phone number for the What to do API. The API can return multiple numbers and also the transfer logic of sequential or parallel calling for multiple agents. This API is provided by 3rd party app company. Call Data Post API At end of a call (incoming or outgoing), Knowlarity SR can post the call details to a 3rd party app to give details of the call. This ensures that each customer phone interaction is logged in the 3rd party system as a complete workflow. A CRM system might want each incoming call to be logged as a lead, a ticket system would want to log each call as a ticket etc. For example: A customer calls a company’s SR number to inquire about a new product. After call is finished, SR will post the call details to the CRM so that a new lead can be created with the caller number and call is logged with date, time and agent details along with call recording link. This API is provided by 3rd party app company. Kpopup During an incoming call Knowlarity SR has ability to inform a 3rd party app in real time along with details of the call in progress. The 3rd party app can show a popup or message about incoming calls with status. This is very powerful, as it allows the agent to know who is calling with details from the app (e.g. lead status of calling customer) before the agent picks up the call. Knowlarity provides JavaScript code for this to the 3rd party app company.

Page 4

Click2call API This allows developers to provide outgoing phone call functionality from within their application. Through a simple HTTP request you can place calls between any two numbers and get them connected. A typical use of this API can be to place a click2call button in your application's interface. At the end of the call the API to post data of the call is executed (discussed above) to ensure the same behavior as an incoming call. Click2call Widget We provide a sample click2call JavaScript widget which can be integrated with your website. Your customers visiting the website can simply enter their phone numbers in the widget and get connected to your SR number or any other number of your wish. The widget is fully customizable.

Technical Details and APIs What to do API: call forwarding number(s) SR allows you to decide the number(s) on which an incoming call is to be forwarded, at run time. i.e. the different numbers can be provided for each incoming call. This is implemented through a WebHook(a HTTP request to your server). The incoming request has the incoming call’s details in the form of parameters and expects a list of numbers as a response. The call is then forwarded to these numbers. Incoming parameters: 

caller_id: Caller’s phone number



dispnumber: SR number on which the call is being made.



extension: DTMF pressed. Possible values (1,2,3...10)



action: Value: “phone”



callid: A unique 36 character long identifier for this call. Ex: a0ea5072-a11e-4a8a-8013512b57c10de7

Expected Response: Comma or Pipeline separated list of numbers Ex: “9912391230,12831923,2312398” and “9912391230|12831923|2312398” The call is forwarded is sequentially to comma separated numbers, but parallely to pipeline separated numbers. Note: A valid response must have only one of either commas or pipes. Both in the same are not allowed. Call Data Post API: SR provides two types of Call Data Post API: a) End of Call Webhook and b) Extension level notification API

Page 5

End of Call Webhook SR provides the functionality to add a Webhook to post the call related data, at the end of each call. The payload When a call end on your SR number, we'll make an HTTP request(GET or POST based on your configuration) to your URL with a payload of the call details. The parameters of the request will be as follows:       

dispnumber: 1234567890 (the number on which we recieved the call, usually your SR number) destination: The agent’s number to whom the call was forwarded. caller_id: Caller’s phone number resource_url: URI of the mp3 file of call recording/voicemail action: fax/phone/voicemail/conference start_time: Start time of the incoming call in the format: 2012-23-11 11:00:12 end_time: End time of the call.

Extension level Notifications API: SR also allows you to configure webhooks at extension level. These extension level API’s can be used to trigger email and SMS notifications as well as some complex webhooks. For example you can create a webhook to make a ticket every time you get a call on say extension 1. You can then get the response parsed in SR and have an email/SMS sent having that value. The key value combination data can be used in Superreceptionist to send SMS/Email notifications. The parameters of the request are the same as End of Call Webhook (above). KPopup Integration: Following JavaScript code is a sample code which clients can embed in their CRM/application UI to subscribe to a push server socket to listen to call transfer events on their SR number, as they happen. <script type="text/javascript" src="http://api.knowlarity.com/socket.io/socket.io.js"> <script type="text/javascript"> var socket = io.connect('http://api.knowlarity.com:8088/'); socket.emit('feedapp', 'kpopup_demo123'); socket.on('message', function(msg) { alert(msg);

Page 6

});

msg returned by socket server will be a JSON string: {"action": "phone", "dtmf_input": 1, "destination": [23456789, 1234589, 432355], "dispnumber": 222222, "caller_id": 123456, “event”:”connecting/ringing/connected/missed”}

Please note: the code line socket.emit will have different values for different applications. Click2Call Integration: SR provides an API for making outbound phone calls to two s and connect them. API details are as follows: URL: http://ww.superreceptionist.in/api/click2call /GET parameters: api_key: Your SR API key. This can be found at you SR ’s Integration > API Key dispnumber: your SR number agent_number: The number to be dialled first. phone_number: The number to connect to after the first placed call has been picked. (optional) response_format = json/xml: Response format of the API request. Default is JSON.

Sample Response: 1) JSON: {“status”:”success/error”, “call_id”:”12345678-1234-123112312312312123”} 2) XML: <status>success/failure 12345678-1234-1231-12312312312123

How to integrate? Knowlarity integration framework has made it easy to help 3rd party apps to integrate with SuperReceptionist.

Page 7

The What To Do and Call Post APIs can be directly plugged into SuperReceptionist. SR also provides to generate API key and code for Kpopup and Click2call which can be inserted inside the 3rd party app. The framework is further enhaced to allow 3rd party app companies to make it easier for it’s customers to integrate with SR or try out SR services. For that Knowlarity’s alliances team formulates a sign up procedure and onboarding plan which allows customers to easily sign up and configure the 3rd party app along with SR without needing technical assistance. This onboarding mechanism makes the 3rd party app like a plugin. Easy to sign up and easy to manage. Configuring your SR All your SuperReceptionist ’s webhooks can be managed at a single place, My Receptionist|Resources| Hook API in your SR . What to do API: You first need to add your API in the hook APIs under resources tab of My Receptionist in your SR . Then for the extension where you want to use this API, set Yes for the field “Use API for Phone#”. Select the relevant API from the drop down. Don’t forget to put a fallback number in the field below so that in case your API fails or returns an invalid response, SR can transfer the call for that extension to a fallback number. Call Data Post API: 1) To configure extension level Call Data Post API, please set Enable Notifications as Yes for that extension and select your webhook from the drop down. This API will be called at end of call only if that particular extension was pressed in that call. 2) To configure end of call Data post API, please add a Post Call Hook rule in rule engine by selecting your API from the drop down. This API will be called for all calls for SR – both incoming and outgoing calls. Kpopup: Go to Integration left menu of your SR . Go to Kpopup right menu. Enable the popup notifications and get the javascript code through Get Widget button. SR needs an API key in order to securely authenticate the your from any application. Click2call API: You can get the code from the Integrations menu of your SR . Go to Click2Call right menu. Click Generate API code or HTML widget code to get the code.

Page 8