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.
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 finihsed
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
duration This parameter is sent when the event is either "Record" or "Dial". It specifies the amount of time the recording or dial happened.
status This parameter is sent when the event is "Dial". It specifies whether the dialed call was answered or unanswered. More info
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}