(4.4.11) Generic Connector JSON API
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 | Hello#<client_destination> | System Status | ||
Send Heartbeatwhile logged in | system | Beat#<client_destination> | System Status | ||
Connect AgentID with Client Unique Name | agent_info | Connect#<agent_login_Id> |
| 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 | Login#<agent_login_Id> | <agent_password>,<agent_extension> | ||
Mobile Agent Login | agent_state | MobileAgentLogin#<agent_login_Id> | <agent_password>,<agent_extension>,<agent_phone>,<connection_mode> | Only on UCCE but not tested yet. Set connection mode to “true” for “call by call”, “false” for “nailed connection”. | |
Agent Logout | agent_state | Logout#<agent_login_Id> | Agent State | Supervisor Command | |
Make agent ready | agent_state | MakeReady#<agent_login_Id> | Agent State | ||
Make agent not ready | agent_state | MakeNotReady#<agent_login_Id> | Agent State | Supervisor Command | |
Get agent current state | agent_state | GetState#<agent_login_Id> | |||
Not Ready with reason code | agent_state | MakeNotReadyWithReason#<agent_login_Id> | <agent_reason_code> | Agent State | |
Make a call | agent_call | MakeCall# <agent_login_Id> | <Other_Party_Extension_Number> | ||
Answer a call | agent_call | AnswerCall# <agent_login_Id> | <Dialog_ID> | Inbound Call | |
Hold a call | agent_call | HoldCall#<agent_login_Id> | <Dialog_ID> | ||
Unhold a call | agent_call | RetrieveCall#<agent_login_Id> | <Dialog_ID> | ||
Release a call | agent_call | ReleaseCall#<agent_login_Id> | <Dialog_ID> | ||
Get Agent Wrap-up Reason Codes | agent_work | wrapupreasoncode#<agent_login_Id> | Reason Codes | ||
Get Agent Logout Reason Codes | agent_state | reasoncodelogout#<agent_login_Id> | Reason Codes | ||
Get Agent Not Ready Reason Codes | agent_state | reasoncodenotready#<agent_login_Id> | Reason Codes | ||
Blind Transfer | agent_call | Transfer_sst#<agent_login_Id> | <Other_Party_Extension_Number>,<Dialog_ID> | For UCCX | Used only in UCCE, will update later. |
Consult Call | agent_call | ConsultCall#<agent_login_Id> | <Other_Party_Extension_Number>,<Dialog_ID> | Consult Call | |
Conference Inititation | agent_call | ConsultCall#<agent_login_Id> | <Other_Party_Extension_Number>,<Dialog_ID> | Consult Call | |
Complete Transfer | agent_call | TransferCall#<agent_login_Id> | <agent_extension>,<Dialog_ID> | Transfer Call | |
Complete Conference | agent_call | Conferencecall#<agent_login_Id> | <agent_extension>,<Dialog_ID> | Conference Call | |
Get Dialog State | agent_dialog | getdialogstate#<agent_login_Id> | <Dialog_ID> | Dialog State | |
Update Dialog Wrap-up Codes | agent_dialog | wrapup#<agent_login_Id> | <Wrapup_Reason>,<dialog_id> | No response is received when this event is called. | |
Logout with Reason | agent_state | logoutwithreason#<agent_login_Id> | <ReasonCode> | Agent State | |
Abrupt Agent Disconnection | agent_state | force_logout#<agent_login_Id> | 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 | getdialogstatecontrols#<agent_login_Id> | <Dialog_ID> | Not Implemented yet | |
Make Work Not Ready | agent_state | makeworknotready#<agentID> | |||
Make Work Ready | agent_state | makeworkready#<agentID> | |||
Get Dialog Participants | agent_call | getDialogParticipants#<agent_login_id> | <dialog_id> | ||
Get Logged in Agents | agent_call | getallagents#<agent_login_id> | Get All Agents | ||
Update Dialog Variable | agent_call | update_call_variable#<agent_login_Id> | <dialog_id>,<variable_name=variable_value> | Inbound 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 | GetPhonebooks#<agent_login_id> | Phonebooks | ||
Get Team Phonebooks | team_phonebooks | GetTeamPhonebooks#<agent_login_id> | <TeamID> | TeamPhonebooks | |
Get Contacts of a Phonebook | contacts | GetPhonebookContacts#<agent_login_id> | <PhonebookID> | Contacts | |
Accept Outbound Preview Call | agent_call | AcceptOutboundPreview#<agent_login_id > | <dialog_id>,<ACCEPT> | Before Call Accepted Agent State (RESERVED_OUTBOUND_PREVIEW) 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#<agent_login_id > | <dialog_id>,<REJECT> | Before Call Rejected Agent State (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#<agent_login_id > | <dialog_id>,<CLOSE> | 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 | AnswerCall# <agent_login_Id> | <Dialog_ID> | Agent State (RESERVED_OUTBOUND) Call Type (OUTBOUND) | |
Outbound Predictive Call | gent_call | AnswerCall# <agent_login_Id> | <Dialog_ID> | 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#<agent_login_id > | <dialog_id>,<ACCEPT> | Before Call Accepted Agent State (RESERVED_OUTBOUND_PREVIEW) After Call Accepted Call Type (OUTBOUND) | |
Reject the personal callback Call | agent_call | RejectOutboundPreview#<agent_login_id > | <dialog_id>,<REJECT> | Before Call Rejected Agent State (RESERVED_OUTBOUND_PREVIEW) After Call Rejected | |
Get Skill Group List | skill_group | GETSKILLGROUP#<agent_login_id > | SkillGroup | Implemented only for UCCE | |
Get Supervisor List | supervisor_list | GETSUPERVISOR#<agent_login_id > | SupervisorList | Implemented only for UCCE | |
Get Agent Extension | agent_extension | GETAGENTEXTENSION #<agent_login_id > | <F_Number> | AgentExtension | Implemented only for UCCE |
Supervisor Commands
Input Message | Category | Message Type | Message Parameters | Expected Output | Comments |
---|---|---|---|---|---|
Get Queue Info | supervisor_queue_info | getqueuelist#<agent_login_Id> | QueueInfo | ||
Silent Monitor (Supervisor Function) | supervisor_dialog | silentmonitor#<agent_login_Id> | <Agent_Extension> | On Supervisor On Agent | |
End Silent Monitor (Supervisor Function) | supervisor_dialog | endsilentmonitor#<agent_login_Id> | <Dialog_ID> | Inbound Call | |
Drop Participant (Supervisor Function) | supervisor_dialog | dropparticipant#<agent_login_Id> | <Agent_Extension>,<Dialog_ID> | ||
Get Team Users (Supervisor Function) | supervisor_team | getteamusers#<agent_login_Id> |
| Get Team User | 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 | getteamuserstate#<agent_login_Id> | <Team_Agent_LoginID> | Not implemented in client yet | |
Make a Barge Call | agent_call | bargein#<agent_login_Id> | <Team_Agent_Extension>,<Dialog_ID> | Inbound Call | |
Agent Logout | agent_state | Logout#<agent_login_Id> | Agent State | ||
Make agent not ready | agent_state | MakeNotReady#<agent_login_Id> | Agent State |
Admin Commands
Input Message | Category | Message Type | Message Parameters | Expected Output | Comments |
---|---|---|---|---|---|
Get Team and Global Phonebooks | phonebook | GetPhonebooks#<agent_login_id> | Phonebooks | ||
Get Contacts of a Phonebook | contacts | GetPhonebookContacts#<agent_login_id> | <PhonebookID> | Contacts | |
Get Team Phonebooks | phonebook |
| <TeamID> | TeamPhonebooks |
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 | ||
status | IN_SERVICE | OUT_OF_SERVICE |
SUBSCRIPTION_FAILED
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | Error |
Connect Status
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | ConnectStatus | ||
status | ConnectSuccess |
Agent Info
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | AgentInfo | ||
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 | |||
State | Agent state | From one of the following agent states: UNKNOWN, | ||
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. | |
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. | |
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 | ||
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 | ||
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 | ||
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 | ||
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 | ||
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 | ||
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 | ||
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 | ||
users | List of login agents |
Get Team User
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | Team Agents | ||
users | List of team user |
Get Queue List
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | Queue Stats | ||
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 |
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 | ||
skills | List of all skillGroups |
Get Supervisor List
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | supervisors | ||
supervisors | List of all supervisors |
Get Agent Extension
Attribute | Value | Description | Sample Output |
---|---|---|---|
type | agentExtension | ||
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 | The request failed due to lack of system resources (no specific details available) | Ref: http://www.cisco.com/en/US/docs/voice_ip_comm/cust_contact/contact_center/crs/express_10_0/programming/guide/UCCX_BK_C239BA3D_00_cti-protocol-developer-guide_chapter_01010.html | |
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 Configuration update in Siebel / Finesse is required to match Agent definition (ID/Pwd). Driver/client app should show 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 When Requester gets no response from Finesse GC tries to establish connection with the secondary Finesse | 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 Timeout exception on connecting to Finesse via Requester After 2 unsuccessful retries, GC tries to establish connection with secondary Finesse | 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 |