KooKoo Docs

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:

response: This is the root tag
playtext: Play some text to your callers
Say-As: Play some dynamic values like date ,currency ,characters etc in different languages
playaudio: Play some audio to your callers
collectdtmf: Collect user input from your callers
record: Record caller conversation
conference: Conference multiple callers
hangup: Disconnect current caller
dial: Make an outbound call (Available only to paid users)

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.

Example:
$r=new Response();
$r->setFiller("yes");

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:

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

<?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.

Examples:

 <?xml version="1.0" encoding="UTF-8"?>
 <response>     
 <playtext>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. In the future we will support SSML to allow you to explicitly say how to pronounce different text
- 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

Example :

  

        format        format_code      text      lang           Play As

        Date              201         20110721    EN      Thursday July 21st 2011
        
        Date              202         20110721    EN      July  21st  2011

        Date              204         20110721    EN      July  21st  

        Currency          402         53          EN      Fifty three rupees and zero zero paise

        Currency          401         53          EN      it ignores numbers after decimal point

        Digits            501         1234        EN      one two three four

        Number              1         1234        EN      one 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
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.

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:None
Examples:

 <?xml version="1.0" encoding="UTF-8"?>    
 <response>   
 <conference>2345</conference>    
 </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 number to be called. 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.
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.
Note: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.
Examples:

<dial record="true" limittime="1000" timeout="30" moh="default" >09912343234</dial>

event

status

data

message