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

http://<adminpanel-server>:<port>/eabc/<object>/<instanceId>

URL Structure

Description                  

<adminpanel-server>

Routable address (IP address) of the Supervisor Tools Server.

<port>

Tomcat port

<object>

One of the supported objects.  

<instanceId>

Optional component needed for GET, DELETE, PUT methods referring to a specific instance of the object. 

Supported Operations

Operation

HTTP

Method

Description                  

Input

Output

LIST

GET

List all the instances of an object

None

List of objects

GET

GET

Get details of an instance specified by instanceId

ID/Name

Single Object instance

SAVE

POST

Create a new instance object 

New instance data

None

UPDATE

PUT

Modify the instance specified by the instanceId

Modified instance data


DELETE

DELETE

Delete the instance specified by the instanceId

ID

None


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.

Note

Business calendars allow to insert shift opening/closing hours on the calendar and make intelligent routing decisions based on that information. It does not yet include announcements to be played on the IVR. If you need to play/change announcements dynamically such as to play public holidays on the IVR, you can create an Easy Announcement for the event (such as a holiday or non-working hour). To learn more, see EasyAnnouncement

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. 

HTTP Method

GET                  

URI

http://<adminpanel-server>:<port>/eabc/BCServiceStatus/getServiceStatus?agencyName={?}&serviceName={?}

Content Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,406,405

Request Params

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

Parameter

Required

Description  

agency

true

Agency name

service

false

Service name

Response Params

Following parameters would be received.

Parameter

Expected Result  

Description 

message

{CLOSED / OPEN / EXCEPT / FERIE / NOTHING }_event_name

These messages return the current status of the business calendar.  In the message, it also returns the name of the event or the shift schedule only when the agency is found to be CLOSED.

event_name

string

Name of the shift schedule. This is a label assigned to each new shift schedule that is created in Supervisor Tools Business Calendars module. This helps in creating multiple shift schedules for an agency with different schedule names. For instance, define separate shift timings for winters and summers.

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”

HTTP Method

GET           

URI

http://<adminpanel-server>:<port>/eabc/generalAnnouncement/getAnnouncements?dn={?}&ani={?}&placeHolder={?}

Content Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,405

Request Params

Following parameters should be sent in the request URL

Parameter

Required

Description  

DN

true

Directory Number. This is the dialed number of the helpline (or CCX trigger) on which the announcement should be played. 

ANI

true

Calling a number of the customer, along with the number prefix. This prefix is then used to filter announcements based on the caller region.

placeHolder

false

A label or tag is used to filter the announcement on the IVR. For instance, use the placeholder with the CSQ name to play a prompt on a particular queue node.

Response Params

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

Parameter

Expected Result  

Description 

prompts

Comma Separated String

This is the list of prompts associated with the announcement

textMessages

Comma Separated String

This is the list of text messages associated with the announcement.

announcementDetails

Array(s) of string

This gives the details of an easy announcement, including id, name, text message string, and prompts string within the easy announcement. 

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.

HTTP Method

GET                 

URI

http://<adminpanel-server>:<port>/eabc/region/getRegion?ani={?}

Content Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,406

Request Params

Following parameters should be sent with the request URL

Parameter

Required

Description  

ani

true

Calling a number of the customer, which is then used to return region.

Response Params

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

Parameter

Expected Result  

Description 

name

String

Name of the region against specific ANI.

status

HTTP Status

API Response Code (i:e 200, 404, 406)

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

HTTP Method

GET

URI

http://<adminpanel-server>:<port>/clm/callerInList/getCallerInLists?callingNumber={?}&listName={?}

Content Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,405


Request Params

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


Parameter

Required

Description  

callingNumber

true

This is the number of the caller. It is a mandatory parameter, if not provided it shows the statements as “Invalid format”. If callingNumber is wrong then an empty object is shown

listName

false

The name of the caller list to check if the caller exists in this list. 

  • In case callerlist is not provided then all the callerlists containing provided number will be shown. 

  • In case callerlist is provided then only that callerlist is checked against a specific number, if the number is not present in that list then callerExist: false is shown

 

  • In case callerlist is not provided and calling number is not present in any of the list then callerExist: false is shown

 

  • In the case of timeToLive, only those lists are shown against number where the number has valid timeToLive

 

Response Params


Parameter

Expected Result  

Description 

callerExist

true/false

True - if caller exists in the given list name

False - if list name is not specified and the caller doesn’t exist in the given list

files

List of objects and each object contain list name and file attributes

listName - The name of the list in which the given caller exists

files - comma-separated prompt files

timeToLive

Date/time in case it is valid
String message in case it is invalid

timeToLive: The time duration during which a caller will remain active in some specific list

Status 

Ok in case of status is 200 etc

It shows the status of the request, whether it is completed successfully or not

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.

HTTP Method

GET

URI

http://<adminpanel-server>:<port>/kpi/ServiceKPI/search?DN=4321

Content-Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,405



Request Params

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

Parameter

Required

Description  

DN

true

Dial Number that is used to search KPIs and values related to it


Response Params


Parameter

Expected Result  

Description 

message

String

Displaying the KPIs and values related to dial the number

kpi

Array

Returns KPI array of objects

values

Any numeric value

(i:e 2211)

Status 

Ok in case of status is 200 etc

It shows the status of the request, whether it is completed successfully or not




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

HTTP Method

GET

URI

http://<adminpanel-server>:<port>/kpi/ServiceKPI?max={?}

Content-Type

Application/JSON 

HTTP Success Code

200

HTTP Failure Code

404,405



Request Params

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


Parameter

Required

Description  

max

false

This parameter describes the number of KPI Services users want in each API call. It is an optional parameter, if not provided then API will simply fetch a complete list of available KPI Services in the Database.

Response Params


Parameter

Expected Result  

Description 

name

Name of the KPI Service

Name of KPI Service provided at creation time.

description

Description

Tells about KPI Service description

value

Any numeric value

(i:e 2231)

kpi

Object

The object of KPI associated with KPI service

dailNumbers

Array

Returns the list of DNs associated with KPI service

Status 

Ok in case of status is 200 etc

It shows the status of the request, whether it is completed successfully or not




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"

        ]

    }

]