File Transfer API for Agent Desktop

The page describes how to implement file transfer (uploading and downloading) in custom agent desktop application using Platform SDK (supported from version 8.5.201.00). For high-level overview of file transfer in Chat Solution please refer to File Transfer in Chat Solutions.

Overview

It is important to understand the following general concepts about file transfer in Chat Solution:

• File storage is independent of Chat Server. Even though only Universal Contact Server (UCS) is currently supported by Genesys components (GMS, Interaction Workspace) as a file storage, other file storage may be used (ensuring that every Chat Server client could operate with the storage).
• Neither Chat Server nor UCS impose any restrictions on files transferred by agent applications (contrary to a customer-faced applications like GMS), therefore performance, network load, security and other aspects should be carefully planned (for example, large files or executables). Genesys Interaction Workspace has a special configuration for agent-initiated file uploads.
• Security protection should be provided by a third-party system as neither Chat Server nor UCS perform antivirus or other security checks of transferred files.

Protocol Description

Agent desktop application can perform the following operations:

• File upload (two-step process):
  1. An application uploads a file to the storage (UCS). A file stored in UCS is referred to as document and is given a unique identifier document-id.
  2. The document is attached to a chat session by sending a special notice (“file-uploaded”) and is then made available for chat participants to download. Chat Server assigns another identifier file-id for the purpose of identifying the file in chat session.
• Whenever the application receives the “file-uploaded” notice in chat session (from any participant), it:
  • Displays (to the agent) the information about the file such as the file name and file size as well as any custom additional information, in the event/notice.
  • Downloads a file from UCS by using document-id (for example, when the agent clicks on the file pictogram).

In code samples, it is assumed that connection objects to UCS and Chat Server are initialized with the proper connection parameters, and that Chat Server basic protocol user has registered and joined the session.

File Upload

The following code snippet demonstrates how to upload a file:

// Prepare connections
BasicChatProtocol chatConnection = ...;
UniversalContactServerProtocol ucsConnection = ...;

// Uploading file into UCS
RequestAddDocument docReq = RequestAddDocument.Create();
// mime-type is mandatory, however not verified by UCS or Chat Server.
docReq.MimeType = "application/octet-stream";
docReq.Content = File.ReadAllBytes("C:\\myfile.txt");
docReq.TheName = "myfile.txt";
docReq.TheSize = docReq.Content.Length;
IMessage addDocReply = ucsConnection.Request(docReq);
EventAddDocument addDocEvent = addDocReply as EventAddDocument;
// Sending notification in chat session
RequestNotify fileReq = RequestNotify.Create();
fileReq.SessionId = ...;
fileReq.NoticeText = NoticeText.Create(NoticeType.SystemCommand, "file-uploaded");
fileReq.UserData = new KeyValueCollection();
fileReq.UserData.Add("file-name", docReq.TheName); // mandatory
fileReq.UserData.Add("file-size", docReq.TheSize); // mandatory
fileReq.UserData.Add("file-source", "ucs"); // mandatory
fileReq.UserData.Add("file-document-id", addDocEvent.DocumentId); // mandatory for UCS
fileReq.UserData.Add("file-upload-type", "file-system"); // optional
fileReq.UserData.Add("file-description", "Sample text file.");  // optional
IMessage fileUploadedReply = chatConnection.Request(fileReq);

Input Parameters

Below is the description of input parameters which must be provided in the “file-uploaded” notice request to Chat Server.

Name	Mandatory	Description
file-name	Yes	File name including extension.
file-size	Yes	File size in bytes.
file-source	Yes	File storage type. Currently supported values by Genesys Solution (but not limited by Chat Server itself): “ucs” – Universal Contact Server
file-document-id	Yes only for file-source=“ucs"	Document Id in UCS.
file-upload-type	Optional	Values used by Genesys Interaction Workspace: “file-system” (Uploaded from file system) “standard-response” (selected from standard responses)
<any additional parameters>	Optional	Could be used by application logic.

File Download

The following code snippet demonstrates how to download file:

// Prepare connections
UniversalContactServerProtocol ucsConnection = ...;

// Download file from UCS
RequestGetDocument docReq = RequestGetDocument.Create();
docReq.DocumentId = ...; // obtain from chat transcript event userdata
IMessage getDocReply = ucsConnection.Request(docReq);

// Saving file in filesystem
EventGetDocument getDocEvent = getDocReply as EventGetDocument;
string filePath = Path.Combine("C:\\", getDocEvent.TheName);
File.WriteAllBytes(filePath, getDocEvent.Content);