KooKoo Tunes

KooKoo tunes is nothing but the name given to markup language which powers the KooKoo platform. Using different KooKoo tunes you can make your application sing :). The heart of the KooKoo platform is a simple request response model. Your web application requests the platform to perform a specific action like play some text, collect some user input or record user voice etc. KooKoo performs the action and responds with a result if a result exists. The following are the KooKoo tunes available at your disposal:

  1. response: This is the root tag
  2. playtext: Play some text to your callers
  3. Say-As: Play some dynamic values like date ,currency ,numbers etc in different languages
  4. playaudio: Play some audio to your callers
  5. collectdtmf: Collect user input from your callers
  6. record: Record caller conversation
  7. conference: Conference multiple callers
  8. hangup: Disconnect current caller
  9. dial: Make an outbound call (Available only to paid users)
  10. gotourl: Application flow jump's to the next flow in the URL given
  11. recognize: To recognize single digits ,yes/no over voice

response:

  • Description:This is the all enclosing root tag. You web application should enclose all other tags inside this root tag.
  • Attributes:
    • sid:Can be used by your web application for session tracking purposes
    • filler:Filler audio attribute. Can be "yes" or "no"
      Use Case: With the addition of filler audio attribute to the response tag, you can now play a wait music when you are doing a lot of processing

      How to use: If you think, the next action from the customer will involve a lot of processing from your side and the customer has to wait, then include the attribute filler="yes" in your response.

      Explanation:
      When, KooKoo sees this attribute, it will first do all the tasks specified by you in the response, and then it will make a Get request to your application and parallely play the filler audio when the customer is waiting.
  • Examples:
    1. Simple response

       
      <?xml version="1.0" encoding="UTF-8"?>
      <Response> 
          <playtext>Hello World</playtext>
      </Response>
                                                  

    2. Simple response with sid

      <?xml version="1.0" encoding="UTF-8"?>
      <Response sid="12345"> 
          <playtext>Hello World</playtext>
      </Response>
                                                  

playtext:

  • Description:This tag informs KooKoo to play the text specified in the tag using the text to speech engine.
  • Attributes: Very soon we will add attributes to this tag to allow you choose the language, TTS engine as well as male or female voice.
    • quality=quality can be best,normal
    • speed =speed used for voice-rate speed limit form 1-9 //if speed 1 plays slow, speed =9 plays fastly, this is only for professional tts
  • Examples:

     
    <?xml version="1.0" encoding="UTF-8"?>
    <response> <playtext quality="best">Hello World</playtext>
    </response>
  • Points to remember:
    • The larger the text, the longer it takes for the TTS engine to process the file. For example, if you have 40 seconds of text to be spoken, it will take about 4-5 seconds to process and if you have 60 seconds of text then it may take around 6-7 seconds. But this will be only for the first time as we cache the TTS text also.
    • KooKoo caches your TTS text so everytime we need not generate the speech
    • When translating text to speech, KooKoo makes assumptions about how to pronounce numbers, dates, times, amounts of money and other abbreviations. Test these situations well. Or you could use Say-as tag.
    • When saying numbers, '567' will be spoken as "five hundred and sixty seven" Whereas "5 6 7 " will be spoken as "five six seven".
    • Free accounts get access to the open source TTS engine whereas paid accounts get access to a more professional speech engine
    • Though we have the best TTS engines available,they are no replacement for Human Voice. So use this tag sparingly. Wherever there is static content, considering recording the content using a human and then play that using the playaudio tag instead of playtext. Use playtext mainly for dynamic content and testing your call flow.
    • KooKoo caches your TTS audio. Make sure you use the cache properly. If you have a large text to be played out, break it up into static and dynamic parts for the best user experience. Let us say you want to play out, "Thank you for registering. Your id is 1 2 3 4. Let us know if you have any queries". Don't put everything in one playtext tag. Instead do something like <playtext>Thank you for registering. Your id is </playtext> <playtext>1 2 3 4 </playtext> <playtext> Let us know if you have any queries. </playtext>

Say-As:

  • Description:To play dynamic values such as date,currency,number etc.
  • Attributes:
    • format= format code to be given for playing date,currency,number.Format code listed below are applied to all the languages.
    • Format code's for attribute language english, you can use the same code for other languages listed given

      FormatCodeTextLangPlay As
      Date20120110721ENThursday July 21st 2011
      Date20220110721ENJuly 21st 2011
      Date20420110721ENJuly 21st
      Currency40253ENFifty three rupees and zero zero paise
      Currency40153ENit ignores numbers after decimal point
      Digits5011234ENone two three four
      Number11234ENone thousand two hundred and thirty four
    • lang= language code to be given in below format to play in that particular language.
    • english => EN,hindi => HI,kannada =>KA,Malayalam=> ML,Telugu => TE,Tamil=>TN,Gujarati=> GUJ, Benagali=>
      BN,Marathi=> MR,Oriya=> ORI
    • Examples 1: To play characters
       
      <?xml version="1.0" encoding="UTF-8"?>
      <response> <say-as format="501" lang="EN">123ABC</say-as>
      </response>
      It will be played as "one two three A B C";

      Examples 2: To play date
       
      <?xml version="1.0" encoding="UTF-8"?>
      <response> <say-as format="222" lang="EN">20121227ABC</say-as>
      </response>
      It will be played as "December 27 2012";

playaudio:

  • Description:This tag informs KooKoo to play the audio specified in the tag. The audio file must be specified as an URL. KooKoo will download the URL and try to play the audio for you. The audio file should be a 16 bit mono 8000Hz file. Audio preparation details can be found here
  • More formats will be supported soon.
  • Attributes:None
  • Examples:

     <?xml version="1.0" encoding="UTF-8"?>
    <response> <playaudio>http://www.ozonetel.com/test.wav</playaudio>
    </response>
  • Points to remember:
    • KooKoo will cache your audio file the first time it is played. So the first time there will be a little bit of a delay as KooKoo downloads the audio file. Next time onwards, there will be no delay.
    • KooKoo will convert your audio file to the telephony native format, so there maybe some loss of quality. So try to provide an audio which is recorded at 8000 samples/sec

collectdtmf:

  • Description: This tag is used to collect user input through dialpad. We can nest either the playtext or playaudio tag inside this tag to prompt the user to enter some input. KooKoo collects the user input and informs your web application through a GotDTMF event which your webapplication should handle.
  • Attributes:
    • l=Maximum number of digits to accept.Default value is unlimited.
    • t=The terminating chracter. KooKoo will stop accepting input after receiving this character. Default value is '#'.
    • o=Timeout. KooKoo will wait for 'o' milliseconds for the user to enter some input. Default value is 4000 (4 seconds).
  • Examples:

     <?xml version="1.0" encoding="UTF-8"?>     
    <response sid="12345">
    <collectdtmf l="4" t="#" o="5000">
    <playtext>Please enter your pin number
    </playtext>
    </collectdtmf>
    </response>

record:

  • Description: This tag is used to record the callers voice and returns the url of the file containing the audio recorded and hosted for one day.
  • Filename:This file name is used as reference to download the file for example myfilename. KooKoo appends a unique string to your filename and returns the URL of the recorded audio file
  • Attributes:
    • format=Recorded Audio file is saved in wav format.other formats are coming soon
    • silence=Is the number of seconds of silence to allow before returning.
    • maxduration=Is the maximum recording duration in seconds.
    • Termination Character # is the default termination character to stop the recording.It is not configurable currently.
  • Examples:

     <?xml version="1.0" encoding="UTF-8"?>
    <response sid="12345">
    <record format="wav" silence="3" maxduration="30" >myfilename</record>
    </response>

conference:

  • Description: This tag is used to create a conference room with number given in the tag.Ex 2345. Using this, you can push callers into a conference room. This tag is mainly used to create dynamic phone conferences. You can mix this with collectdtmf to ask the users to enter a pin and then push them into a correct conference room.
  • Attributes:
    • caller_id = set caller ID within the list of numbers allocated to your KooKoo Account,Example 9140XXXXXXXX..
    • record= to enable conference recording, record ={'true'/'false'}
    • version=1(Version Number)
    • timeout=x( KooKoo will wait for x milliseconds for the conference to run.)
    • caller_onhold_music={default} //default there will be a music on hold.
  • Examples:
  •  <?xml version="1.0" encoding="UTF-8"?>    
    <response>
    <conference caller_onhold_music="default" record="true">2345</conference>
    </response>

    Please check this three scenarios to receive request parameters in your application to handle the conference application.

    1) event=conference,status,callduration,data(recording for the dial),message (This shall come when user terminate's with hash)

    2) event=Hangup,process=conference,data(recording for the conference), callduration (This will come when the user drops the call in the conference)

    3) event=Hangup,process=none ,total_call_duration .(If the user drop's the call when no process is associated)

gotourl:

  • Description:This tag is used to inform KooKoo to jump to the next URL which has a another KooKoo Application.The URL should be full url : 'http://host../nextapp.app'.
  • Attributes:None
  • Examples:
  •  <?xml version="1.0" encoding="UTF-8"?>    
    <response>
    <gotourl>http://host../nextapp.app</gotourl>
    </response>


hangup:

  • Description:This tag is used to inform KooKoo to disconnect the caller.Make sure you always call this at the end of your program to keep things clean.
  • Attributes:None
  • Examples:
  •  <?xml version="1.0" encoding="UTF-8"?>    
    <response>
    <hangup></hangup>
    </response>


dial:

  • Description: Inside your KooKoo XML just include <dial>number to be called</dial>. When KooKoo sees that tag it will make a call to that specified number and connect the caller. This is mainly used when we want to connect the caller to an agent or something. This tag is used to dial an outbound number and the conversation can be recorded. It returns status of the dial and also the url of the file containing the audio recorded and hosted for one day.
  • Attributes:
    • record=Record the conversation or not.Values are true or false.
    • caller_id = set caller ID within the list of numbers allocated to your KooKoo Account,Example 9140XXXXXXXX..
    • limit time= for max calltime //maxtime call allowed after called_number answered.
    • timeout=maximum ringing time for call when dialed to a number.
    • if {moh=default} there will be a music on hold or {moh=ring} there will be normal ring.
    • promptToCalledNumber =If would like to play prompt to called number, give audio url like
      'http://www.kookoo.in/recordings/promptToCallerParty.wav'
  • Examples:
  • <dial record="true" limittime="1000" timeout="30" moh="default" >09912343234</dial>
                                    

    After the dial is done, KooKoo will call your application URL with the following parameters:

    event=Dial

    status=answered/not_answered

    data=url of recorded file if record is enabled.

    message=Telecom status as sent by the service provider.
    Please check this three scenarios to receive request parameters in your application to handle the dial application.

    1) In event=dial you will get parameters status,callduration,data(recording for the dial),telco_code,pickduration,message (This shall come when user terminate's with hash)

    2) In event=Hangup you will get parameters status,process=dial,data(recording for the dial), callduration,message (This will come when the user drops in the call, this is the source number or the caller number)

    3) In event=Hangup you will get parameters process=none ,total_call_duration,message .(If the user drop's the call when no process is associated)

    4) event=Disconnect.(when the application hangs the call using kookoo hangup tag)

    Note: If the event received is Disconnect you will get only total_call_duration and callduration is the (dailed number duration) which is sent as a request parameter in the event Dial.In event Dial you will get only callduration of the dialed number if you want total call duration send hangup tag in event Dial you shall get it as get event Disconnect capture the total call duration there.

    The message gives us more insight into why a dialed call failed. Most calls go through, but when the calls have a problem these messages give us more pointers.
    If a lot of calls are failing, please mail to support with the most common reason and KooKoo will work with the telecom service provider to resolve the issue.
    When you make a dial out, then it uses one more port. So if you have taken 5 KooKoo ports, you can make maximum of 2 dials.


recognize:

  • Description:The recognize tag allows you to include speech recognition capabilities into your IVR application.
    • type : This should be always indybol
    • timeout : Maximum waiting time for a user to give input over voice.
    • silence : Within this time if you dont say anything it shall assume no input.
    • lang : Currently we are supporting english(en) and hindi(hi).
    • length : Currently we are supporting single digit length only(length=1).
    • grammar :
      1. "digits" grammar: This will allow you to recognize digits spoken on the phone. You can use this to recognize pin numbers, OTP, phone numbers, IVR choices.
      2. "yesno" grammar: This will allow you to recognize "yes/no". A little surprise, this grammar also accepts hindi. So it recognizes even "haan/naa". Very useful to ask questions and get a yes or no answer from your callers.
  • Examples:
  •  <?xml version="1.0" encoding="UTF-8"?>
    <response >
    <playtext speed="2" quality="normal" >Please say a number from 1 to 9 </playtext>
    <recognize type="indybol" timeout="2" silence="3" lang="en" length="1" grammar="digits" />
    </response>



    After the recognition is done, KooKoo will call your application URL with the following parameters:

    event=Recognize

    data=spoken digit.
    
        
In order to use the KooKoo php library, just download KooKoo PHP library and include it in your source code.
------- Play Text Example -------- <?php require 'response.php';//include response.php into your code $r = new response(); $r->addPlayText("I Love Koo Koo"); // Play any text to play $r->addHangup(); $r->send(); ?>
------- SayAs Tag Example -------- <?php /*** * Use Say-As Tag for play Dynamic content like playing number or digits * */ require 'response.php';//include response.php into your code $r = new response(); $r->addSayAs("1234",501,'EN'); // Play any text to play $r->addHangup(); $r->send(); ?>
---------- PlayAudio Tag Example Code ---------- <?php /*** * Use PlayAudio Tag to play pre-recorded audio file */ require 'response.php';//include response.php into your code $r = new response(); $r->addPlayAudio("http://yourhost.com/welcome.wav"); // Play any text to play $r->addHangup(); $r->send(); ?>
---------------------------Collect DTMF Example------------------------------------------------- <?php /* * * * Use Collect DTMF to collect DTMF input from user. */ require 'response.php'; //include response.php into your code $r = new response(); if (isset($_REQUEST['event']) && $_REQUEST['event'] == 'NewCall') { $cd = new CollectDtmf(); //initiate new collect dtmf object $cd->addPlayText("Press 1, for sales"); $cd->addPlayText("Press 1, for to know about our company"); $r->addCollectDtmf($cd); } elseif (isset($_REQUEST['event']) && $_REQUEST['event'] == 'GotDTMF') { if (isset($_REQUEST['data']) && !empty($_REQUEST['data'])) { $r->addPlayText("you have pressed D T M F" . $_REQUEST['data']); } else { $r->addPlayText("you have not given any input please re enter"); $cd = new CollectDtmf(); //initiate new collect dtmf object $cd->addPlayText("Press 1, for sales"); $cd->addPlayText("Press 1, for to know about our company"); $r->addCollectDtmf($cd); } }else{ $r->addHangup(); } $r->send(); ?>
---------------------------Record Tag Example------------------------------------------------- <?php /* * * * Use Record Tag, To record message. recorded message will be pushed application as URL */ require 'response.php'; //include response.php into your code $r = new response(); if (isset($_REQUEST['event']) && $_REQUEST['event'] == 'NewCall') { $r->addPlayText("Please record your message"); $r->addRecord("recordFileName"); } elseif (isset($_REQUEST['event']) && $_REQUEST['event'] == 'Record') { $r->addPlayText("your recorded message is "); $r->addPlayAudio($_REQUEST['data']); }else{ $r->addHangup(); } $r->send(); ?>
---------------------------Conference Tag Example------------------------------------------------- <?php /* * * * Conference Tag Example * */ require 'response.php'; //include response.php into your code $r = new response(); if (isset($_REQUEST['event']) && $_REQUEST['event'] == 'NewCall') { $r->addPlayText("You are joining into conference"); $r->addConference("1234"); //1234->is conference nummbr } elseif (isset($_REQUEST['event']) && $_REQUEST['event'] == 'Conference') { $r->addPlayText("your recorded message is "); $r->addPlayAudio($_REQUEST['data']); } else { $r->addHangup(); } $r->send(); ?>
---------------------------Goto Tag Example------------------------------------------------- <?php /* * * * GoTo Tag Example */ require 'response.php'; //include response.php into your code $r = new response(); $r->addGoto("http://your.public.host/nextapp.php"); $r->addHangup(); $r->send(); ?>
---------------------------Hangup Tag Example------------------------------------------------- <?php /* * * * Hangup Tag Example */ require 'response.php'; //include response.php into your code $r = new response(); $r->addHangup(); //simply add hangup tag to disconnect $r->send(); ?>
---------------------------Dial Tag Example------------------------------------------------- <?php /* * * * Dial Tag Example * */ require 'response.php'; //include response.php into your code $r = new response(); if (isset($_REQUEST['event']) && $_REQUEST['event'] == 'NewCall') { $r->addPlayText("Please wail while we connecting"); $r->addDial("09xxxx"); //phone number to dial } elseif (isset($_REQUEST['event']) && $_REQUEST['event'] == 'Dial') { if ($_REQUEST['status'] == 'answered') { $r->addPlayText("dialled number is answered"); } else { $r->addPlayText("dialled number is not answered"); } $r->addHangup(); } else { $r->addHangup(); } $r->send(); ?>>
In order to use the KooKoo java library, just download KooKoo Java library and include it in your source code.
--- playText Example code ----- import com.ozonetel.kookoo.Response; //add and import kookoo response.jar or source code into your application import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @WebServlet(name = "testIvr", urlPatterns = {"/testIvr"}) public class testIvr extends HttpServlet { /** * @param request servlet request * @param response servlet response * @throws ServletException if a servlet-specific error occurs * @throws IOException if an I/O error occurs */ @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/xml;charset=UTF-8"); Response r = new Response(); //create kookoo Response Object r.addPlayText("I Love Koo Koo"); // add play text object r.addHangup(); String kookooResponseOutput = r.getXML(); try (PrintWriter out = response.getWriter()) { out.println(kookooResponseOutput); } } } --------------------------------------------------------------------------------
--------------------------PlayAudio Example------------------------------------- import com.ozonetel.kookoo.Response; //add and import kookoo response.jar or source code into your application import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @WebServlet(name = "testIvr", urlPatterns = {"/testIvr"}) public class testIvr extends HttpServlet { /** * @param request servlet request * @param response servlet response * @throws ServletException if a servlet-specific error occurs * @throws IOException if an I/O error occurs */ @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/xml;charset=UTF-8"); Response r = new Response(); //create kookoo Response Object r.addPlayAudio("http://your...host/audios/welcome.wav"); // play pre-recorded files r.addHangup(); String kookooResponseOutput = r.getXML(); try (PrintWriter out = response.getWriter()) { out.println(kookooResponseOutput); } } }
-------- CollectDTMF Tag Example ---- import com.ozonetel.kookoo.Response; //add and import kookoo response.jar or source code into your application import com.ozonetel.kookoo.CollectDtmf;//import collectdtmf class import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @WebServlet(name = "testIvr", urlPatterns = {"/testIvr"}) public class testIvr extends HttpServlet { /** * @param request servlet request * @param response servlet response * @throws ServletException if a servlet-specific error occurs * @throws IOException if an I/O error occurs */ @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/xml;charset=UTF-8"); String event = request.getParameter("event"); Response r = new Response(); //create kookoo Response Object if ((null != event) && event.equalsIgnoreCase("NewCall")) { CollectDtmf cd = new CollectDtmf(1, "#", 5); cd.addPlayText("Press 1 for sales"); cd.addPlayText("Press 2, for know about our company"); r.addCollectDtmf(cd); } else if ((null != event) && event.equalsIgnoreCase("GotDTMF")) { r.addPlayText("you have entered number is " + request.getParameter("data")); r.addHangup(); } else { r.addPlayText("call is disconnecting " ); r.addHangup(); } String kookooResponseOutput = r.getXML(); try (PrintWriter out = response.getWriter()) { out.println(kookooResponseOutput); } } }
-------- Record Tag Example ---- import com.ozonetel.kookoo.Response; //add and import kookoo response.jar or source code into your application import com.ozonetel.kookoo.Record; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @WebServlet(name = "testIvr", urlPatterns = {"/testIvr"}) public class testIvr extends HttpServlet { /** * @param request servlet request * @param response servlet response * @throws ServletException if a servlet-specific error occurs * @throws IOException if an I/O error occurs */ @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/xml;charset=UTF-8"); String event = request.getParameter("event"); Response r = new Response(); //create kookoo Response Object if ((null != event) && event.equalsIgnoreCase("NewCall")) { r.addPlayText("Please say your message after beep"); Record rec = new Record(); rec.setFileName("recordFileName"); rec.setMaxDuration(15); r.addRecord(rec); } else if ((null != event) && event.equalsIgnoreCase("Record")) { r.addPlayText("message recored by you is :"); r.addPlayAudio(request.getParameter("data")); r.addHangup(); } else { r.addPlayText("call is disconnecting "); r.addHangup(); } String kookooResponseOutput = r.getXML(); try (PrintWriter out = response.getWriter()) { out.println(kookooResponseOutput); } } } ---Dial Tag Example ----- import com.ozonetel.kookoo.Response; //add and import kookoo response.jar or source code into your application import com.ozonetel.kookoo.Dial; import java.io.IOException; import java.io.PrintWriter; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; @WebServlet(name = "testIvr", urlPatterns = {"/testIvr"}) public class testIvr extends HttpServlet { @Override protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType("text/xml;charset=UTF-8"); String event = request.getParameter("event"); Response r = new Response(); //create kookoo Response Object if ((null != event) && event.equalsIgnoreCase("NewCall")) { r.addPlayText("Please say your message after beep"); Dial dial = new Dial(); dial.setNumber("99xxxxxx"); // set number to dial r.addDial(dial); } else if ((null != event) && event.equalsIgnoreCase("Dial")) { String status = request.getParameter("status"); if (status.equalsIgnoreCase("answered")) { r.addPlayText("Dialled number is answered"); } else { r.addPlayText("Dialled number is not answered"); } r.addHangup(); } else { r.addPlayText("call is disconnecting "); r.addHangup(); } String kookooResponseOutput = r.getXML(); try (PrintWriter out = response.getWriter()) { out.println(kookooResponseOutput); } } }

Outbound Calls

Use Case

Programatically make outbound calls using KooKoo. This feature can be used to automatically call your users to alert them or give information.
Now making an outbound call is as simple as making a HTTP request.

Procedure:

To make an outbound call just make a http request to http://www.kookoo.in/outbound/outbound.php with the following parameters:

api_key * the API KEY of your account. This is so that you don't send your username and password over HTTP. You can find it in your dashboard once you login to www.kookoo.in
phone_no * The phone number to place the call to
url The url of your application
extra_data The initial XML action to perform.It could be something like <response><playtext>Some text to be played to the users</playtext><hangup/></response>
outbound_version value should be set to 2. This is the latest version and the older versions are deprecated.
caller_id Using this parameter, you can set your caller id if you have more than one phone number assigned to you.
callback_url
This is the URL which will be called after the call is finished. You can have your after call processing at this URL. We send the following parameters to this URL: 'sid' : A unique sequence ID. This will uniquely identify the call. 'caller_id' : The caller id which was set for this call 'phone_no' : The phone number which was called. 'duration': The duration of the call in seconds 'start_time': The start time of the call 'status': The status of the call.It currently has 'answered/ ring/ invalid_number/ busy/ network_congestion/ exception'

Example Http Request:

1. To call 9333422312 and when he picks up, play "I love KooKoo" and hangup
2. To call 9333422312 and when he picks up, play "I love KooKoo" redirect him to your KooKoo application which is hosted at http://www.test.com/kookoo
3. To call 9333422312 and when he picks up, redirect him to your KooKoo application which is hosted at http://www.test.com/kookoo

Note:

  1. Because of TRAI restrictions we do not allow bulk calling. We limit the number of outbound calls to 50/day. In case you have a valid business requirement to make more calls, please mail your requirement to support@kookoo.in and we will get in touch with you.
  2. Outbound call charges apply.The call charges have been fixed at Re.0.70 ps/min pan India.
  3. Just remember if the text is very long, then it takes some time the first time and you will hear the phone ringing. The second time onwards, since the TTS comes from the cache it will be faster.
  4. This feature is available only to paid users of KooKoo.
  5. If any case our primary http://kookoo.in is not responding due to some network latency,You can route your requests or create a fallback to http://1.kookoo.in

The following is the flow:

  1. You make an outbound call request to the REST API by making a HTTP request. You can provide a callback_url parameter to get status of the call.
  2. Once the request is made, KooKoo responds with a status: <response><status>queued</status><message>1234552525</message></response> The status can be 'queued' or 'error'. If it is queued you get the unique id. If it is error, you get an error message. If it is an error, you will have to retry this call.
  3. In the background. KooKoo will be making the call and handling it. Once the call is finished KooKoo will make an HTTP POST request to your callback URL. If the call is not answered you will get a corresponding status given below. In your call back url you can do post call processing. Very simply you can record all the call statuses in the database and then try to call them again in another attempt or do something.
Call Back Url Parameters
sidoutbound-ucid, This is the link to the outbound request.It will be the same value which was returned in the xml for the outbound.php request
status'answered/ring/invalid_number/busy/network_congestion/exception'
phone_no'Phone number of the dialed number'
start_timeCall queued time
ringing_timeDuration of call ring before answered
durationAnswered call duration in seconds
caller_idNumber, on which call is dialed
status_detailsreason to call is not answered check <dial> tag for descriptions
dial_timeCall dialing time from the KooKoo Platform
pick_timeThe call picked time
end_timeThe call end time
KooKoo Outbound API Status and Message Description
<response><status>error</status><message>Outbound parameter extra_data or url is mandatory</message></response> extraData is mandatory
<response><status>error</status><message>Phone number is mandatory</message></response> Phone Number is mandatory
<response><status>error</status><message>Phone number is not in proper format</message></response> Phone Number is not in particular format
<response><status>error</status><message>DB Error</message></response> If there is an internal API error.
<response><status>error</status><message>Authentication error</message></response> Not Provided valid details like callerID and apiKey
<response><status>error</status><message>Phone number in DND list</message></response> Phone Number is in DND
<response><status>error</status><message>Calls will not be made between 9pm to 9am</message></response> Can't call after between 9PM to 9 AM as per TRAI
<response><status>error</status><message>Caller Id not valid</message></response> callerID not provided properly
<response><status>error</status><message>Telephony error</message></response> Can't able to queue the call
<response><status>error</status><message>Max Connections Reached</message></response> Max Connections Reached (this will work if you use outbound_version=2)
<response><status>queued</status><message>xxxxx</message></response> if call is successfully queued
<response><status>error</status><message>Credit limit exceeded</message></response> Credit limit exceeded.

Please Keep Watching this Space for more Updates......

                            <?php            
$url = 'http://www.kookoo.in/outbound/outbound.php';
$param = array('api_key' => 'KKfdbxxxxxxxx', 
'phone_no' => '099xxxxxxxx', 
'caller_id' => '91xxxxxxxx', 
'outbound_version' => 2, 
'url' => 'http://test.php'  
);
                          
$url = $url . "?" . http_build_query($param, '&');
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
//     return $result;
?>
                        

            
import java.net.URI;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.BasicResponseHandler;
import org.apache.http.impl.client.DefaultHttpClient;

public class OutboundTest {

    public static void main(String a[]) {
        try {
            String url = "http://kookoo.in/outbound/outbound.php";
            URIBuilder uribuilder = new URIBuilder(url);

            uribuilder.addParameter("api_key", "11111");
            uribuilder.addParameter("phone_no", "91xxx");
            uribuilder.addParameter("caller_id", "9140");
            uribuilder.addParameter("outbound_version", "2");
            uribuilder.addParameter("url", "http://x.yourhost/ivr.php");
            URI uri = uribuilder.build();
            System.out.println("Final Outboud API url " + uri);
            HttpGet httpget = new HttpGet(uri);
            DefaultHttpClient defaulthttpclient = new DefaultHttpClient();

            HttpResponse outboundResponse = defaulthttpclient.execute(httpget);
            String responseString = new BasicResponseHandler().handleResponse(outboundResponse);
            System.out.println(responseString);

        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}


                            

Outbound SMS

SMS API for Transactional and Promotional.

The SMS API is configure to be promotional by default and the sms shall go with some random sender id like LM-650318. If you need to use transactional then you need to configure 6 char sender id on the account. If there are multiple sender ids you can differentiate with the api using the senderid parameter.

Procedure

Just make a HTTP request to
http://www.kookoo.in/outbound/outbound_sms.php
The parameters to be provided are:
phone_no: The number to which we need to send the sms
api_key: For security purposes. use your API key in the dashboard.
message: The message to be sent.
senderid:The 6 characters senderid which has been setup on your account.For example KOOKOO

Example:

1) http://www.kookoo.in/outbound/outbound_sms.php?phone_no=9xxxxxx90&api_key=your_api_key&message=testing
2) http://www.kookoo.in/outbound/outbound_sms.php?phone_no=9xxxxxx90&api_key=your_api_key&message=testing&senderid=KOOKOO
Note:If any case our primary http://kookoo.in is not responding due to some network latency,You can route your requests or create a fallback to http://1.kookoo.in

SMS Status Callback

For enabling SMS status details through callback URL please go into the KooKoo setting's page look for smscallback URL field assign the URL which is hosted at your end.
Once this is done.Any sms fired from our api that sms status shall be sent to this callback URL using POST method with the follwoing parameters.
status (SMS status success,failure etc...)
smsid (Unique ID )
mobileno (Number to which the message is sent)
donetime
                        
                            
<?php            
$url = 'http://www.kookoo.in/outbound/outbound_sms.php';
$param = array('api_key' => 'KKfdbxxxxxxxx', 
'phone_no' => '099xxxxxxxx', 
'message' => 'test message' 
);
                          
$url = $url . "?" . http_build_query($param, '&');
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
//     return $result;
?>
                        
                            
                        import java.net.URI;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.BasicResponseHandler;
import org.apache.http.impl.client.HttpClientBuilder;

public class OutboundSMS {

    public static void main(String a[]) {
        try {
            String url = "http://www.kookoo.in/outbound/outbound_sms.php";
            URIBuilder uribuilder = new URIBuilder(url);

            uribuilder.addParameter("api_key", "11111");
            uribuilder.addParameter("message", "test message");
            uribuilder.addParameter("phone_no", "9140");
            URI uri = uribuilder.build();
            System.out.println("Final Outboud API url " + uri);
            HttpGet httpget = new HttpGet(uri);
           HttpClient  client = HttpClientBuilder.create().build();

            HttpResponse outboundResponse = client.execute(httpget);
            String responseString = new BasicResponseHandler().handleResponse(outboundResponse);
            System.out.println(responseString);
        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}
                        
                            

Inbound SMS

Ask your users to send an SMS to your longcode EX 923xxxxx or to the same longcode with "your_keyword <space> message" as a message. That's it.You have now enabled a data channel for your application. When KooKoo receives the SMS it checks your longcode or any associated keyword it forwards to your application URL with the following parameters which is to added in the settings page of your KooKoo Account:
event=NewSMS
cid=the_number_which_sent_the_sms
message=the_actual_sms_message
time=the_time_at_which_the_sms_was_sent
If there is a keyword then keyword={Keyword Name}
Update your application at the application URL to handle this new event and perform required operations you are set. Please let us know if the longcode has to be configured and any keywords.

Audio File Preparation

1. Purpose
This document details the procedure to convert the audio file recorded by the user to KooKoo supported audio format.
2. Pre Requisite
This document demonstrates the audio file conversion using Audacity. Audacity can be downloaded from: audacity.sourceforge.net
Tips

• Record the audio as wav with PCM signed 16 Bit, 48000 Hz, Mono (preferable) else stereo. Record high quality, mix down to 8Khz mono
• Filter out audio below 300 Hz and above 3000 Hz
• Keep volume levels between -6 and -9db
• While recording don’t add much bass (will get filtered out), high treble will convert to hiss sound on mixing down.
• Kookoo needs audio with specs as
-> Wav PCM Signed Mono
-> 16 Bit
-> 8000 Hz
-> 128 Kbps
 
3. Audio Preparation Steps

•If stereo convert track to mono
•Compress : The Compressor effect reduces the dynamic range of audio.
  One of the main purposes of reducing dynamic range is to permit the audio to be amplified further
•Apply Notch filter for frequency 1663, 1477,1336, 1209. These are high level frequency for DTMF.
  Removing them make sure that there is no false dtmf tone detection, while audio is playing back
(Issue is more prominent when calls are from landlines).
•Normalize
•Resample at 8000 Hz
•Export the Audio
3.1. Start Audacity Application
Go to menu click Tracks >> Stereo Track To Mono.
3.2. Select Compressor
Go to menu click Effect >> Compressor.
3.3. Select Notch Filter
Go to menu click Effect >> Notch Filter
3.4. Normalize

Go to menu click Effect >> Normalize (-6 DB)
3.5.Resample
Go to menu click Tracks >>Resample
3.6. Export Audio
Go to menu click File >> Export.
Converted files now can be used with KooKoo.

Audio Cache Management

Sometimes in your KooKoo application you want to play some audio and you use the <playaudio> tag.

KooKoo downloads the audio and caches it and plays the audio to the caller. This means that the first time caller will have some delay as KooKoo will be downloading the audio.

To overcome this, you can upload your audio files to KooKoo cache using the cache API.
You can find the cache API at (http://kookoo.in/index.php/kookoo-docs#cache-api) .

You can use this to upload the audio files to the cache. For now you we will not touch your cache. But going forward we will have a cache management strategy and we will inform you accordingly.

You will need to provide the following information to upload to your cache:

  1. Your API Key: You can find this in your dashboard once you login to your KooKoo account
  2. Cache location: This is the location of your phone number.
  3. The file that you want to upload.(Should not be more than 20Mb)

Note:
  1. You will be responsible for any content you upload to the KooKoo cache.
  2. KooKoo cache is temporary and will be cleared from time to time.
  3. You can upload only wav files and the files should be less than 20 Mb.

Cache API

Note 1: By default Cache is disabled for all the KooKoo users and if you want to enable Cache for your account please send a mail to support@kookoo.in with subject as:Enable Cache and it will be enabled at the earliest for Paid Accounts.

1. To upload an audio file:

Make a POST request to

http://kookoo.in/restkookoo/index.php/api/cache/audio/

with the parameters:

api_key=your_api_key
url=URL of the audio to be uploaded to the cache. Make sure that you use the same url in the <playaudio> tag and make sure there are no spaces etc in the URL as we use this URL to create a md5 hash for the cache filename.

Also make sure the parameters are URL encoded.

Example request:

curl -d "api_key=your_api_key&url=http://test.com/test.wav http://kookoo.in/restkookoo/index.php/api/cache/audio/

2. To get filename of your audio in the cache

Make a GET request as shown below

http://kookoo.in/restkookoo/index.php/api/cache/audio/api_key/your_key/url/encoded

Example request:

curl "http://kookoo.in/restkookoo/index.php/api/cache/audio/api_key/KK9XXXXXXX XXXXXXc/url/http:%5C%5Cwww.test.com%5Ctest.wav"

Note: Please see how we have encoded the url parameter.

3. To delete a file from cache:

Make a GET request as shown below:

curl "http://kookoo.in/restkookoo/index.php/api/cache/audio/api_key/ your_api_key/url/audio_url_you_want_to_delete/delete/true"


4. To delete all files from cache:

Make a GET request as shown below:


curl "http://kookoo.in/restkookoo/index.php/api/cache/audio/api_key/KKXXXX9c/delete/all"
                            
<?php
    
    $files=array(
               'http://www.test.com/sites/default/files/audio/1.wav',
               'http://www.test.com/sites/default/files/audio/2.wav'
               );

    foreach($files as $value)
        {
            $post_data['api_key'] ="KKXXXXXXXXXXXX";
            $post_data['url'] = $value;
            echo $post_data['url'];
            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL,"http://kookoo.in/restkookoo/index.php/api/cache/audio/");
            curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
            curl_setopt($ch, CURLOPT_HTTPHEADER, array('Expect:'));
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
            curl_setopt($ch, CURLOPT_VERBOSE, 1);
            $curl_scraped_page = curl_exec($ch);
            curl_close($ch);
           echo $curl_scraped_page;
        }
?>
                        

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.HttpClient;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.message.BasicNameValuePair;

/**
 *
 * @author rajeshg
 */
public class CacheAPITest {

    public static void main(String a[]) {
        try {

            String audios[] = {"http://yourhost/generic/en/welcome_audio.wav",
                "http://yourhost/generic/en/thanks_audio.wav"};

            String url = "http://kookoo.in/restkookoo/index.php/api/cache/audio/";
            HttpClient client;
            HttpPost post;

            for (String audioUrl : audios) {

                client = HttpClientBuilder.create().build();

                post = new HttpPost(url);

                List<NameValuePair> postParams = new ArrayList<>();

                postParams.add(new BasicNameValuePair("api_key", "KKxxxxxx"));
                postParams.add(new BasicNameValuePair("url", audioUrl));
                post.setEntity(new UrlEncodedFormEntity(postParams));
                HttpResponse response = client.execute(post);
                System.out.println("Response Code : "
                        + response.getStatusLine().getStatusCode());

                BufferedReader rd = new BufferedReader(
                        new InputStreamReader(response.getEntity().getContent()));

                StringBuilder result = new StringBuilder();

                String line;

                while ((line = rd.readLine()) != null) {
                    result.append(line);
                }

                System.out.println("kookoo api response" + result.toString());
            }
        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}
   
                            

Quick Start

  1. Register for a KooKoo account. On registration you will allocated access to the shared pool of telephone lines assigned to the normal users. You will also be assigned a pin number which should be used by you to access your application.
  2. Setup a web page which you can access publicly.If you don't have any public server to host the kookoo app and run a trail then you can try creating a tunnel to your localhost application and one service which helps you doing this is https://ngrok.com/, ngrok helps you exposing a local server behind a NAT or firewall to the internet.Test if you can access your page from a browser
  3. Create a page which returns the following:
    <response><playtext>I Love KooKoo</playtext><hangup/></response>
  4. Access your example from a browser
  5. Login to KooKoo
  6. Enter the URL of your example application and save
  7. Call KooKoo (040-39411020, 080-39411020, 022-39411020) and enter your pin number.
  8. Start coding

Next Steps

  1. Check out all the tags supported by KooKoo. These are the commands that your application can give to KooKoo.
  2. Understand the Request Parameters sent by KooKoo to your application. You should develop your application to accept these parameters.
  3. See how you can place outbound calls in KooKoo.
  4. Get ideas for your applications on our blog.
   
            
                                
            
            
                    
             
                            

KooKoo Request Overview

KooKoo makes HTTP requests to your application just like a regular web browser. By including parameters and values in its requests, KooKoo sends data to your application that you can act upon before responding. You can configure the URLs KooKoo uses to make its requests via your KooKoo nest after you login to your account portal.

KooKoo Voice Requests

When KooKoo receives a call for your configured number it makes a synchronous HTTP request to the application URL configured for that number, and expects to receive KooKoo XML in response. KooKoo sends the following parameters with its request as URL query parameters

Request Parameters

Parameter Description
sid A unique identifier for this call, generated by KooKoo. You can use this to track your session state to move through the call flow.
cid The phone number of the party that initiated the call.This is nothing but the caller id. This will help your application to know who called your number. You can use this to compare the caller id in a database to identify the caller. KooKoo will try its best to send a 10 digit phone number but because of the different standards followed by our carriers it is best to test the different numbers that your application receives.This parameter will be sent only during the first request made by KooKoo. So make sure you store it for further reference.
cid_e164 Which gives you the correct international format (E.164) which is in a standard format. You can use this in your application .
called_number The KooKoo phone number that has been called.This is nothing but the DID.It will be useful if your application has more than one phone number associated with it and will help your application to know to which number the customer called.
event

This will indicate to your application what event KooKoo handled just now. For example, if KooKoo just received a call, then it will populate this parameter with the value NewCall. Your application can use this parameter to react to different actions performed by KooKoo. The events supported by KooKoo right now are:

  • NewCall : When KooKoo receives a new call
  • Record : When KooKoo finishes recording a file
  • GotDTMF : When KooKoo has collected user input
  • Hangup : When the caller has hungup the current call
  • Disconnect: When we (KooKoo) disconnects the caller
  • Dial: When the outbound dial has finished
  • Conference: When the user terminates with # in the conference
data

Generally there are different data associated with the KooKoo events. For example, once a recording is finished KooKoo returns the file name of the recorded file to your application. Similarly, after we collect user input, KooKoo returns the collected digits to your application for further processing. The different data sent by KooKoo for different events are:

  • NewCall: No data is sent
  • Record: URL of the file name recorded is sent in the data parameter
  • GotDTMF: The digits entered by the user are sent in the data parameter. For example if the user entered 1234,then KooKoo sends data=1234 as a request parameter.
  • Dial:URL of the file name recorded is sent in the data parameter
callduration This parameter is sent when the event is either "Record" or "Dial" or "Conference" and also when the event is in process like process ={"dial" or "Conference" or "record"} this generally comes when the event is in process and call gets disconnected. It specifies the amount of time the recording or dial happened.
record_duration This parameter is sent when the event is "Record" and when the call gets disconnected with particular event in process,then you get the duration with process parameter value as record. It specifies the amount of time the recording happened.
total_call_duration This parameter is sent when the event is "Hangup","Disconnect" or event "Hangup","Disconnect" with process ={"dial" or "Conference" or "record"}. It specifies the total time taken during the entire call.
process This parameter is sent when the call gets disconnected with particular event in process like {process=dial, process=conference, process=record, process=none}
status This parameter is sent when the event is "Dial". It specifies whether the dialed call was answered or unanswered. More info
telco_code This parameter is sent when the event is "Dial". When the Telco network or remote user disconnects a call for any reason.You can refer to the cause code and the same related details are provided in this site. . Click Here.

KooKoo also sends you some codes which are sent in the same parameter.Currently we have these "200" => "DND_Number", "201" => "ISDDisabled", "202" => "Invalid_CallerId.
outbound_sid This parameter is sent when the event is "NewCall" and the call was generated through an outbound request. This will uniquely identify an outbound call. This is the connecting parameter from making an outbound request, to receiving the call on your IVR and after the call is finished in the callback url. So please use this to track the status of your call.
circle This parameter is sent when the event is "NewCall" and mentions the telecom circle of the caller. Using this, you can create an application that reacts differently based on the location(as per telecom circle) of the caller.
List of possible values:
  1. BIHAR and JHARKHAND
  2. MUMBAI
  3. MAHARASHTRA
  4. TAMILNADU
  5. ANDHRA PRADESH
  6. PUNJAB
  7. NORTH EAST
  8. UTTAR PRADESH (E)
  9. UTTAR PRADESH (W) and UTTARAKHAND
  10. KARNATAKA
  11. MADHYA PRADESH and CHHATISGARH
  12. KERALA
  13. HARYANA
  14. GUJARAT
  15. ORISSA
  16. WEST BENGAL
  17. CHENNAI
  18. KOLKATA
  19. JAMMU and KASHMIR
  20. ASSAM
  21. DELHI
  22. RAJASTHAN
  23. HIMACHAL PRADESH
operator This parameter is sent when the event is "NewCall" and mentions the telecom operator of the caller. Using this, you can create an application that reacts differently based on the operator of the caller.
List of possible values:
  1. STEL
  2. IDEA
  3. RELIANCE
  4. VIDEOCON
  5. BSNL
  6. VODAFONE
  7. UNINOR
  8. AIRTEL
  9. AIRCEL
  10. TATA DOCOMO
  11. LOOP
  12. MTS
  13. TATA DOCOMO
  14. SPICE
  15. HFCL
  16. MTNL
  17. LOOP MOBILE
  18. TATA INDICOM
  19. ETISALAT

Examples

Let us assume your application is hosted at http://yourapp.com/ivr.php
  • When a new call comes in:
    http://yourapp.com/ivr.php?event=NewCall&cid={caller id}&called_number={the number which was called}&sid={unique id of the call}&circle={telecom circle of the caller}&operator={the telecom operator of the caller}
  • After the user enters DTMF input:
    http://yourapp.com/ivr.php?event=GotDTMF&data={the digits entered by the caller}&sid={call id}
  • After recording is finished:
    http://yourapp.com/ivr.php?event=Record&data={URL of recorded file}&sid={call id}
  • After caller hangs up:
    http://yourapp.com/ivr.php?event=Hangup&process={last working event when the call was hung up}&data={data related to the process that was hung up}&sid={call id}
  • After the outbound dial is finished:
    http://yourapp.com/ivr.php?event=Dial&data={URL of call recording}&status={answered/not_answered}&message={reason for not answering}&sid={call id}