Product: B2C Service

In today’s digital age, chatting has become the go-to medium for organisations to offer instant support to their customers. Many businesses have integrated chat functionality into their websites and mobile apps to allow customers to communicate efficiently with their support agents using a rich set of Chat Rest API. One of the most critical features of chat support is the ability to send and receive attachments. Sharing attachments during a chat session can be helpful in many scenarios. For example, a customer might need to send a screenshot of an error message they are experiencing, or a support agent might need to send a user manual to help a customer troubleshoot an issue.

The general question we often hear from our customers and system integrators is, ‘How do I get the functionality related to exchange of attachment working via the Chat Rest API?’. In this blog post, we will be outlining the implementation details on how agents and customers can send and receive attachments during a chat session invoked by chat Rest API in Oracle B2C Service cloud.

Sending Attachments from Agent end

To send an attachment during a chat session, the agent can click on the attachment icon in the chat window. This will open a file explorer where the agent can select the file they want to send. Alternatively Agent can drag and drop the attachment in the chat window. Once the file is selected/added, it will be uploaded to the server, and a link to the file will be sent to the customer. The customer can then click on the link to download the file.

Steps to enable send attachment feature at the Agent end:

  • Under Configuration Settings, “OIT_CORS_ALLOWLIST” config should be updated to either of the following values: .*, or “<your_domain.com>”
  • Establish a chat session:

Request URL: https://<sitename>.custhelp.com/services/rest/crossChannelServices/latest/establishSessions

Method: POST

Authorization: Basic <Base64(username:password)>

Request Body: {“sessionInformation”: “{\”question\” : \”sample text\”,\”auxiliaryData\” : {\”CONSUMER_CAN_RECEIVE_FILE_ATTACHMENTS\” : true}}”}

Note: “CONSUMER_CAN_RECEIVE_FILE_ATTACHMENTS” config verb set to true enables Attachment Icon at the Agent chat sidebar. On establishing session, Session token and chat server details will be obtained as response. 

Attachment Icon

  • Create chat Engagement session:

Request URL: https://<chat domain name>.rightnowtech.com/engagement/api/consumer/<sitename>/v1/requestEngagement?pool=<pool id>

Method: POST

Authorization: Bearer <chat session token>

  • Attach & Send Attachment from Agent Console:

Agents can attach and send attachments using the file upload icon available in the chat window. Once the Agent shares the attachments, end user can access the attachment related information in “Get Messages” API call,

Request URL: https://<chat domain name>.rightnowtech.com/engagement/api/consumer/<sitename>/v1/getMessages?pool=<pool id>

Method: POST

Request Header:

SessionId: <session id obtained while creating chat session>

Sample Response:

{

“status”: “RECEIVED”,

“engagementId”: <Engagement ID obtained while creating engagement>,

“localFileName”: <LocalFileName>,

“userFileName”: <UserFileName>,

“contentType”: <FileType>,

“fileSize”: <FileSize>,

“messageName”: “RNEngagementFileAttachmentMessage”,

“createdTime”: <File Uploaded TimeStamp>,

“sequenceNumber”:<Sequence Number>,

“sequenceNumberString”: <Sequence Number in string format>,

“engagementIdString”: <Engagement ID in string format>,

“fileSizeString”: <File Size in string format>

}

  • Access the attachment from client end:

In order to access the attachment from the client end, an URL needs to be built with the received response in the following format: https://<sitename>.widget.custhelp.com/ci/oit/getTempFile?contentType=<contentType>&createdTime=<createdTime>&fileSize=<FileSize>&localFileName=<LocalFileName>&userFileName=<UserFileName>

Request Header:

Accept: application/json

Accept-Encoding: gzip, deflate, br

origin: https://<sitename>.custhelp.com

On accessing the above link attachments can be downloaded.

Sending Attachments from Customer end

Similarly, customers may also need to send attachments to support agents during a chat session. For instance, a customer might need to send a screenshot of an issue they are experiencing. To receive an attachment, the agent needs to make sure that the chat application supports attachments. If the application does, then the customer can send the attachment by clicking on the attachment icon and selecting the file they want to send. Once the file is uploaded, the link to the file will be sent to the agent, who can click on the link to download the file.

  • File attachment upload notification:

Notifies Agent that file attachment upload has started

Request URL:  https://<domain from establish session>/engagement/api/consumer/<siteName>/v1/fileAttachmentUploadNotification?pool=<pool>

Request Body: {“clientRequestTime”: <currentdatetime>,”engagementId”: <engagementid from request engagement api>}

Request Header: SessionId: <sessionid from request engagement api>

  • File upload (OIT): 

Upload file to OSvC

Request URL: https://<sitename>.widget.custhelp.com/ci/oit/fileUpload

File should be uploaded as form data

Request Headers: 

(“Content-Type”,<filetype>);

(“name”, “file”);

(“filename”, <filename>);

Sample Response:

{

 “name”: <userfilename>,

“type”: “image/png”,

“tmp_name”: <tempfilename>,

“error”: 0,

“size”: <filesize> 

}

  • File attachment upload:

Notifies Agent on upload completion

Request URL: https://<domain>/engagement/api/consumer/<siteName>/v1/fileAttachmentUpload?pool=<pool>

Request Payload: Request payload will be based on the values received from file upload response.

{

“engagementId”: <engagemnetid from request engagement api>,

“status”: “RECEIVED”,

“localFileName”: <tempfilename>,

“userFileName”: <userfilename>,

“contentType”: <type>,

“clientRequestTime”: <currentdatetime>,

“fileSize”: <filesize>

}

  • Agent receives a file download link, on click of the link file gets downloaded and becomes accessible to chat Agent.

  • Once the chat is concluded by Agent/End user, the file attachment gets added to the incident associated with the chat as an attachment.

Sharing Inline images in Chat

Customers can also upload the images to their cloud storage locations and render the image links in chat as inline image both at Agent and end user end. 

To view images as inline in chat at the end user end, following attachment download URL could be used to render it as an inline image with img src data tag.

To view images as inline in chat at the agent end, Rich Text message could be enabled and could specify the image source url in the chat message with the Send Message API call as shown below.

Request URL: https://<chat domain name>.rightnowtech.com/engagement/api/consumer/<sitename>/v1/postMessage

Request Body:

{

“body”: “<div><span style=’display: none;’></span><img src=<image url> style=’display: block;max-width:200px;max-height:200px;width: auto;height: auto;’></div>”,

“richText”: 1

}

Chat Rest APIs provides details to create and manage chat engagements, providing a detailed description on each of the REST API. 

Conclusion

In conclusion, the ability to send and receive attachments in chat via the Chat Rest API brings about functional parity with B2C Service chat client. It can provide the same consistent experience that is available as standard Chat client, allowing customer & agent to exhange images/attachment to resolve complex issues more quickly and efficiently. Organizations that incorporate this feature into their chat platforms would to provide a better customer experience, which can ultimately lead to increased customer satisfaction and loyalty.