Bar API Integration¶

The WebCaller API is a functionality of the FS system, used for agent login, status setting, and call control, which can be integrated into third-party applications.

Overview¶

The Bar API is an HTTP interface that allows controlling FS. Integration into a third-party application assumes the use of custom client-side logic and the use of HTTP REST/JSON services, the client technology can be any (web, thick application, mobile application). The REST/JSON API is exposed by the ReactClient module.

Architecture¶

Example of the arrangement of a web client application and its connection to the server side.

Types of API¶

The client application has the following APIs available:

BarModel – JSON API for obtaining status and workplace dictionaries
BarStatus – JSON API for determining the agent’s workplace status and CTI status
BaAction – JSON API for triggering workplace status change actions and CTI commands
Call – text API for invoking call-related functions
Web – text API for invoking various FS functions

Configuration on the FS side¶

To use the application, it needs to be configured correctly:

BarAction Permissions
- AllowRead level only allows monitoring (API “BarStatus” and “BarModel”)
- AllowWrite level additionally allows active control (API “BaAction”)
StatusChange permission with AllowRead level is required for agent status changes and login
Permission to make status changes from the workplace in WebClient mode (in the agent’s Seating settings)
For the Web API, permissions specific to the given function may be required

Communication Protocol¶

Common HTTP GET requests are used for the given URL with query-string parameters. Either JSON formatted data (application/json) or plain text response OK/ERROR (text/plain) is returned. In some cases, the HTTP POST variant of the request can be used to deliver larger amounts of data. Authentication is set the same as in ReactClient. The bar cannot be used without authentication.

OpenAPI Interface Definition

The implementer can use the exposed OpenAPI (Swagger) interface definition, which is available at the URL ReactClient: http:/server/swagger/index.html

A public version is also exposed on the test system: https://test.frontstage.online/fake/swagger/index.html

Note

The exposure of Swagger must be enabled in appsettings.json with the EnableSwagger parameter.

BarModel¶

URL ReactClient: http:/server/api/bar/model?Seq=n

The service has a single parameter, which is the sequence number. This prevents the use of a “cached” page in the browser and proxy, with another type of client it may not need to be changed and can be constant. The system does not check the number in any way and returns it unchanged in the “Sequence” field in the response.

BarModelPoco Structure¶

| public class BarModelPoco
| {
|     public List<string> statusTexts { get; set; }
|     public List<Guid> statusIds { get; set; }
|     public List<string> statusClasses { get; set; }
|     public List<string> workplaceTexts { get; set; }
|     public List<Guid> workplaceIds { get; set; }
|     public List<string> workplaceClasses { get; set; }
|     public List<string> poolTexts { get; set; }
|     public List<int> poolIds { get; set; }
|     public List<string> poolClasses { get; set; }
|     public int? Sequence { get; set; }
| }

Response Parameters¶

The structure always contains triplets of fields that have the same length and the related values Text-Id-Class are located at the same indexes.

statusTexts – array of status names in which the agent can be
statusIds – array of status ids in which the agent can be
statusClasses – array of texts in the form “statusXXX“, where XXX is the Activity value associated with the given status; possible values:
- “statusReady” – the agent is ready
- “statusPostCall” – the agent is processing information about the completed call
- “statusPause” – the agent is on a break
- “statusLogoff” – the agent is logged off
workplaceTexts – array of workplace names to which the agent can log in
workplaceIds – array of workplace ids to which the agent can log in
workplaceClasses – array of texts in the form “workplaceYYY”, where YYY indicates the availability/occupancy of the workplace; possible values:
- “workplaceFree” – the workplace is available and allows login; the option should be active
- “workplaceUsed” – the workplace is already occupied by someone else; the option should not be active
- “workplaceError” – the workplace has a malfunction, temporarily cannot log in; the option should not be active
poolTexts – array of workplace pool names to which the agent can log in
poolIds – array of workplace pool ids to which the agent can log in
poolClasses – array of texts in the form “poolYYY”, where YYY indicates the availability/occupancy of the workplace pool; possible values:
- “poolFree” – the pool contains some free workplaces; the option should be active
- “poolBusy” – there are no free workplaces in the pool; the option should not be active
Sequence – returning the input parameter Seq

Example response¶

{

    "statusTexts": [
        "Ready",
        "Calls only",
        "Fill in",
        "Completing",
        "Not ready",
        "Backoffice",
        "Log off",
        "Vacation"

    ],

    "statusIds": [
        "60fba1e2-08f0-4129-97b3-3041e9ee27b8",
        "6dcf4408-e640-40a1-9f95-5380eae64f03",
        "00d95aa0-3fb5-416e-b230-561a10199c37",
        "fd9b3ae4-2180-42f7-9614-ddb5a463359c",
        "78028459-ca9e-45de-a574-5005f96774bc",
        "0ccc24a1-669e-4ece-ba12-3b1fca7448bb",
        "e8ad6b58-b5cc-478f-9bae-d6c8d8dc1aae",
        "27f80724-aa7b-4a21-bfa6-052e33a8a99b"
    ],

    "statusClasses": [
        "statusReady",
        "statusReady",
        "statusPostCall",
        "statusPostCall",
        "statusPause",
        "statusPause",
        "statusLogoff",
        "statusLogoff"
    ],

    "workplaceTexts": [
        "W160",
        "W161",
        "W162",
        "W165",
        "W166",
        "W251"
    ],

    "workplaceIds": [
        "92a4fe39-d071-4040-a8dc-e21426ad8b08",
        "aded24a5-8ca1-4326-808b-a97c8e852a25",
        "d542c40b-9114-4dc0-b412-0b30235bc023",
        "68d83be0-bf79-44d7-9260-b4c44999c314",
        "3db54655-eabf-4767-bfda-be9390fc1a77",
        "313617a1-2d94-431c-8d97-714c22e4328d"
    ],

    "workplaceClasses": [
        "workplaceUsed",
        "workplaceFree",
        "workplaceFree",
        "workplaceFree",
        "workplaceFree",
        "workplaceFree"
    ],
    "poolTexts": [
        "WORKPLACE"
    ],
    "poolIds": [
        1
    ],
    "poolClasses": [
        "poolFree"
    ],
    "Sequence": 12548
}

BarStatus¶

URL ReactClient: http:/server/api/bar/status?Seq=nnn

The service has a single parameter, which is the sequence number. This prevents the use of a “cached” page in the browser and proxy, with another type of client it may not need to be changed and can be constant. The system does not check the number in any way and returns it unchanged in the “Sequence” field in the response. Visualization parameters should be mapped directly to the states and values of the controls. Integration parameters are intended for use by third-party code.

BarStatusPoco Structure¶

| public class BarStatusPoco
| {
|     #region JSON data fields for IWorkplaceData
|     public string pbxCallId { get; set; }
|     public int callDirection { get; set; }
|     public int warnLevel { get; set; }
|     public string connectedNumber { get; set; }
|     public int startCall { get; set; }
|     public int holdCall { get; set; }
|     public int endCall { get; set; }
|     public bool durationRun { get; set; }
|     public string transferNumber { get; set; }
|     public int consultCall { get; set; }
|     public int transferCall { get; set; }
|     public int retrieveCall { get; set; }
|     public int conference { get; set; }
|     public int workplaceStatus { get; set; }
|     public int cstaState { get; set; }
|     public string durationText { get; set; }
|     public int duration { get; set; }
|     public int progress { get; set; }
|     public int progressType { get; set; }
|     public int showCallResult { get; set; }
|     #endregion
|     #region JSON data fields for IAgentData
|     public string workplaceText { get; set; }
|     public string agentText { get; set; }
|     public string teamText { get; set; }
|     public int agentStatus { get; set; }
|     public int loggedStatus { get; set; }
|     public string statusId { get; set; }
|     #endregion
|     #region JSON data fields for ICallInfoData
|     public string callId { get; set; }
|     public string workplaceNumber { get; set; }
|     public string workplaceId { get; set; }
|     public string agentId { get; set; }
|     public string projectId { get; set; }
|     public string languageId { get; set; }
|     public string outBoundListId { get; set; }
|     public string contactId { get; set; }
|     public string callType { get; set; }
|     public int ispredictive { get; set; }
|     public string callTypeText { get; set; }
|     public string callInfoText { get; set; }
|     public string remotePartyNumber { get; set; }
|     public string projectName { get; set; }
|     public string languageName { get; set; }
|     public string displayName { get; set; }
|     public string contactName { get; set; }
|     public string pilotName { get; set; }
|     public string redirector { get; set; }
|     public DateTime referenceTime { get; set; }
|     public string outBoundListName { get; set; }
|     #endregion
|     #region JSON data fields for IScenarioListData
|     public ScenarioInfoData[] scenarioList { get; set; }
|     public string scenarioCallId { get; set; }
|     public string scenarioCallType { get; set; }
|     #endregion
|     public int? Sequence { get; set; }
| }

Workplace Parameters IWorkplaceData¶

pbxCallId – a string indicator of the call in the telephone exchange; the application should treat it as a literal and not interpret it; this field should not be used by the application outside the context of the browser
callDirection – call direction
- 0 = outgoing
- 1 = incoming
warnLevel – a number from 0 to 3 indicating the exceeding of the call duration preset in the application for the given project; possible interpretation is, for example, a color change to notify the agent of a too long call
connectedNumber – label/field for the connected party’s phone number
startCall – button to start the call
- 0 = disable function (grayed out) – the branch does not allow these actions because a call is in progress (Disabled)
- 1 = enable function to start a direct call (MakeCall) – the branch is idle (Enabled)
- 2 = enable function to answer the call (AnswerCall) – the call is ringing (Alert)
- 3 = enable function to accept the outgoing project call (Offer)
- 4 = enable function to accept the project preview (PreCall)
holdCall – button to put the call on hold
- 0 = disable function (grayed out)
- 1 = enable function
endCall – button to end the call
- 0 = disable function (grayed out)
- 1 = enable function
durationRun – indication that the call duration counter should run
transferNumber – label/field for the phone number to which the call is being transferred
consultCall – button to start the transfer
- 0 = disable function (grayed out)
- 1 = enable function
transferCall – button to complete the transfer
- 0 = disable function (grayed out)
- 1 = enable function
retrieveCall – button to return to the caller without completing the transfer
- 0 = disable function (grayed out)
- 1 = enable function
conference – button to start the conference
- 0 = disable function (grayed out)
- 1 = enable function
wrkplaceStatus – indication of workplace status
- 0 = workplace is not active
- 1 = workplace is active and allows calls
- 2 = workplace is active but does not allow calls
cstaSate – CSTA call status (extended numeric): NoCall = 0, Alerting = 1, AlertingWaiting = 2, Answered = 3, AnsweredToHold = 4, AnsweredToConference = 5, IncomingHold = 6, IncomingConference = 7, IncomingDisconnected = 8, IncomingRelease = 9, DialTone = 10, Dialing = 11, Dialed = 12, Ringing = 13, RingingWaiting = 14, Connected = 15, ConnectedToHold = 16, ConnectedToConference = 17, OutgoingHold = 18, OutgoingConference = 19, OutgoingDisconnected = 20, OutgoingRelease = 21, Transferring = 22, ConnectedToIntervention = 23
durationText – string indicating the call duration
duration – duration of the state in seconds as a number
progress – a number from 0 to 100 indicating the progress of the activity in percent (e.g., ringing time)
progressType – type of ongoing activity
- 0 = no activity
- 1 = call
- 2 = ringing
- 3 = outgoing call offer

Agent Parameters IAgentData¶

workplaceText – label indicating the name of the workplace
agentText – label indicating the agent’s name
teamText – label indicating the name of the team to which the agent belongs
agentStatus – agent status button; (value is an integer)
- 0 = disable function (grayed out)
- 1 = enable function
loggedStatus – status index used to display the current status (integer); status fields can be obtained from BarModel
statusId – agent status id

Call Information Parameters ICallInfoData¶

callId – a string of the unique call indicator; the application should treat it as a literal and not interpret it; serves as a linking key in the InboundCall or OutboundCall table (see callType parameter)
workplaceNumber – number of the workplace where the call is taking place
workplaceId – workplace identifier; the application should treat it as a literal and not interpret it; serves as a linking key in the Workplace table
agentId – agent identifier; the application should treat it as a literal and not interpret it; serves as a linking key in the Agent table
projectId – a string of the unique project indicator; the application should treat it as a literal and not interpret it; serves as a linking key in the Project table; text representation is in the projectName parameter
languageId – language identifier; the application should treat it as a literal and not interpret it; serves as a linking key in the Language table; text representation is in the languageName parameter
outBoundListId – campaign identifier; the application should treat it as a literal and not interpret it; serves as a linking key in the OutboundList table
contactId – contact identifier in the Contact table; the application can use it as a linking key; text representation is in the displayName parameter
callType – type of call from the contact center perspective
- Pilot – incoming project call managed by iCC
- Direct – incoming direct call not managed by iCC
- DialOut – outgoing project call managed by iCC
- Private – outgoing direct call not managed by iCC
ispredictive – indication of whether it is a predictive call
- 0 = no
- 1 = yes
callTypeText – type of call expressed in text for display in the application
callInfoText – field contains the results of IVR processing
remotePartyNumber – project party number as obtained when the call arrived; may differ for transferred and otherwise processed calls from connectedNumber
projectName – name of the call project
languageName – name of the call language
displayName – contact information for the call
pilotName – name of the entry through which the call came
redirector – number of the indirect entry through which the call came
referenceTime – reference time (UTC) of the call for the purposes of time counters
outBoundListName – name of the outbound call campaign

Call results details¶

showCallResult – indicates that the system is waiting for the outbound call result to be entered
- 0 = not waiting (Disabled)
- 1 = waiting (Enabled)
- 4 = call waiting to start during preview phase (PreCall)

User data parameters for the call IScenarioListData¶

scenarioCallId – ID of the call to which the data relates; the field is analogous to the callId field from the ICallInfoData set, but may be presented in different time intervals, depending on data display requirements
scenarioCallType – type of call to which the data relates; the field is analogous to the callType field from the ICallInfoData set, but may be presented in different time intervals, depending on data display requirements
scenarioList – array of records associated with the call, structure ScenarioInfoData

ScenarioInfoData Structure¶

| public class ScenarioInfoData
| {
|     public string id { get; set;}
|     public short activity { get; set; }
|     public string scenarioName { get; set; }
|     public string resultCreated { get; set; }
|     public string callerNumber { get; set; }
|     public string displayName { get; set; }
| }

id – identifier of the scenario (ScenarioId) or data set (ScenarioResultId)
activity – indication of the type of record and its status
- empty string – the record has no associated status, it can be a scenario with or without a data set
- PreFilled – the record has a data set that was created automatically and is editable
- Active – the record has a data set that is being edited
- Completed – the record has a data set and it is closed (cannot be edited)
- Canceled – the record has a data set and it is canceled (cannot be edited)
- Neglected – the record has a data set whose editing was not completed (cannot be edited)
scenarioName – name of the scenario for the data set (data schema)
resultCreated – time of data set creation, if the field is empty, it is a scenario that does not yet have a data set
callerNumber – number of the caller (counterparty) of the call that is directly associated with the data set
displayName – associated data from the data set, separated by commas; the order and type of data depends on the configuration of the scenario data set

Example data set¶

"scenarioList":[

| {"id":"a0cdbdff-3da8-e211-a546-f0def18b5d58",
| "activity":"Completed",
| "scenarioName":"IVR data",
| "resultCreated":"18. dubna 2013 17:38",
| "callerNumber":"512",
| "displayName":"52452563"},

| {"id":"c817394c-e816-47c6-a52a-4ef3028f2cde",
| "activity":"",
| "scenarioName":"Reklamace",
| "resultCreated":"",
| "callerNumber":null,
| "displayName":""}

],

| "scenarioCallId":"9ecdbdff-3da8-e211-a546-f0def18b5d58",
| "scenarioCallType":"PilotIn"

The first record of the array is a data set, created on 18.4.2013 17:38, with a single piece of data, namely “52452563”.

URL to open the record in ReactClient UI: http:/server/Pages/FormEditor.html?Id=a0cdbdff-3da8-e211-a546-f0def18b5d58

The second record is not a data set, a new data set according to this scenario can be created by opening the form.

URL to create a record in ReactClient UI: http:/server/Pages/FormEditor.html?ScenarioId=c817394c-e816-47c6-a52a-4ef3028f2cde

Complete data of the existing form can be obtained as JSON data.

URL to get the record in ReactClient as JSON data: http:/server/api/form/a0cdbdff-3da8-e211-a546-f0def18b5d58

BarAction¶

URL ReactClient: http:/server/api/bar/action?Cmd=ccc&Par=ppp&Seq=nnn

The service has three parameters: the command (Cmd) to be executed, the command parameter (Par), and the sequence number (Seq). The sequence number prevents the use of a “cached” page in the browser; with another type of client, it may not need to be changed and can be constant. The system does not check the number in any way and returns it unchanged in the response.

The response is the same as for BarStatus, reflecting the state after the command is executed, if the command is synchronous.

Agent status commands and their parameters¶

“Workplace” – one of the offered workplaces was selected, the parameter is the id (Guid) of this workplace (see workplaceIds in BarModel), the application is automatically WebClient
“Pool” – one of the offered workplace pools was selected, the parameter is the id (int) of this pool (see poolIds in BarModel), the application is automatically WebClient
“AgentStatus” – a new agent status was selected from the offered statuses, the parameter is the id of this status (see statusIds in BarModel), the application is automatically WebCaller

CTI commands and their parameters¶

“StartCall” – the button to start the call was pressed, the parameter is the called number (see the startCall and connectedNumber parameters in BarStatus)
- Example: http:/server/WebCaller/BarAction.aspx?Cmd=StartCall&Par=602330533
- Note: The behavior of the command can be changed by the configuration parameter “PrivateCallsOnWebAction”; if set, this function works for dialing the same as “PrivateCall” on the WebAction page, but without the possibility to add additional parameters.
“EndCall” – the button to end the call was pressed, the parameter is empty (see the endCall parameter in BarStatus.)
“ConsultCall” – the button to start the transfer was pressed, the parameter is the number to which the call is to be transferred (see the consultCall and transferNumber parameters in BarStatus)
“TransferCall” – the button to complete the transfer was pressed, the parameter is the number to which the call is to be transferred (see the transferCall and transferNumber parameters in BarStatus)
“RetrieveCall” – the button to cancel the transfer was pressed, the parameter is empty (see the retrieveCall parameter in BarStatus)

Call¶

URL ReactClient: http:/server/api/bar/call?Cmd=ccc&Par=ppp&Seq=nnn

The service is functionally identical to BarAction, but the return value is not a JSON structure; it is plain text, either “OK” or text starting with the word “ERROR”.

Web¶

URL ReactClient: http:/server/api/bar/web?Cmd=ccc&Par=ppp&Seq=nnn

The service has three parameters: the command (Cmd) to be executed, the command parameter (Par), and the sequence number (Seq). The sequence number prevents the use of a “cached” page in the browser; with another type of client, it may not need to be changed and can be constant. The system does not check the number in any way and returns it unchanged in the response. If additional parameters are used, they are specified analogously as a “query-string”, i.e., separated by the & character in the format parameter=value. The service can be used with both HTTP GET and HTTP POST.

The response varies depending on the command and can be either “OK” or text starting with the word “ERROR”.

Commands and their parameters¶

“PrivateCall” – initiating an immediate private outbound call. The agent for whom the call is being initiated must be logged in at the time; their status is not relevant for the function. The parameter (Par) is the target phone number. Additional parameters can also be specified – they are optional.
- AgentId – ID of the agent for whom the call is initiated; if not specified, the call will be initiated for the authenticated agent.
- ProjectId – ID of the project to which the call should be assigned for reporting purposes
- LanguageId – ID of the language to which the call should be assigned for reporting purposes
- OutboundListId – ID of the outbound campaign to which the call should be assigned for reporting purposes
- IssueId – ID of the issue to which the call should be assigned for reporting purposes
- ContactId – ID of the contact to which the call should be assigned for reporting purposes
- CallKey – external identifier (max. 48 characters) that is recorded in the OutboundCall table for the created private call
- Example: http:/server/api/bar/web?Cmd=PrivateCall&Par=602330533&Seq=12&OutboundListId=05396d15-2ae6-e511-87f7-9439e5913128&CallKey=MY4447(A)
„CallOrConsult“ – initiating a direct CTI call (similar to BarAction) or starting a transfer with consultation. The parameter (Par) is the target phone number.
- Example: http:/server/api/bar/web?Cmd=CallOrConsult&Par=602330533
- Note: The behavior of the command can be changed by the configuration parameter „PrivateCallsOnWebAction“; if set, this function works for dialing the same as „PrivateCall“
„CallOrBlind“ – initiating a direct CTI call (similar to BarAction) or performing a blind transfer. The parameter (Par) is the target phone number.
- Note: The behavior of the command CAN be changed by the configuration parameter „PrivateCallsOnWebAction“; if set, this function works for dialing the same as „PrivateCall“
„SetCallKey“ – associating an external CallKey identifier with an ongoing outbound (DialOut or Private) or inbound (PilotIn) call of the authenticated Agent. The parameter (Par) is the value of the CallKey identifier (max. 48 characters). If an empty value is used, the value in the OutboundCall.CallKey table is cleared (set to NULL).
- Example: http:/server/api/bar/web?Cmd=SetCallKey&Par=EXT-K-10454
„IvrFeedback“ – request to enable the IvrFeedBack flag for the given call
„ChangeMeta“ – changing the metadata of the current call and returning it to the queue for redistribution. The agent initiating the action must be logged in and have a project call; their status is not relevant for the function. The parameter (Par) is not used. To make an actual change, at least one additional parameter must be specified – they are optional.
- AgentId – ID of the agent to whom the call should be transferred as a „direct selection“ (predistributed).
- ProjectId – ID of the project to which the call should be transferred.
- LanguageId – ID of the language to which the call should be transferred.
- OutboundListId – ID of the outbound campaign to which the call should be transferred.
- Priority – number 0-100 indicating the new priority level of the call
- Example: http:/server/api/bar/web?Cmd=ChangeMeta& Seq=12&ProjectId=05396d15-2ae6-e511-87f7-9439e5913128&Priority=20
„ChangeProject“ – changing the project of the current call and returning it to the queue for redistribution. The agent initiating the action must be logged in and have a project call; their status is not relevant for the function. The parameter (Par) contains the ID of the project to which the call metadata should be changed.
- Example: http:/server/api/bar/web?Cmd=ChangeProject&Seq=12&Par=05396d15-2ae6-e511-87f7-9439e5913128
„ChangeLang“ – changing the language of the current call and returning it to the queue for redistribution. The agent initiating the action must be logged in and have a project call; their status is not relevant for the function. The parameter (Par) contains the ID of the language to which the call metadata should be changed.
- Example: http:/server/api/bar/web?Cmd=ChangeLang&Seq=12&Par=48396d15-2ae6-e511-87f7-9439e5913128
„ChangePriority“ – changing the priority of the current call and returning it to the queue for redistribution. The agent initiating the action must be logged in and have a project call; their status is not relevant for the function. The parameter (Par) contains the priority number (0…100) to which the call metadata should be changed.
- Example: http:/server/api/bar/web?Cmd=ChangePriority&Seq=12&Par=20
„ListenStart“ – starting the listening from the SRec module of the call (requires ListenProxy permission and ListenStartUrl configuration)
„ListenEnd“ – ending the listening from the SRec module of the call (requires ListenProxy permission and ListenEndUrl configuration)
„IntvListen“ – starting an intervention call in the listening stage to the given target branch (requires Intervention permission at AllowRead level), the parameter is the target branch number
„IntvWhisper“ – starting an intervention call in the whispering stage to the given target branch (requires Intervention permission at AllowWrite level), the parameter is the target branch number
„IntvListen“ – starting an intervention call in the connection stage to the given target branch (requires Intervention permission at AllowWrite level), the parameter is the target branch number