(4.4.12) Generic Connector JSON API
- Mariyam Mahaar
- CTI
A GC client can call this API to connect with Generic Connector.
REST JSON Format
We will use this specific format for GC REST Commands and Events for JSON API Click here for the data format
Agent Commands
Print Message
Message types and their expected output are mentioned below.
Input Message | Category | Message Type | Message Parameters | Expected Output | Comments |
|---|---|---|---|---|---|
Send Heartbeat while not logged in | system |
For Rest Command { | |||
Send Heartbeatwhile logged in | system |
| |||
Connect AgentID with Client Unique Name | agent_info |
|
| No response Note We will pass SSO as a third parameter if the user is SSO Enabled, otherwise, we will send two parameters as we are sending previously | |
Agent Login | agent_state |
{ |
| ||
Mobile Agent Login | agent_state |
{ | <agent_password>,<agent_extension>,<agent_phone>,<connection_mode> | Only on UCCE but not tested yet. | |
Agent Logout | agent_state |
| Supervisor Command | ||
Make agent ready | agent_state |
| |||
Make agent not ready | agent_state |
| Supervisor Command | ||
Get agent current state | agent_state |
| |||
Not Ready with reason code | agent_state |
|
| ||
Make a call | agent_call |
|
| ||
Answer a call | agent_call |
|
| ||
Hold a call | agent_call |
|
| ||
Unhold a call | agent_call |
|
| ||
Release a call | agent_call |
|
| ||
Get Agent Wrap-up Reason Codes | agent_work |
| |||
Get Agent Logout Reason Codes | agent_state |
| |||
Get Agent Not Ready Reason Codes | agent_state |
| |||
Blind Transfer | agent_call |
|
| For UCCX | Used only in UCCE, will update later. |
| agent_call |
|
| ||
| agent_call |
|
| ||
| agent_call |
|
| ||
Complete Conference | agent_call |
|
| ||
Get Dialog State | agent_dialog |
|
| ||
Update Dialog Wrap-up Codes | agent_dialog |
|
| No response is received when this event is called. | |
Logout with Reason | agent_state |
|
| ||
Abrupt Agent Disconnection | agent_state |
| Had do send this message in backend but the output is same as of in Expected Output | ||
Get Dialog State Controls | agent_dialog |
|
| Not Implemented yet | |
Make Work Not Ready | agent_state |
| |||
Make Work Ready | agent_state |
| |||
Get Dialog Participants | agent_call |
|
| ||
Get Logged in Agents | agent_call |
| |||
Update Dialog Variable | agent_call |
|
| Will receive this InboundCall event with updated call variables | |
Pause Zoom Call Recording | zoom | ZOOMPauseRecording#<agent_login_Id> | |||
Resume Zoom Call Recording | zoom | ZOOMResumeRecording#<agent_login_Id> | |||
Refresh | agent_state | refresh#<agent_login_Id> | |||
Get Team and Global Phonebooks | phonebook |
| |||
Get Team Phonebooks | team_phonebooks | GetTeamPhonebooks#<agent_login_id> | <TeamID> | ||
Get Contacts of a Phonebook | contacts |
|
| ||
Accept Outbound Preview Call | agent_call | AcceptOutboundPreview#< |
| Before Call Accepted After Call Accepted Call Type (OUTBOUND) | Pass ACCEPT as a second parameter if you want to accept a preview outbound call |
Reject Outbound Preview Call | agent_call | RejectOutboundPreview#< |
| Before Call Rejected AgentState(RESERVED_OUTBOUND_PREVIEW) After Call Rejected | Pass REJECT as a second parameter if you want to reject preview outbound call |
Close Outbound Preview Call | agent_call | CloseOutboundPreview#< |
| Before Call Closed Agent State (RESERVED_OUTBOUND_PREVIEW) After Call Closed | Pass CLOSE as a second parameter if you want to close preview outbound call |
Outbound Progressive Call | agent_call |
|
| Agent State (RESERVED_OUTBOUND) Call Type (OUTBOUND) | |
Outbound Predictive Call | gent_call |
|
| Agent State (RESERVED_OUTBOUND) Call Type (OUTBOUND) | |
Schedule a callback call | agent_call | SHCEDULECALLBACK#<agent_login_id> | <targetMediaAddress>,<dialog_id>,<callbackTime>,<callbackNumber> | Call Type (OUTBOUND) | |
Update a callback call | agent_call | UPDATECALLBACK#<agent_login_id> | <targetMediaAddress>,<dialog_id>,<callbackTime>,<callbackNumber> | Call Type (OUTBOUND) | |
Cancel the scheduled callback call | agent_call | CANCELSHCEDULECALLBACK#<agent_login_id> | <targetMediaAddress>,<dialog_id> | Call Type (OUTBOUND) | |
Reclassify an outbound direct preview call | agent_call | RECLASSIFYCALL#<agent_login_id> | <targetMediaAddress>,<dialog_id>,<Value> | ||
Accept the personal callback call | agent_call | AcceptOutboundPreview#< |
| Before Call Accepted Agent State (RESERVED_OUTBOUND_PREVIEW) After Call Accepted Call Type (OUTBOUND) | |
Reject the personal callback Call | agent_call | RejectOutboundPreview#< |
| Before Call Rejected Agent State (RESERVED_OUTBOUND_PREVIEW) After Call Rejected | |
Get Skill Group List | skill_group | GETSKILLGROUP#< | If you want All skill groups <ALL>,<0>,<0> If you want Indexing of skill groups <INDEXING>,<1>,<25> | Implemented only for UCCE | |
Get Supervisor List | supervisor_list | GETSUPERVISOR#< | Implemented only for UCCE | ||
Get Agent Extension | agent_extension | GETAGENTEXTENSION #< | <F_Number> | Implemented only for UCCE |
Supervisor Commands
Input Message | Category | Message Type | Message Parameters | Expected Output | Comments |
|---|---|---|---|---|---|
Get Queue Info | supervisor_queue_info |
| |||
Silent Monitor (Supervisor Function) | supervisor_dialog |
|
| On Supervisor On Agent | |
End Silent Monitor (Supervisor Function) | supervisor_dialog |
|
| ||
Drop Participant (Supervisor Function) | supervisor_dialog |
|
| ||
Get Team Users (Supervisor Function) | supervisor_team |
|
| If you want to get team user and also want to subscribe team events then pass
Otherwise just pass
| |
Get Team Users State (Supervisor Function) | supervisor_team_member_state |
|
| Not implemented in client yet | |
Make a Barge Call | agent_call |
|
| ||
Agent Logout | agent_state | Logout#<agent_login_Id> | |||
Make agent not ready | agent_state | MakeNotReady#<agent_login_Id> |
Admin Commands
Input Message | Category | Message Type | Message Parameters | Expected Output | Comments |
|---|---|---|---|---|---|
Get Team and Global Phonebooks | phonebook |
| |||
Get Contacts of a Phonebook | contacts |
|
| ||
Get Team Phonebooks | phonebook |
| <TeamID> |
Queue Name
The queue name is received every time an agent consults/transfers/conferences with another agent, but on the Alerting event, the queue name remains empty & on the Answering event it shows the value in the queue name.
On answering the call but not on alerting event{}
Queue name appears in all below cases for CCE 12.6
Extension:
Consult.
Consult-Transfer.
Direct-Transfer.
Consult-Conference
Queue DN
Consult.
Direct-Transfer.
Consult-Transfer.
Consult-Conference
GC Events
GC events as published by GC after receiving Finesse events:
System Status
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | System | System{
"type": "System",
"status": "OUT_OF_SERVICE"
}
| |
status | IN_SERVICE | OUT_OF_SERVICE |
SUBSCRIPTION_FAILED
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | Error | System{
"type": "Error",
"errorType": "SUBSCRIPTION_FAILED || Unauthorized",
"errorMessage": "Invalid Credentials"
} |
Connect Status
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | ConnectStatus | System{
"type": "ConnectStatus",
"status": "ConnectSuccess"
} | |
status | ConnectSuccess |
Agent Info
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | AgentInfo | Agent Info | |
firstName | Agent's first name | ||
lastName | Agent's last name | ||
supervisor | true | false | Is this agent a supervisor? | |
wrapUpOnIncoming | |||
totalNumberOfTeams | Total numbers of teams | ||
teams | If the agent is a supervisor, it's an array of all teams. Each element is a team object as defined below. | ||
team | Agent's team | ||
agentId | Agent ID |
Agent State
Attribute | Value | Description | Sample Output Agent | Sample Output Supervisor |
|---|---|---|---|---|
type | State | Agent State | ||
State | Agent state | From one of the following agent states: UNKNOWN, | Agent State | |
reasonCode | Not Ready reason codes as defined in Finesse | |||
stateChangeTimeString | not used | |||
pendingState | Only available with UCCE and as passed by Cisco Finesse | |||
stateChangeTime | 2019-09-17 12:46:21 | Date & Time of state change | ||
fullName | Agent full name | |||
extension | Agent's extension | |||
label | break | state change label |
Inbound Call State
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | InboundCall | Attributes may vary for each type of Call object. | Agent Call |
dialogID | Finesse Dialog ID | ||
state | One of the Finesse dialog states | ||
startTime | The start time of the call | ||
associatedDialogId | Finesse Dialog ID | ||
fromAddress | A number from an inbound call is placed | ||
callVariables | A total of 10 call variables as received from Finesse | ||
participants | Participants engaged in the call | ||
callType | Call type | ||
agentId | Agent ID | ||
queueName | Queue Name |
New Outbound Call State
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | OutboundCall | Attributes may vary for each type of Call object. | Agent Call |
dialogID | Finesse Dialog ID | ||
state | One of the Finesse dialog states | ||
startTime | The start time of the call | ||
prevDialogId | Finesse Dialog ID | ||
fromAddress | A number from an inbound call is placed | ||
callVariables | A total of 10 call variables as received from Finesse | ||
participants | Participants engaged in the call | ||
callType | Call type | ||
agentId | Agent ID | ||
queueName | Queue Name |
New Outbound Preview Call State
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | OutboundCall | Attributes may vary for each type of Call object. |
Agent Call
|
dialogID |
| Finesse Dialog ID | |
state |
| One of the Finesse dialog states | |
startTime |
| The start time of the call | |
prevDialogId |
| Finesse Dialog ID | |
fromAddress |
| A number from an inbound call is placed | |
callVariables |
| A total of 10 call variables as received from Finesse | |
participants |
| Participants engaged in the call | |
callType |
| Call type | |
agentId |
| Agent ID | |
queueName |
| Queue Name |
New Inbound Call
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | NewInboundCall | New Call | |
dialogID | Finesse Dialog ID | ||
fromAddress | A number from an inbound call is placed | ||
callVariables | A total of 10 call variables as received from Finesse | ||
callType | Call Type | ||
agentId | Agent ID | ||
queueName | Queue Name |
Reason Codes
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | ReasonCodes | Reason Codes | |
category | WrapUp | LOGOUT | NOT_READY | as passed in the request | |
reasonCodes | key-value pair of defined reason codes of the specified category | ||
agentId | Agent ID |
Consult Call State
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | ConsultCall | Consult Call States | |
state | INITIATING | INITIATED | state of call | |
assDialogId | This is an associated Dialog ID. In case of consult call, dialogId is named as assDialogId | ||
startTime | Starting Time of call | ||
fromAddress | A number from which consult call is initiated | ||
toAddress | A number to which the consult call is requested | ||
callVariables | Call Variables in Finesse | ||
participants | Participants engaged in call | ||
callType | Call Type | ||
agentId | Agent ID | ||
queueName | Queue Name |
Release Call Output
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | InboundCall | Dropped Call | |
dialogId | ID of the call | ||
prevDialogId | null | prevDialogId is not null if call is being transferred to another agent | |
state | state of call | ||
agentId | Agent Id | ||
queueName | Queue Name |
Complete Conference
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | InboundCall | Complete Conference | |
dialogId | DialogId is id of the call | ||
state | Active | States in Finnese | |
startTime | Starting Time of call | ||
prevDialogId | null | Dialog Id in Finesse | |
fromAddress | A number from an inbound call is placed | ||
callVariables | Call Variables in Finesse | ||
participants | Participants engaged in call | ||
callType | Call Tyep | ||
agentId | Agent ID | ||
queueName | Queue Name |
Transfer Call
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | InboundCall | Complete Transfer | |
dialogId | Dialog Id in Finesse | ||
state | Held | States in Finnese | |
startTime | Starting Time of call | ||
associatedDialogId | null | Dialog Id in Finesse | |
fromAddress | A number from an inbound call is placed | ||
callVariables | Call Variables in Finesse | ||
participants | Participants engaged in call | ||
callType | Call Type | ||
agentId | Agent ID |
Get Dialog State
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | DialogState | Dialog State | |
dialogId | Dialog Id in Finesse | ||
state | INITIATED | ALERTING | ACTIVE | HELD | NOT_FOUND | This is state of the call | |
agentId | Agent ID |
Get All Agents
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | Agents | Get All Agents | |
users | List of login agents |
Get Team User
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | Team Agents | Get All Agents | |
users | List of team user |
Get Queue List
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | Queue Stats | GetQueueInfo | |
queue | queue stats info |
Phonebooks
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | PhoneBook | List of phonebooks |
Team Phonebooks
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | Team PhoneBook | List of phonebooks |
Contacts
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | phoneBook_contacts | List of contacts |
Print Message
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | status | status-bar |
Participant Drop Message
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | control | status-bar |
CallBack Message
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | callback | callback scheduled |
Reclassify Message
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | callback | reclassify |
|
No Data Found Message
Attribute | Value | Description | Sample Output (JSON) |
|---|---|---|---|
type | callback | callback scheduled |
Get Skill Groups
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | skillGroup | Get All Agents | |
skills | List of all skillGroups |
Get Supervisor List
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | supervisors | Get All Agents | |
supervisors | List of all supervisors |
Get Agent Extension
Attribute | Value | Description | Sample Output |
|---|---|---|---|
type | agentExtension | Get All Agents | |
agentExtension | mobile agent port and dialNumber |
Errors
Error_Code | Error_Origin | Error Description | Expected Driver Behaviour | |
CF_INVALID_CALLED_DEVICE | Finesse | The called device is not valid | display the error message and continue regular operations | |
CF_INVALID_CALLING_DEVICE | Finesse | The calling device is not valid | display the error message and continue regular operations | |
CF_INVALID_CONNECTION_ID_FOR_ACTIVE_CALL | Finesse | The active connection ID in the request is invalid | display the error message and continue regular operations | |
CF_INVALID_CONSULT_TYPE | Finesse | The consult type is invalid | display the error message and continue regular operations | |
CF_AGENT_ACCOUNT_LOCKED_OUT | Finesse | The account is locked out | display the error message and continue regular operations | |
CF_INVALID_CSTA_DEVICE_IDENTIFIER | Finesse | The device ID is not valid. | display the error message and ask user to enter valid Extension | |
CF_RESOURCE_BUSY | Finesse | An internal resource is busy | ||
CF_INVALID_LOGON_DEVICE_SPECIFIED | Finesse | The request specified an invalid logon device. | display the error message and ask user to enter valid Extension | |
CF_GENERIC_UNSPECIFIED_REJECTION | Finesse | The request has been rejected (no specific details available). | ||
CF_INVALID_OBJECT_STATE | Finesse | The object is in the incorrect state for the request. | ||
CF_INVALID_PASSWORD_SPECIFIED | Finesse | The request specified an invalid agent password. | Prompt user to supply a valid password | |
CF_GENERIC_SYSTEM_RESOURCE_AVAILABILITY | Finesse | | ||
E_CTI_INVALID_CALLID | Finesse | A request message was received with an invalid CallID value. | ||
USER_NOT_FOUND | Finesse | When Agent ID isn't found in Finesse | Display the error message | |
GENERAL_ERROR | Finesse | when root cause is unclear | display the error message and continue regular operations | |
CF_GENERIC_OPERATION | Finesse | An operation error occurred (no specific details available). | display error message according to the last command sent | |
BAD_DESTINATION | Finesse | Agent called to an invalid extension | display the error message and continue regular operations | |
DOWN | GC | IOException | display the error message and continue regular operations | |
LICENSES_EXCEEDED | GC | User license limit exceeded | display the error message | |
MISSING_EXTENSION | GC | Missing Extension | display the error message and ask user to enter extension | |
MISSING_NUMBER | GC | Number to dial is missing in request | display the error message and ask user to enter dial number | |
MISSING_PASSWORD | GC | Password is missing in request | display the error message and ask user for credentials | |
MISSING_REASON_CODE | GC | GC/Finesse expects reason-code that wasn't provided by the client | display the error message and ask user to provide reason code | |
NO_DIALOG_ID | GC | The requested dialog doesn't exists in GC | send getdialogstate request for any active dialogs | |
NOT_REACHABLE | GC | SocketTimeoutException | display the error message and continue regular operations | |
PLEASE_RETRY | GC | invalid request params, IOException, request timeout | display the error message and continue regular operations | |
SUBSCRIPTION_FAILED | GC | Invalid credentials supplied for agent login | display the error message and ask user to enter valid credentials | |
UNABLE_TO_SUBSCRIBE_TO_FINESSE | GC | Invalid credentials supplied for agent login | display the error message and ask user to enter valid credentials | |
WRONG_EXTENSION | GC | Extension is not valid (contains alphabetic characters) | display the error message and ask user to enter valid Extension | |
SESSION_INVALIDATED | GC | The current session session for login has been invalidate, user has been logged in from a new destination. GC will send a logout message followed by this message | display the error message and ask user to login again | |
Note: Some of the error from finesse are mentioned here. Rest of the Finesse errors can be found in this document on page 17: https://drive.google.com/open?id=0B0txXw8kofb1blBxenFmcHBWcms | ||||