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.
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.
Agent desktop application can perform the following operations:
- File upload (two-step process):
- 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.
- 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.
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);
Below is the description of input parameters which must be provided in the “file-uploaded” notice request to Chat Server.
|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):|
|file-document-id||Yes only for file-source=“ucs"||Document Id in UCS.|
||Optional||Values used by Genesys Interaction Workspace:
|<any additional parameters>||Optional||Could be used by application logic.|
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);