Click-to-Call: HTTP/HTTPS API Integration - including Interactive Applications

Owned by Abhinandan Shah (Deactivated)
Last updated: Aug 31, 2021Version comment
18 min read

This document provides API integration details regarding Phonon’s Click-to-Call product. For any query, more information or suggestions, write to us at help@phonon.io, or contact your Customer Success Manager.

 

Table of Content:

Before You Begin

Please read this section before proceeding with any integration in the document.

Customer to Provide (Source IP Address for Validation)

Please provide us the IP address of your server so that we can validate your IP address for each request. Requests are allowed only from valid IP addresses for each customer.

HTTP/S APIs Details

For Click-to-Call we have the following APIs: 

  1. MakeCall API 

  2. Status Update API

  3. Cancel Call API

  4. Online call data and billing API (XML Reports)

  5. Interactive Application APIs

  6. Prompt Upload and Modification APIs

  7. CLIDetailsRetreive API

URL Formats (Resources)

Phonon provides two resources:

  1. Test Resources at test.phonon.in, which are used for all test and integration purposes.

  2. Production Resources at c4c.phonon.in, which is enabled for customers once all testing and integration is completed and system is ready to go into production at customer.

In the document all resources are indicated as <resource>.phonon.in. For integration this needs to be read to as test.phonon.in and for production (after confirmation from Phonon) to be used as c4c.phonon.in

HTTPS Support

Phonon Click-to-Call APIs support only HTTPS. No HTTP support is provided. Any HTTP call gets redirected to HTTPS immediately. Our SSL Certificate is SHA256 certificate.

HTTP Methods Support

HTTP methods supported are GET and POST. We suggest customers use POST while using HTTPS APIs and calling any Phonon services.

Default Setup

Default setup has:

  1. OAC check enabled for NDNC registered customers only.

  2. Service calling times between 09:00 to 21:00 IST, all days of the week.

  3. International calling is disabled.

  4. Interactive Application and Prompt Upload and Modification APIs are disabled.

Any changes in the above are made only on specific request from customers.

1. MakeCall API

This API is used to generate a make call request to connect the visitor and advertiser. This API validates that the request is coming from your registered source IP with us, before a call is made.

MakeCall API - Request

Test Request URI

  • https://test.phonon.in/c2c/C2CRequest?visitor=<Visitor Number>&advertiser=<Advertiser Number>&custToken=<Customer Token>&duration=<Call Duration>&uniqueID=<Unique Identifier>&udf1=<UDF Parameter 1>&udf2=<UDF Parameter 2>&udf3=<UDF Parameter 3>&udf5=<UDF Parameter 5>&visitorIP=<visitorIP>&scheduled_callback_time=<scheduled_callback_time>

Production Request URI

  • https://c4c.phonon.in/c2c/C2CRequest?visitor=<Visitor Number>&advertiser=<Advertiser Number>&custToken=<Customer Token>&duration=<Call Duration>&uniqueID=<Unique Identifier>&udf1=<UDF Parameter 1>&udf2=<UDF Parameter 2>&udf3=<UDF Parameter 3>&udf5=<UDF Parameter 5>&visitorIP=<visitorIP>&scheduled_callback_time=<scheduled_callback_time>

Note: 

  1. For HTTP/s POST method the URL should be without query string (i.e http://test.phonon.in/c2c/C2CRequest). 

  2. The field name should be same as the parameter names in the URL with query string. For example: To pass a visitor parameter using HTTP/s POST method there should be a FIELD named “visitor”.

  3. Here value for scheduled_callback_time = 2018-01-24 12:28:58 (format: YYYY-MM-dd hh:mm:ss)

Where:

Mandatory Parameters:

  1. custToken  : (mandatory) your unique customer token provided by us.

  2. visitor         : (mandatory) Visitor phone number, who is visiting the site. 

  3. advertiser  : (mandatory) Advertiser phone number, who will be connected to visitor. Note: In case of only outbound call, advertiser parameter is not mandatory and kept as blank.

Please note for items 2 & 3: Phone number is sent in the E.164 number plan including country code e.g. '919978889490' or '912652781717'

 

Optional Parameters:

  1. duration: Duration in seconds for call between visitor and advertiser, if not send default duration of 900 seconds is taken by system.

  2. UDF1: UDF 1 parameter value.

  3. UDF2: UDF 2 parameter value.

  4. UDF3: UDF 3 parameter value.

  5. UDF4: UDF 4 parameter value. UDF4 in HTTP API is defined as uniqueID (optional). This is Unique Identifier generated at your end to track each Click2Call Request uniquely. 

  6. UDF5:UDF 5 parameter value. 

  7. VisitorIP     : This is the source IP of the visitor who has requested the URL. This is stored in UDF6.

  8. Scheduled_callback_time: this is schedule call back time, if want to generate call at given specific time (not at same time request generated). Here value for scheduled_callback_time = 2018-01-24 12:28:58 (format: YYYY-MM-dd hh:mm:ss) If this parameter has null or blank data then no validation takes place. If there is some value then it should validate date in above given format and past date is not allowed. This time is consider only as IST time.

Please Note: 

UDF Parameters are User Defined Parameters, useful for you to analyse and maintain reports. Maximum length of any UDF1 - UDF 5 parameters is: 100 characters.

MakeCall API - Response

Response String

The response string gives you a unique ID called RequestID generated at our end; with the initial status of the request sent by you. Response string can be of type:

NACK:<NACK_Reason>:<RequestID>

ACK:<RequestID>

NACK / ACK Code Master Values

The current reason values for NACK are:

NACK Reason

Unique Phonon Reference ID Sent

NACK Reason

Unique Phonon Reference ID Sent

1

NACK:NDNC

Yes

2

NACK:Session Timeout

No

3

NACK:Call Not Allowed

No

4

NACK:Advertiser Calls Exceeded

No

5

NACK:Visitor Calls Exceeded

No

6

NACK:Fixed Pair Calls Exceeded

Yes

7

NACK:Service not available

No

8

NACK:Country Blacklisted

No

9

NACK:IP Blacklisted

No

10

NACK:Number Blacklisted

No

11

NACK:Invalid ISD Code

Yes

12

NACK:Invalid Country

Yes

13

NACK:Invalid Country Code

Yes

14

NACK:Invalid URL Authentication

Yes

15

NACK:Invalid parameter

No

16

NACK:Permission denied

Yes

17

NACK:Working Hours are <1> hours to <2> hours <IST>

Yes

18

NACK:Invalid Source IP parameter

Yes

19

NACK:Invalid Visitor Number

No

20

NACK:Invalid Advertiser Number

No

21

NACK:Not valid credit

Yes

22

NACK:Validity Expired

Yes

23

NACK:Invalid customer

No

24

NACK:Invalid Request

No

25

NACK:Connection Refused

Yes

26

NACK:ERROR DB

No

27

NACK:ERROR

No

28

ACK

Yes

 

Note: 

  1. In NACK code -10: <1> hours to <2> hours time is sent in HH:MM IST format.(Calls are not allowed during these hours)

    1. <1> is Donot call Start Time

    2. <2> is Donot call End Time

  2. In certain cases as mentioned in the above table; request ID is not sent. For example, in case request is received from invalid IP; RequestID is not generated and response is simply: 'NACK:Invalid Source IP parameter:' .

Sample Request & Response for MakeCall API

Sample MakeCall API - Request URL

https://test.phonon.in/c2c/C2CRequest?visitor=919978889490&advertiser=919227728888&custToken=abcd1234&duration=900&uniqueID=abcd1234&udf1=100078945&udf2=200014587&udf3=400057489&udf5=30000145874   

Sample MakeCall API - Response URL

  • Sample ACK Resposne String: 'ACK:10000000000025693147'

  • Sample NACK Response String: 'NACK:Fixed Pair Calls Exceeded:10000000000025693147'

MakeCall API JSON Wrapper

A JSON wrapper is also provided for makeCall Request / Response. The URI for this wrapper is: 

Test URI

Production URI 

Schema JSON MakeCall API - Request

Schema Download link

Sample JSON MakeCall API - Request 

 {   "visitor": "919978889490",   "advertiser": "",   "custToken": "1234abcd",   "duration": "900",   "uniqueID": "123456",   "udf1": "Vadodara",   "udf2": "Delhi",   "udf3": "5000",   "udf4": "EN",   "udf5": "httpcallbackurl" }

JSON MakeCall API - Response Format

[Response : "NACK:<NACK_Reason>:<RequestID>"] [Response : "ACK:<RequestID>"]

Sample JSON Response 

{ Response: "NACK:Working Hours are <1> hours to <2> hours IST:10000000000010352710" } { Response: "ACK:10000000000010352711" }

  • RequestID is numeric data of length 20.

  • The response string is returned with ACK or an NACK value. An ACK value implies that the MakeCall request has been received by our click-to-call service and the call will be generated. An NACK response value implies that though the request has been received by our service, the server will not be processing this request. NACK is generally returned with a reason value as well. 

Compliance with TRAI guidelines for NDNC Registered Numbers

All outbound calls to NDNC registered numbers are blocked by default. Customers who want to use click-to-call or interactive outbound calls for NDNC registered numbers need to request for enabling validation through one of the two routes below:

  1. get an OAC (one-time authentication code) validation done. 

  2. give a missed call to a given number to authenticate the request.

OAC / Missed Call Validation

The process flow for OAC / Missed Call validation is as under:

  1. makeCall Request is received from the customer.

  2. Phonon system checks in real-time for the number being registered as an NDNC number. 

    1. In case the number is not registered in the NDNC or TRAI’s NCCP (National Customer Communications Preferences) Register, the call is proceeded and ‘ACK:<RequestId>’ is returned in response to the makeCall request.

    2. In case the number is registered in the NDNC or TRAI’s NCCP Register, Phonon Click-to-Call system will:

      1. Immediately send a one-time authentication (OAC) code to the customer’s given phone number.

      2. Provider in return of the makeCall request a unique phone number where customer needs to give a missed call.

In this process, the response will always be ‘OAC:ACK:<RequestId>;<Number_to_give_missed_call_on>’, e.g. the response to a makeCall request will be ‘OAC:ACK:10000000001234567890;912653930102’. 

  1. For OAC validation: 

    1. If OAC is sent, the customer at this stage will capture the requestId and show a form to collect the OAC from the site visitor. This OAC collection can be in terms of a text box field or any other medium as convenient.

    2. Once OAC is received and entered in the form, customer will send us another request: 

      1. Test URI:
        http://test.phonon.in/c2c/C2CRequest?requestId=<requestId sent in step1>&oac=<oac_received_on_visitor_number>&custToken=<customerToken>

      2. Production URI:
        http://c4c.phonon.in/c2c/C2CRequest?requestId=<requestId sent in step1>&oac=<oac_received_on_visitor_number>&custToken=<customerToken>

    3. If the OAC matches, ‘ACK:<requestId>’ will be responded by our server. In the case of OAC match, the number on which missed call needs to be given will be deactivated for this request and allocated to a different request.

    4. If the OAC does not match, ‘NACK:<reason>’ will be responded by our server.

  2. For Missed Call Validation

    1. The customer (you) will on the web-page display the phone number on which the website visitor needs to give a missed call.

    2. As soon as the customer gives a missed call on the given number, Phonon servers will identify the request for which missed call is received and proceed with remainder click-to-call request.

Please note: 

  1. OAC Validation and MCA validation are time specific processes with a default validity of 20 minutes for both the OAC and the DID number allocated for missed call.

  2. To know the status of call-request process, when the website visitor has given the click-to-call request, you may use the Status Update API.


Sample Request Response for OAC Validation of NDNC Registered

Request 1 (Make Call Request): 

https://test.phonon.in/c2c/C2CRequest?visitor=919978889490&advertiser=919227728888&custToken=abcd1234&duration=900&uniqueID=abcd1234&udf1=100078945&udf2=200014587&udf3=400057489&udf5=30000145874

Response to Request 1 in case visitor (919978889490) is NDNC registered and OAC is not enabled:

  • NACK:NDNC:10000000000025693147

Response to Request 1 in case visitor (919978889490) is NDNC registered and OAC / MCA is enabled:

  • OAC:ACK:10000000000025693147;912653930101 

Request 2 from customer application only if OAC is enabled and once OAC is provided by site visitor: 

https://test.phonon.in/c2c/C2CRequest?custToken=abcd1234&requestId=10000000000025693147&oac=123456

Response to Request 2:

  • Incase OAC is valid: ACK:10000000000025693147

  • Incase OAC is invalid: NACK:Invalid OAC

2. Status Update API

The status update API is used to retrieve call and connection status to give real time updates while the call connection is in progress. Details for this API are as under:

Request URL

Test URI: https://test.phonon.in/c2c/RetrieveStatus?reqID=<requestID>&custToken=<CustToken>

Production URI: https://c4c.phonon.in/c2c/RetrieveStatus?reqID=<requestID>&custToken=<CustToken>

where,

  • reqID is the unique ID generated from our end as mentioned above.

  • custToken is the unique Customer token provided by Phonon to the customer.

Response String: 

Response string at any time gives the real-time status of the call.

“Advertiser:<Advertiser Call Status>;Visitor:<Visitor Call Status>;ConnStatus:<Connection Status>;”

Here, detail reasons for <Advertiser Call Status>, <Visitor Call Status> and <Connection Status> are given in the below tables.

Call Status:

0

Reserved - Not Used

0

Reserved - Not Used

1

1

Reserved (2) - Not Used

2

2

Busy

3

3

No Reply

4

4

Other Error

5

5

Success

6

6

User Hangup

7

7

Not Called [Default]

8

8

Invalid Number Format

9

9

Number Unobtainable

10

10

Call complete sucess 

11

11

Visitor Cancel Request

 

Note: The above error codes are based on consolidation of ISDN Results provided by telecom operators to make result analysis easier.

Connection Status:

1

0

Successfully Connected

2

-1

Error

3

-2

Do Not Call Hours

4

-3

To Be Connected [Default]

5

-4

Invalid IP

6

-5

Dialer Unavailable

7

-6

Not Connected

8

-7

Invalid Parameter

Sample Request & Response for Status Update API

Sample Request URL:   https://test.phonon.in/c2c/RetrieveStatus?unique_id=abcd1234&custToken=abc1234

Sample Response String:   “Advertiser:5;Visitor:6;ConnStatus:0;”

 

3. Cancel Call API

The Cancel Call API is used to disconnect any call that is in progress. Once cancel call request is received both the calls in whatever state they are are disconnected.

Cancel Call API Request

Test URI: 

http://test.phonon.in/c2c/cancelCall?requestID=<RequestID>

Production URI: 

http://c4c.phonon.in/c2c/cancelCall?requestID=<RequestID>

where,

RequestID is the unique ID generated from our end as mentioned above.

Cancel Call API Response

  • NACK:Not Valid IP

  • ACK:0:<Request_ID>

Above response is sent if the cancel request is not coming from the valid source

Sample Request & Response for Cancel Call

 

4. Online call data and billing API (XML Reports)

XML reports are used to retrieve call record data for all click-to-call services used by customer. XML reports are generated in the following format. Reports are provided in response to request from valid IP address for customer and in g-zip enabled XML format.

The reports can be retrieved through one of the following methods, viz:

  1. Pushed to Customer’s CallBack URL or 

  2. Phonon’s Web Service Pull API (enabled only on request) for given Request ID only.

  3. Phonon’s Web Service Pull API (enabled only on request) based on Date Filter.

Details for each of the options are as below:

Option 1: Customer’s CallBack API

Customer can provide an CallBack API which we can hit each time the call gets completed. CallBack API can be like https://CustomerURL/Reports. Only XML Format is supported to submit call details in CallbackAPI. Below is the XML format for the same. 

Note: The Call-back URI is called after each call attempt for a call is completed.

Option 2: Online call data and billing API for given RequestID

XML reports are used to retrieve call record data of given RequestID for all click-to-call services used by customer. XML reports are generated in the following format. Reports are provided in response to request from valid IP address for customer and in g-zip enabled XML format.

API Schema for Options 1 and 2 (Call-back and Pull API Integration)

Both optons CDR Pushed to Customer’s CallBack URL or CDR Retreived from Phonon’s Web Service Pull API (enabled only on request) are for an individual Request ID only and therefore follow the same schema.



Call-back URL

Pull API



Call-back URL

Pull API

1

XML Supported

Default

Default. API enabled on request.

2

JSON

Enabled on request

Not Supported

3

XML URI

To be provided by customer

Test URI

https://test.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&RequestId=1234

Production URI

https://c4c.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&RequestId=1234

Where:

Mandatory Parameters:

  1. Custtoken: (mandatory) your customer token

  2. RequestId: (mandatory) RequestID for your request

For example, sample request for details of RequestID=10000000000001836144 will be:

https://test.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&RequestId=10000000000001836144

Note:  The response schema will be sent with G-Zip compression.

4

XML Schema

Refer: XML API Schemas

 

5

JSON Schema

Refer: JSON API Schemas

Not Supported


XML API Schemas 

XML Schema (for Option 1: Call back URL and Option 2: Pull Web Services)

Please refer to https://s.phonon.in/schemas/CDR_billing_RequestID.XSD for schema to fetch CDRs based on the requestID.

Schema download link 

https://s.phonon.in/schemas/CDR_billing_RequestID.XSD

XML Sample
<CallReport> <NumberOfRecords>1</NumberOfRecords> <CallDetails> <referenceID id="10000000000011488966"> <advertiser>917043337901</advertiser> <visitor>919687939393</visitor> <duration>0</duration> <visitorstarttime>2014-08-04 00:44:04</visitorstarttime> <visitorconnecttime>2014-08-04 00:44:06</visitorconnecttime> <visitorendtime>2014-08-04 00:44:13</visitorendtime> <advertiserstarttime></advertiserstarttime> <advertiserconnecttime></advertiserconnecttime> <advertiserendtime></advertiserendtime> <UDF1>255187</UDF1> <UDF2>415861</UDF2> <UDF3>CallPatch</UDF3> <UDF5>919341221626</UDF5> <UDF6>917043337901</UDF6> <UDF7>India</UDF7> <UDF8></UDF7> <UDF9></UDF9> <UDF10></UDF10> <UDF11></UDF11> <UDF12></UDF12> <UDF13></UDF13> <UDF14></UDF14> <UDF15></UDF15> <referrer> </referrer> <advertiserCDRID></advertiserCDRID> <visitorCDRID>53DD7C5200000530</visitorCDRID> <NACK>ACK</NACK> <connection_status>Not Connected</connection_status> <visitor_call_status>Success</visitor_call_status> <advertiser_call_status>Not Called</advertiser_call_status> </referenceID> </CallDetails> </CallReport>

JSON API Schema (For Option 1: Call-back URI only)

JSON Schema

Please refer to https://s.phonon.in/schemas/CDR_billing_RequestID.JSON for JSON schema to fetch CDRs based on the requestID.

Schema download link

https://s.phonon.in/schemas/CDR_billing_RequestID.JSON

Schema download link 

https://s.phonon.in/schemas/CDR_billing_RequestID.JSON

JSON Sample
<CallReport> <NumberOfRecords>1</NumberOfRecords> <CallDetails> <referenceID id="10000000000011488966"> <advertiser>917043337901</advertiser> <visitor>919687939393</visitor> <duration>0</duration> <visitorstarttime>2014-08-04 00:44:04</visitorstarttime> <visitorconnecttime>2014-08-04 00:44:06</visitorconnecttime> <visitorendtime>2014-08-04 00:44:13</visitorendtime> <advertiserstarttime></advertiserstarttime> <advertiserconnecttime></advertiserconnecttime> <advertiserendtime></advertiserendtime> <UDF1>255187</UDF1> <UDF2>415861</UDF2> <UDF3>CallPatch</UDF3> <UDF5>919341221626</UDF5> <UDF6>917043337901</UDF6> <UDF7>India</UDF7> <UDF8> </UDF7> <UDF9></UDF9> <UDF10></UDF10> <UDF11></UDF11> <UDF12></UDF12> <UDF13></UDF13> <UDF14></UDF14> <UDF15></UDF15> <referrer></referrer> <advertiserCDRID></advertiserCDRID> <visitorCDRID>53DD7C5200000530</visitorCDRID> <NACK>ACK</NACK> <connection_status>Not Connected</connection_status> <visitor_call_status>Success</visitor_call_status> <advertiser_call_status>Not Called</advertiser_call_status> </referenceID> </CallDetails> </CallReport>

Option 3: Pull CDRs based on Date Filter

Customer can pull the CDRs based on date filter. Data will be shared when valid custToken is received with valid date format. Reports will only be accessible from customer’s whitelisted IP addresses.

Limitations

  1. Customer can fetch data of last 3 months.

  2. Maximum of 50,000 data can be fetched in one go. To retrieved more data, date needs to be altered in the API request.

Test URI 

https://test.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&from=ddmmyyyy&to=ddmmyyyy&customer_details=<FALSE/true>&call_details=<false/true>&connection_details=<FALSE/True>&fromrequestid=10000000000073026794

Production URI

https://c4c.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&from=ddmmyyyy&to=ddmmyyyy&customer_details=<FALSE/true>&call_details=<false/true>&connection_details=<FALSE/True>&IP=<ipAddress>&fromrequestid=10000000000073026794

Where:

Mandatory Parameters:

  1. Custtoken: (mandatory) your customer token

  2. from: (mandatory) start date from when you need report in ddmmyyyy format

  3. to:  (mandatory) end date till when you need report in ddmmyyyy format

 

Optional Parameters:

  1. customer_details: FALSE/True. Provides details of customer such as expiry date, balance etc. (default: False). If true, shows parameters highlighted in blue below.

  2. connection_details: FALSE/True. Provide additional details about each customer. (default: False). If true, shows parameters highlighted in green below.

  3. call_details: FALSE/true. Provide details of call.(default: False ) If true, shows parameters in orange font.

  4. IP: Requesting IP address filter (e.g. IP=59.90.163.27)

  5. fromrequestid : This parameter is used for Paging of Response. For any given range, if request count exceeds to 50000 then in response there will be one parameter named “latestRequestIdOfPage” which will contain last requestID of page. Customer should invoke same api with additional parameter “fromrequestid” which contains requestID got in the previous response to get next 50000 records. This will continue until all records for given range extracted and displayed in response.

Please note:

  1. The filters will work as AND filtering in case more than one filter is provided in request:

  2. Incase, you want report only with one filter, you can send other parameters as <blank> or not send those parameters at all.

  3. UDF Parameter values are returned only if they are NOT null.

For example, sample request for details of UDF1=2150 for today will be:

https://test.phonon.in/C2CWebService/CustomerUrl?Custtoken=abc1234&from=03072009&to=03072009&connection_details=true&UDF1=2150&fromrequestid=10000000000073026794 

Note:  The response schema will be sent with G-Zip compression.

XML Schema

Please refer to https://s.phonon.in/schemas/CDR_Date_Filter.XSD for XML schema details.

Schema download link

https://s.phonon.in/schemas/CDR_Date_Filter.XSD

XML Sample
<CallReport> <Customer> <!--Sent when customer_details=true--> <CustomerName>phonon</CustomerName> <Balance>1000</Balance> <ExpiryDate>07082014</ExpiryDate> </Customer> <NumberOfRecords>1</NumberOfRecords> <CallDetails> <referenceID id="10000000000011488966"> <advertiser>919898989877</advertiser> <visitor>919897124134</visitor> <visitorlocation>delhi</visitorlocation> <visitorIP>159.90.163.27</visitorIP> <duration>0</duration> <!-- duration in seconds--> <visitorcost>1</visitorcost> <!--Sent when customer_details=true--> <advertisercost>2</advertisercost> <!--Sent when customer_details=true--> <visitorstarttime>2014-08-04 00:44:04</visitorstarttime> <visitorconnecttime>2014-08-04 00:44:06</visitorconnecttime> <visitorendtime>2014-08-04 00:44:13</visitorendtime> <advertiserstarttime></advertiserstarttime> <advertiserconnecttime></advertiserconnecttime> <advertiserendtime></advertiserendtime> <UDF1>2150</UDF1> <UDF2>31253</UDF2> <UDF3>SELLER</UDF3> <UDF4>1234567890</UDF4> <UDF5>919725098056</UDF5> <UDF6>BUY/SELL</UDF6> <UDF7></UDF7> <UDF8></UDF8> <UDF9></UDF9> <UDF10></UDF10> <UDF11></UDF11> <UDF12></UDF12> <UDF13></UDF13> <UDF14></UDF14> <UDF15></UDF15> <referrer></referrer> <advertiserCDRID></advertiserCDRID> <!--sent when connection_details=true--> <visitorCDRID>53DD7C5200000530</visitorCDRID> <!--sent when connection_details=true--> <NACK>ACK</NACK> <!--sent when connection_details=true--> <connection_status>Successfully Connected</connection_status> <!--sent when connection_details=true--> <visitor_call_status>Success</visitor_call_status> <!--sent when connection_details=true--> <advertiser_call_status>Call Completed Success</advertiser_call_status> <!--sent when connection_details=true--> </referenceID> </CallDetails> <latestRequestIdOfPage>10000000000073026794 <latestRequestIdOfPage> </CallReport>

 

5. Interactive Applications API 

Note: This API is enabled on Customer Request.

This is used when interactive applications are enabled. This API calls a customer provided URL; with specific call status and inputs. On the same request, the API then receives a response from the customer and continues with the call.

API Initiation

This API is initiated through two routes:

  1. An inbound call is received on a DID number alloted to the customer.

  2. An outbound call in initiated through MakeCall request. Please note the MakeCall request will only have visitor_number parameter and no advertiser_number parameter.

Customer URL Called

<www.customerurl.com/application?>requestid=<phononrequestid>&callstatus=X&dtmf=<dtmfstring>&cli=<10digitCliofCaller>&udf1=<custudf1>&udf2=<custudf2>&ud32=<custudf3>&udf4=<custudf4>&udf5=<custudf5>&msg=<CDATA_tagged_base64_encoded_mp3_file>

Here:

  • phononrequestid is the request id returned from phonon server to customer during the makecall request.

  • dtmfstring is max 15 characters.

  • callstatus  X is:

1 : Call being initiated or incoming call received (not yet answered). 

2 : Outgoing call is connected or incoming call is answered.

4 : Prompt play completed and DTMF(s) received. dtmfstring parameter will be :

  • Full or short dtmf in case of any dtmf input received from customer.

  • Blank in case no DTMF is received or required to be captured

5 : Call ended 

  • 10digitCliofCaller this is the 10 digit number of the party on call. It is the CLI in case of an incoming call alert (Call status 1) and is the dialed number in case of outgoing calls.

  • udf1 … udf5: These are the UDF parameters sent by the customer in case of outbound batch or HTTP request based calls.

  • msg: This parameter is sent only as a response to task: 04.

 

Customer Response Expected:

Customer will provide a semi-colon (;) delimited response to the request. These response APIs work only once a call is in ‘Connected’ state. To cancel a call even it is not in the connected state, use Cancel Call API. Details of fields expected in customer response are as below.

Task - this field is of length 2 characters

  1. 00: Play file; if the DTMF characters field is populated, system will also get DTMF.

  2. 01: Play file and disconnect call

  3. 02: Disconnect call

  4. 03: Connect call

  5. 04: Recording call

  6. 05: Play digits; if the DTMF characters field is populated, system will also get DTMF.

  7. 06: Play number; if the DTMF characters field is populated, system will also get DTMF.

  8. 06: Play time; if the DTMF characters field is populated, system will also get DTMF.


Expected response data for each task is as per table below:

Task

Expected Response

Response Details

Task

Expected Response

Response Details

00, 01

<Task>;<CommaSeparatedFileNames>;<MaximumDtmfCharactersToGet>;<DtmfTimeOut>;<DtmfBargeIn>;<DtmfTerminator>;

CommaSeparatedFileNames - this field is of max length fifty characters. ‘<file1.pcm>,<file2.pcm>,<file3.pcm>’. File names are stored as .pcm only.

File names need to be loaded as per details in Prompt Upload API. 

MaximumDtmfCharactersToGet -Number of characters of DTMF to get. 

DtmfTimeOut: Number of seconds to wait for DTMF string (maximum 20) or wait for recording before function returns (maximum 90).

DtmfBargeIn: ‘Y’ for yes or ‘N’ for No.

DtmfTerminator: Optional Dtmf termination character after which system will not wait for any more dtmf.

02,03

<Task>;



04

<Task>;<CommaSeparatedFileNames>;<SilenceTimeOut>;<RecordingTimeOut>;<PlayBeep>;<DtmfTerminator>;

CommaSeparatedFileNames - this field is of max length fifty characters. ‘<file1.pcm>,<file2.pcm>,<file3.pcm>’. File names are stored as .pcm only.

File names need to be loaded as per details in Prompt Upload API. 

SilenceTimeOut -  Maximum number of seconds the function wait before returning, if no sound is detected on the line.

RecordingTimeOut: Recording maximum duration in seconds.

PlayBeep: If ‘Y’, a beep is played before recording.

DtmfTerminator: Optional Dtmf termination character after which system will not record any further.

05

<Task>;<Digits_to_be_played>;<MaximumDtmfCharactersToGet>;<DtmfTimeOut>;<DtmfBargeIn>;<DtmfTerminator>;

Digits_to_be_played - play digits upto 10 characters, alphabets and numbers.

MaximumDtmfCharactersToGet -Number of characters of DTMF to get. 

DtmfTimeOut: Number of seconds to wait for DTMF string (maximum 20) or wait for recording before function returns (maximum 90).

DtmfBargeIn: ‘Y’ for yes or ‘N’ for No.

DtmfTerminator: Optional Dtmf termination character after which system will not wait for any more dtmf.

06

<Task>;<Number_to_be_played>;<MaximumDtmfCharactersToGet>;<DtmfTimeOut>;<DtmfBargeIn>;<DtmfTerminator>;

Number_to_be_played - play numbers upto 10 digits long.

MaximumDtmfCharactersToGet -Number of characters of DTMF to get. 

DtmfTimeOut: Number of seconds to wait for DTMF string (maximum 20) or wait for recording before function returns (maximum 90).

DtmfBargeIn: ‘Y’ for yes or ‘N’ for No.

DtmfTerminator: Optional Dtmf termination character after which system will not wait for any more dtmf.

07

<Task>;<Time_to_be_played>;<MaximumDtmfCharactersToGet>;<DtmfTimeOut>;<DtmfBargeIn>;<DtmfTerminator>;

Time_to_be_played - time in Epoch / UnixTimeFormat followed by “_” underscore followed by DMY@hms. (Presently time is played in GMT+05:30.)

D=Date (DD) M=Month (MM) Y=Year (YYYY) @=separator h=hour in 24 hour format (HH) m=minutes (MI) s=seconds (SS)



Sample: 

  1. 1431926379_@hms plays: “10 hours 49 minutes 39 seconds”

  2. 1431926379_DM plays: “18th May”



MaximumDtmfCharactersToGet -Number of characters of DTMF to get. 

DtmfTimeOut: Number of seconds to wait for DTMF string (maximum 20) or wait for recording before function returns (maximum 90).

DtmfBargeIn: ‘Y’ for yes or ‘N’ for No.

DtmfTerminator: Optional Dtmf termination character after which system will not wait for any more dtmf.

6. Prompt Upload API

The Prompt Upload API is used to upload prompt using customer details and prompt details. Thereafter the customer can access this API and use the prompt for playing in any kind of interactive application. Details for this API is as under:

API Details:

XML Request schema expected is:

Please refer to https://s.phonon.in/schemas/PromptUpload.XSD for XML schema which is expected for PromptUpload API.

Schema download link

https://s.phonon.in/schemas/PromptUpload.XSD

Sample XML

<PromptUpload> <customer> <username />abcd123 <!--username provided by phonon--> <password />abcd123 <!--password provided by phonon--> <customerId/>2 <!--customer id for the user--> </customer> <prompt> <actionType>Add</actionType> <!--Add, Modify, Delete--> <promptName></promptName> <!--only for modify and delete, XXXX.pcm--> <type>tts</type> <!--TTS or File used only for add, modify. Presently only File allowed--> <text>hello</text> <!--text for TTS when type=TTS and action = add / modify--> <file></file> <!--prompt file base 64-encoded, and tagged by CDATA for type=file and action=add/modify--> </prompt> </PromptUpload>

Note: 

  1. CDATA field tagging for file will be as below: 

<file><![CDATA[.......base64-encoded content....]]></file>

  1. Presently only one <prompt> tag is allowed per request.

Response Schema will be:

For error requests:

<status>Failed</status>

<reason>details of error</reason>

For success requests:

<status>Success</status>

<prompt>promptName</prompt> <!-- prompt name will be in the format XXXX.pcm-->


Note: Responses sent for success will be for individual prompt tags.

7. Detail Retrieve API

Functionality

This Detail Retrieve API is used for times where there is integration with 3rd party CTI systems, specifically when using Click-to-Call services. The use case for this is that for the advertiser (or call center) leg of call, when the Call lands at the Call-center where 3rd party CTI systems for CT pop-up are used. In this case, the CTI system at customer site, will need end-customer meta data associated with the call received at the call center. This is represented by the block diagram below.

Application Security

Application security will be maintained through IP filtering and domain selection. Only those

requests that are received from valid permitted IP addresses will be processed. All requests can support HTTP and HTTPS. However, it is preferred that all communication should go through HTTPS APIs.

Whenever a request is received at Phonon Web Server. the request is verified on the basis of following request parameters:

  1. CustToken in the request parameter to identify the customer.

  2. Source IP from which request is made and whether this source IP is registered with phonon for the given customer.

  3. Domain from which this request was made is registered with phonon for given customer or not.

  4. Validity and balance for the customer.

If any of the above check fails we update that this request could not be processed.

Limitation

  • In such cases, Phonon will share with the customer, set of Phonon originating CLIs.

  • Whenever customer system receives a call from any Phonon originating CLIs, the Customer CTI system will call Phonon URI for Detail Retrieve as per API Details below.

  • Phonon Detail Retrieve API will in response to the customer API Call respond with associated meta-data of each call as per XML Schema represented below. 

    • This Schema will contain as per pre-defined field format all meta-data associated with the call.

    • Meta-Data consists of the following: Unique Phonon Request ID for each Click-to-Call request received on Phonon Systems, Customer Phone Number and Customer Form Fill Meta-Data stored in fields UDF1 through UDF8.

  • In case JSON responses are needed, Detail Retrieve API is supported by Phonon JSON Wrapper as per specifications below.

Representative Use Case Block Diagram

API Details

URI to Call

Request Parameters / Schema

  • Method Supported: POST / GET

  • Parameters required:

Parameter

Mandatory / Optional

Details

custToken

Mandatory

Customer Token to identify the request

CLI

Mandatory

Phonon’s CLI number from which the call is received at the call center / CRM.

Sample Request (for XML Response)

URL: https://test.phonon.in/c2c/CLIDetailRetrieve?custToken=abcd123&CLI=912652781717

Sample Request (for JSON Wrapper)

URL: https://test.phonon.in/c2c/CLIDetailRetrieve/JSON?custToken=abcd123&CLI=912652781717

Response Parameters / Schema

XML Response 
Schema

Please refer to https://s.phonon.in/schemas/CLI_Detail_Retrive.XSD for XML schema of Detail Retreive API.

Sample Response 
<root> <phononRequestID>1000000000001234567</phononRequestID> <customerDetails> <visitorNumber>919978889490</visitorNumber> <uniqueID>dnjg342124</uniqueID> <udf1>name</udf1> <udf2>address1</udf2> <udf3>address2</udf3> <udf4>address3</udf4> <udf5>Product Name</udf5> <udf6>User Defined field</udf6> <udf7>Campaign</udf7> <udf8>Lead Source</udf8> <referrerURL>Source URL</referrerURL> </customerDetails> </root>
JSON Response 
Schema

Please refer to https://s.phonon.in/schemas/CLI_Detail_Retrive.JSON for JSON schema of DetailRetrive API.

Sample Response
{ "root": { "phononRequestID": "1000000000001234567", "customerDetails": { "visitorNumber": "919978889490", "uniqueID": "dnjg342124", "udf1": "name", "udf2": "address1", "udf3": "address2", "udf4": "address3", "udf5": "Product Name", "udf6": "User Defined field", "udf7": "Campaign", "udf8": "Lead Source", "referrerURL": "Source URL" } } }

Version History:

Version Date Comment
Current Version (v. 2) Aug 31, 2021 18:32 Abhinandan Shah:
Added export of the latest version for downloading.
v. 1 Aug 31, 2021 18:22 Abhinandan Shah

Confidentiality Note

This document has been developed by Phonon for the sole and exclusive use of the customer / prospective customer with whom this document is being shared. Further, this document has been provided by Phonon in good faith to the recipient based on request from the recipient for the same. This document is a confidential document and contains confidential product technology details and for the sole usage of the intended recipients of this document. Recipients are advised not to share this document with any third party that is not the intended recipient of this document and neither to bring this document in full or parts into the public domain. Any unauthorized access may be brought to Phonon’s notice immediately. Phonon is free to take any legal action it deems necessary against any person or entity that violates this confidentiality agreement. Phonon is bound and governed by the rules of the state of Gujarat in India.

This document has been developed by Phonon.io for the sole and exclusive use of the customer / prospective customer with whom this document is being shared. Further, this document has been provided by Phonon.io to the recipient in good faith and based on request from the recipient for the same. This document is a confidential document and contains confidential product technology, workflow and commercial details that are for the sole usage of the intended recipients of this document. Recipients are advised not to share this document with any third party that is not the intended recipient of this document and neither to bring this document in full or parts into the public domain. Any unauthorized access may be brought to Phonon.io’s notice immediately. Phonon.io is free to take any legal action it deems necessary against any person or entity that violates this confidentiality agreement. Phonon.io is bound and governed by the rules of the state of Gujarat in India. In case you are not in agreement with the terms set in this clause or are not an intended recipient of this document, please destroy the document and intimate us of the same at info@phonon.io.