IVR API Reference

Introduction

Supervisor Tools offers RESTful APIs for integration with UCCX IVR. Each object supports five methods (except where documented otherwise) that can be invoked on the URL which is associated with the object. 

The structure of the URL is

https://<adminpanel-server>:<port>/umm/eabc/<object>/<instanceId>

Supported Operations

All methods support Application/JSON as input MIME types.

Failure Response Codes

The failure response codes for Supervisor Tools REST APIs are listed here: 

• 400: Bad Request

• Request parameters are invalid. 

• 401: Unauthorized 

• The user is valid but does not have permission to perform the specified action. 

• 404: Not Found 

• If the record that was supposed to be updated is not found on the server. 

• 405: Method Not Allowed 

• If the requested action/method is not allowed with the requested object. For instance, if the defined action for an object is GET and the request is made with POST.

• 406: Not Acceptable

• Request parameters are invalid. 

• 500: Internal Server Error

• If there is an issue on the server-side while processing the request.

CORS

Cross-Origin Resource Sharing (CORS) is supported that allows you to place requests to configuration APIs from any origin.

Business Calendars 

Business calendars allow the businesses to set hours of operation, public holidays, and exceptional openings/closings of the service. Based on these calendar configurations, scripting engineers can either route a caller to an appropriate CSQ or play a static CCX prompt on the CCX script to the caller, to drop the call on the IVR.

Get Service Status (of business calendars)

A business calendar is created with an Agency and/or a Service (that is offered within the agency). 

The Service Status API for business calendars allows retrieving business shifts for an Agency or a site. An Agency could be a site, a contact center, or a specific CSQ that can have its own shift timings and public holidays. 

The Service Status API checks the status of a calendar, i.e. if the agency is Opened, Closed, has a Holiday, or has an Exceptional opening or closing. 

The order in which the API checks  the status is the following:
Based on the date/time of the API call, it first checks if there is an Exceptional event (exceptional opening/closure). Then queries to see if there is a Holiday.  If no exceptional or holiday event is found, it returns OPENED, CLOSED, or NOTHING based on the defined shift schedule. 

Request Params

Following parameters should be sent with a request by specifying them in the URL

Response Params

Following parameters would be received.

Sample Success Responses

Following are the possible status messages:

1. {"message":"CLOSED_winter","event_name":"winter"}

This message is returned if the site is closed and there are no opened shifts at the time of the call. This assumes that there is at least one shift schedule present in the system but the time of the shifts does not match the time of the API call. 

In this case, the API returns the event name along with the message status.

1. {"message":"OPEN","event_name":"winter"}

This message is returned if a shift is opened at the time of the API call. In this case, the API sends only the message status without the schedule name associated to it.

1. {"message":"EXCEPT"}
   This status is returned if the API finds an Exceptional event at the time of the API call.
   
   
2. {"message":"FERIE","holiday_name":"test_holiday"}
   This status is returned if the API finds a holiday for the agency at the time of the API call.
   
   
3. {"message":NOTHING"}
   This status is returned if the API doesn’t find any shift schedule attached with that particular business calendar or if the date range specified with the shift schedule does not match.

Easy Announcements

An easy announcement is one or a group of UCCX prompts which are played on the IVR to callers calling from a specific region and on a particular Dialed Number (DN) during a particular period of time.

Following are the available announcement types: 

• General: For all general announcements such as promotions, incidents/outages. 

Get GENERAL Announcements

This API is used to get announcement(s) of type “General”. 

Request Params

Following parameters should be sent in the request URL

Response Params

The following table lists the responsible parameters that would be returned in the call to the API.

Sample Success Response

{

"Prompts":"incident.wav,goodbye.wav",

"textMessages":"text message one, text message 2"

,"announcementsDetails":

[

{"announcementId":"51","announcementName":"Outage","textMessages":["message1,message2"],"prompts_list":["incident.wav","goodbye.wav"]}

],

"status":{"enumType":"org.springframework.http.HttpStatus","name":"OK"},"message":"Request Completed Successfully."}

Get Regions

This API call is used to get the region of a Customer Number (ANI). First, it checks If ANI is provided to get the region then returns the region against specific ANI. If not found, It will ask to provide the correct ANI which is required to get a region of the customer.

Request Params

Following parameters should be sent with the request URL

Response Params

The following table lists the responsible parameters that would be returned in the call to the API.

Sample Success Response

{

    "name": "Any",

    "status": {

        "enumType": "org.springframework.http.HttpStatus",

        "name": "OK"

    }

}

Caller List

This is the api to check whether a specific caller exist in the list or not. It also returns the prompts associated to a particular callerlist

Request Params

The API takes two parameters. One of the parameters “Calling Number” is mandatory while the other parameter “Callerlist” is optional. 112233111111

Response Params

Sample Success Response

{

    "callerExist": true,

    "files": [

        {

            "listName": "ListA",

            "files": "Prompt 1.wav,Prompt2.wav"

        },

        {

            "listName": "ListB",

            "files": "Prompt 1.wav,Prompt2.wav"

        }

    ],

    "timeToLive": "2018-12-13 23:59",

    "status": {

        "enumType": "org.springframework.http.HttpStatus",

        "name": "OK"

    },

    "message": "Request Completed Successfully."

}

KPI List

This API is used to search KPI on the base of DN.

Request Params

The API takes one parameter. Which is “DN” and it is required. 

Response Params

Sample Success Response

{

    "Message": "Displaying the KPIs and values related to dial number",

    "kpi": [

        {

            "kpi": {

                "id": 6,

                "name": "TEA_115",

                "description": null,

                "code": "1151"

            },

            "value": "240"

        }

    ]

}

This API is used to check the list of available KPI Services

Request Params

The API takes one parameter. Which is “max” and it is optional. 

Response Params

Sample Success Response

[

    {

        "id": 1,

        "name": "service_KPI",

        "description": "Adding more KPI services",

        "value": "111",

        "kpi": {

            "id": 2,

            "name": "Add_KPI",

            "description": "Adding more KPIs",

            "code": "123"

        },

        "dialNumbers": [

            "12",

            "12345678"

        ]

    }

]