API Guide

Introduction

ST 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://<st-server>:<port>/eabc/<object>/<instanceId>

URL Structure	Description
<adminpanel-server>	Routable address (IP address) of the CCAdmin 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 CCAdmin REST APIs are listed here:

Code	Message	Description
400	Bad Request	Request parameters are invalid.
401	Unauthorized	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 take 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 Easy Announcements.

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 to retrieve business shifts for an Agency or a site. An Agency could be a site, a contact center or a specific CSQ which 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 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 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	This messages returns 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 CCAdmin 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:

JSON

{"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 to the time of the API call.

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

JSON

{"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.

JSON

{"message":"EXCEPT"}

This status is returned if the API finds an Exceptional event at the time of the API call.

JSON

{"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.

JSON

{"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.
Holiday: To play public holidays on the IVR
Working: To insert or play business working hours

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 the dialed number of the help line (or CCX trigger) on which the announcement should be played.
ANI	true	Calling 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 that 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

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
announcementDetails	Array(s) of string	This gives the details of an easy announcement, including id, name and prompts string within the easy announcement.

Sample Success Response

JSON

{
  "prompts":"incident.wav,goodbye.wav",
  "announcementsDetails":[
    {
      "announcementId":"51",
      "announcementName":"Outage",
      "prompts_list":[
        "incident.wav",
        "goodbye.wav"
      ]
    }
  ],
  "status":{
    "enumType":"org.springframework.http.HttpStatus",
    "name":"OK"
  },
  "message":"Request Completed Successfully."
}

Get Service Status Announcements

This API call is used to get the status of a contact center service (DN). First, it checks if it is a Holiday on the service and returns a holiday announcement. If not found, it checks if the service is active and currently Working. To define/play working hours of a service, create an announcement of type Working in Easy Announcements module.

HTTP Method	GET
URI	http://<adminpanel-server>:<port>/eabc/serviceStatus/getAnnouncements?dn={?}&ani={?}&placeHolder={?}
Content Type	Application/JSON
HTTP Success Code	200
HTTP Failure Code	404,405

Request Params

Following parameters should be sent with the request URL

Parameter	Required	Description
DN	true	Directory Number. This the dialed number of the help line (or CCX trigger) on which the announcement should be played.
ANI	true	Calling 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 that 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

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

Parameter	Expected Result	Description
service_status	ACTIVE / NOT_ACTIVE	ACTIVE: This means that the service is active and API call time falls under the opening hours of the service. NOT_ACTIVE: This means that either the service is closed or it is a holiday.
error_code	0 / 1	0: This means that the service processed successfully and the contact center is ACTIVE. 1: This means that one of the following is true: The service is closed, It is a holiday. An error occurred in servicing the request.
prompts	Comma Separated String	This is the list of prompts associated with the announcement. A working announcement can or cannot have audio prompts associated with it.
type	Working/ Holiday/ Nothing	Working: If a Working announcement is found Holiday: If a Holiday is found Nothing: Neither holiday nor working announcement is found
announcementsDetails	Arrays of string	This gives the details of an easy announcement, including id, name and prompts string within the easy announcement.

Sample Success Response

JSON

{
  "service_status":"NOT_ACTIVE",
  "Error_code":1,
  "type":"HOLIDAY",
  "prompts":"holiday.wav,goodbye.wav",
  "announcementsDetails":[
    {
      "announcementId":"71",
      "announcementName":"Holiday",
      "prompts_list":[
        "holiday.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 region against specific ANI. If not found, It will ask to provide correct ANI which is required to get region of 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 number of the customer,which is then used to return region.

Response Params

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

Parameter	Expected Result	Description
name	String	Name of region against specific ANI.
status	HTTP Status	API Response Code (i:e 200, 404, 406)

Sample Success Response

JSON

{
  "name":"Any",
  "status":{
    "enumType":"org.springframework.http.HttpStatus",
    "name":"OK"
  }
}

Callers

Callers are added in particular caller lists in CCAdmin Caller Lists module, to get specific treatment on the IVR. As soon a calls comes in, the UCCX scripting engineers are supposed to call the following APIs to get the caller list to which a caller belongs.

Based on the response, customized IVR treatment can be provided to the caller. For instance, give an IVR bypass or route the call to an expert queue if a caller is a VIP or GOLD customer.

Get caller

This is the REST API call to check if a particular caller exists in the specified caller list. The response also returns the audio prompts associated with the caller list if there exists any.

The prompts returned are then played to the caller on the IVR. For instance, play a prompt to a malicious caller and drop the call straight away.

HTTP Method	GET
URI	http://<adminpanel-server>:<port>/eabc/callerInList/getCallerInLists?callingNumber={?}&listName={?}
Content Type	Application/JSON
HTTP Success Code	200
HTTP Failure Code	404,405

Request Params

Following parameters would be sent in the request URL

Parameter	Required	Description
callingNumber	true	This is the number of the caller.
listName	false	The name of the caller list to check if the caller exists in this list.

Response Params

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

Parameter

Expected Result

Description

callerExist

true/false

True - if caller exists in the given list name

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

files

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

listName - name of the list in which the given caller exist

files - comma separated prompt files

Sample Success Response

CODE

{
  "callerExist": false,
  "files": [
    {
      "listName": "ListA",
      "files": "Prompt 1.wav,Prompt2.wav"
    },
    {
      "listName": "ListB",
      "files": "Prompt 1.wav,Prompt2.wav"
    }
  ],
  "status": {
    "enumType": "org.springframework.http.HttpStatus",
    "name": "OK"
  },
  "message": "Request Completed Successfully."
}

KPI:

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

Parameters:

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

Sample Result parameters:

Parameter	Expected Result	Description
message	String	Displaying the Kpis and values related to dial number
kpi	Array	Returns KPI array of objects
values	Any numeric value	(i:e 2211)
Status	Ok in case status is 200 etc	It shows the status of the request, whether it is completed successfully or not

Example:

CODE

{
  "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

Parameters:

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 user want in each API call. It is an optional parameter, if not provided then API will simply fetch complete list of available KPI Services in Database.

Sample Result parameters

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	Object of KPI associated with KPI service
dailNumbers	Array	Returns the list of DNs associated with KPI service
Status	Ok in case status is 200 etc	It shows the status of the request, whether it is completed successfully or not

Example:

CODE

[
  {
    "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"
    ]
  }
]