Availability, notification and reporting Management

"Availability, notification and reporting Management" Javascript API:

	  This API allows to "log in" an Helper, control his availability status and
	  receive Pending Notifications, issued when a Client (a.k.a. Helpee) requests
	  a Contact with a Widget this helper is associated with.
	  

	  It also allows to respond to the Notification (accept / deny). A positive
	  response triggers the start of the WebChat session, that is notified to the
	  Sparkom Helper API.
	  

	  It can then, depending on the Helper Webchat Mode set, either autonomously
	  open an Helper Webchat popup, or invoke a Callback function (the API user
	  has the responsibility to open the Helper Webchat window).
	  

	  When the Helper Webchat signals it, a "Create Ticket" notification is issued
	  by the API with the Session Details, to help interface with ticket-based
	  customer interaction systems.
  

Login/Logout and Callbacks

		  SparkomAvailabilityApi.corpoLogin(corpoId, apiKey, emailLogin)
	  
It is Mandatory to invoke this method prior to any other API method.

It sets global parameters used for all other methods.

A single helper should login and set its Available status from one place only.

Note: Rather than these authentication parameters, it is possible to use the

SparkomAvailabilityApi.directLogin(emailLogin, password); method instead.

		  SparkomAvailabilityApi.logout()
	  
An invocation of this method clears all previously set authentication parameters
and stops all API activity.

		  SparkomAvailabilityApi.setAvailabilityCallback(callbackFunction)
	  
The registered callbackFunction will be invoked when the Availability Status changes.

This status will be detected and refreshed only after startAsAvailable() or startAsObserver() has been called.

It will be invoked aysnchronously with a single parameter: 

"isAvailable" that may take 3 values: true, false, null or any other value [Unknown]

		  SparkomAvailabilityApi.setErrorCallback(callbackFunction)
	  
The registered callbackFunction will be invoked when an Error occurs in the periodic refresh initiated by startAsAvailable() or startAsObserver().

It will also be invoked when an error occurs with other commands that take an Error Callback as argument,
if this argument is not supplied (it's a Default ErrorCallback indeed).

It will be invoked aysnchronously with a single parameter:

"errorMessage" that gives an indication about the error.

Control of Availability Status

		  SparkomAvailabilityApi.startAsAvailable(notifRequestCallback)
	  
When this method is invoked, the Api code sets this Helper "Available" and notifies the Server.

It starts a periodic refresh of this Available condition (the servers would time out, otherwise),
and retrieve at the same time the list of "Pending Notifications".

A "Pending Notification" represents a Client (Helpee) request on a given Widget, that is not yet answered.

All Helpers associated with this Widget are notified and may reply, to accept or deny the request.

Notifications are delivered asynchronously to the notifRequestCallback function given as argument.

This callback function receives one argument: An Array of Pending Notifications,
that may be empty.

Each Pending Notification contains the following fields:

 - "requestId": Identifies the Request (needed for the accept/deny API methods).

 - "requestDurationSecs": Number of Seconds since the request was initiated.

 - "widgetId": The ID of the Widget used for the Request.

 - "widgetDisplayName": The Display Name of this Widget.

 - "helpeeDisplayName": Identifier value given by the Helpee at the request.

 - "helpeeDemand": Description text optionnally provided by the Helpee.

 - "requestOrigin": "wchat"

 The callback function is called repeatedly, at each Server response.

It always contains the full list of Pending Notifications.

Notifications can be removed either at Helpee request (cancelling the demand), because
another helper accepted it, or because it was timeouted.

		  SparkomAvailabilityApi.startAsObserver(notifRequestCallback)
	  
When this method is invoked, the Api code starts a periodic refresh of the Available/Unavailable status of this Helper,
and of his "Pending Notifications".

An Observer does not set the Status of the Helper to "Available".

He should not attempt to accept / deny these notifications.

The callback function may be undefined (the Availability Status is alvays delivered
through the function registered with setAvailabilityCallback().

If not, it receives the same information (an Array of Pending Notifications) as in the Available case above.

		  SparkomAvailabilityApi.stop()
	  
When this method is invoked, the Api code sets this Helper "Unavailable" and notifies the Server.

It stops any periodic operation.

		  SparkomAvailabilityApi.isAvailable()
	  
This method returns the last known Availability Status of this Helper: true, false, or
Any Other Value [unknown]. It does NOT trigger a server query.

Accept / Deny Pending Request Notifications

		  SparkomAvailabilityApi.acceptRequest(requestId, resultCallback, errorCallback)
	  
To be invoked when the Helper accepts the Request, identified by requestId.

This terminates the "Pending Notification", that will disappear from the list
returned to the notifRequestCallback, and allows the setup of the WebChat session
to proceed.

The Helpee side is notified of the Acceptation, and waits for the opening of the
Helper side WebChat window.

According to the Mode set with setOpenHelperChat(), this API may open a Chat
window autonomously, or invoke the specified openHelperChat callback.

This method invokes asynchronously the given "resultCallback" (if present) in case of success.

It invokes the "errorCallback" (if present -- otherwise the function registered
by setErrorCallback(), if present, will be used) with an Error Message.

		  SparkomAvailabilityApi.denyRequest(requestId, resultCallback, errorCallback)
	  
To be invoked when the Helper Rejects the Request, identified by requestId.

This terminates the "Pending Notification", that will disappear from his own list
returned to the notifRequestCallback. The Helpee will be notified of the Denial
only after all Available Helpers have Denied the request.

This method invokes asynchronously the given "resultCallback" (if present), in case of success.

It invokes the "errorCallback" (if present -- otherwise the function registered
by setErrorCallback(), if present, will be used) with an Error Message.

Utility functions

		  SparkomAvailabilityApi.listWidgets(resultCallback, errorCallback)
	  
This Utility function queries the Server and returns the list of Widgets associated
with this Helper.

When this Helper is Available, all these Widgets will therefore
be Available.

This method invokes asynchronously the given "resultCallback" (if present) with
an array of "Widget"s, in case of success.

Each "Widget" contains the following fields:

 - "widgetId": Unique Identifier

 - "widgetDisplayName": Display Name of the widget.

It invokes the "errorCallback" (if present -- otherwise the function registered
by setErrorCallback(), if present, will be used) with an Error Message, in case of error.

Session Callbacks

		  SparkomAvailabilityApi.setOpenHelperChat(mode, param)
	  
Specifies what happens when the Helper has accepted a Webchat request.

With mode="auto", the API opens by itself a new Webchat window.

By default, the standard Sparkom Webchat is opened (/panserver3/wchat/sparkom/wchat.html).

The (optional) "param" allows to specify a Custom Webchat URL.

With mode="callback", the API will invoke the function specified as "param".

The [Required] "param" is the callback function, it will receive as parameter a
single Javascript objects with the following fields:
urlParams: the Query String to append to the desired Helper Webchat URL (does not include the ?).
csid: Identifier for the Webchat Session
helpeeDisplayName: The Helpee Identification, entered by the Helpee (clientId).
widgetId: The ID of the Widget used for starting this Session.
widgetDisplayName: The DisplayName of the Widget.
helperDisplayName: The DisplayName shown to the Helpee.
trustcircle: true if this is a TrustCircle Widget.

		  SparkomAvailabilityApi.setOpenClientCallback(openClientCallback)
	  
The "openClientCallback" function will be invoked when the Helper has accepted
a request for a Widget that is NOT a Trust Circle one, and a Webchat starts.
It will receive as Parameters:

clientid: the Helpee Identification, entered by the Helpee (helpee DisplayName).
csid: Identifier for the Webchat Session

		  SparkomAvailabilityApi.setOpenChatWinParams(winParams)
	  
Only when the openChat Mode has been set to "auto" with setOpenHelperChat(), the
API will open the Helper WebChat popup window. This method allows to specify the
Javascript window parameters (otherwise the default ones will be used).

		  SparkomAvailabilityApi.setCreateTicketCallback(createTicketCallback)
	  
The "createTicketCallback" function will be invoked when the Helper clicks on
the "Create Ticket" button at session End.
It will receive as Parameter a JS Object with the following fields:

csid: Identifier for the Webchat Session
clientid: the Helpee Identification, entered by the Helpee (helpee DisplayName).
session_details_url: URL that links to the Session Details page in the Sparkom application (/rss2)
helper_notes: Notes taken by the Helper during the Session
session_transcript: HTML Transcript of the Session lines.

Retrieval of Session Details

		  SparkomAvailabilityApi.getSessionDetails(csid,resultCallback, errorCallback)
	  
When this method is invoked, the Api code retrieves from the Server the detailed informations
on the session identified by the Identifier 'csid'.

In case of success, it invokes the resultCallback with two arguments: 'wcSession' and 'sxrSession'

- wcSession: This Object contains information on the WebChat part of the session.

  .csid: Identifier of the Session

  .startTime: Date and Time (Locale:FRANCE) of the Session Initiation

  .endTime: Date and Time (Locale:FRANCE) of the Session Termination

  .duration: Session Duration in hh:mm:ss format

  .status: Session Status. The Session Information is complete only when this

           field has the value "TERMINATED".

  .helpeeDisplayName: Identification of the Helpee, who requested the session.

  .helperDisplayName: Helper, who answered the request.

  .initRequest: Text of the Initial Request by the Helpee

  .htmlTranscript: Transcript of the webchat exchange.

  .waitTime: Time in hh:mm:ss between Helpee Request and session acceptation.

  .widgetId: ID of the Widget Access Point used.

  .helperLoginId: ID of the Helper who accepted the Session.

- sxrSession: null if no Screen Sharing occured. Otherwise:

  .sxrid: Local Identifier of the Screen Sharing sub-session

  .status: Status of the Screen Sharing sub-session:

  	NOT_FINISHED - In progress or being setup

  	DENIED - All Helpers rejected or became Unavailable

  	CANCELLED - Cancelled by the Helpee

  	ERROR - An Error occurred

  	FINISHED - Screen-Sharing is terminated.

  .startTime: Date and Time of the Screen Sharing Start

  .endTime: Date and Time of the Screen Sharing Start

  .duration: Formatted duration (as a String)

  .waitTime: Formatted wait time (only available on instrumented Widgets)

  .accessWidget: Helper and Widget string

  .widgetId: The Widget used.

  .helpeeDisplayName: (when known)

  .proClientId: when applicable (Session paid by Codes)

  .crmClientName: Name of the Helpee as entered by the Helper in the application's mini-crm

  .sessionNotation: Numeric value of the Notation given be the Helpee (-1 if not available)

  .clientComments: Comments associated with this notation, when applicable.

  .prestaName: DisplayName of the Helper Account

  .distribHelperId: Distributor tag when applicable

  .scrm: Comments entered by the Helper in the application's mini-crm

The errorCallback may not be supplied - in this case the global error callback would be
invoked in case of error.