article by Frank Nimphius, August 2019
In a recent Oracle TechExchange article, Upload Documents in an Oracle Digital Assistant Conversation with Messengers like Facebook or the Oracle JavaScript Client SDK, I explained how to upload documents in a messenger client through Oracle Digital Assistant. In this article I now explain the opposite, which is how to download of documents like audio, video, image and document files within a bot conversation.
Basically, to download documents in Oracle Digital Assistant conversations, you have three implementation options available
- Using the System.CommonResponse component attachment response type, you navigate to a dialog flow state that returns the download URL along with the document type (audio, video, image, file) to the messenger client to download the content. The rendering of the document, whether it is in place within the messenger conversation, or in an external browser or webview window, is not in the control of Oracle Digital Assistant but the messenger used.
- Using a custom component, you use the JavaScript MessageModel object available in the Oracle custom component SDK. Using a custom component is what you would use if the document URL and type is accessed dynamically from a remote service call. The rendering location, in-place within the messenger client, or external in a web browser or webview, depends on the messenger client used. Oracle Digital Assistant , like any other chatbot too, does not control the messenger client.
- Using the System.CommonResponse component url action, you can redirect the user to an online source that is always opened in a separate browser tab, or in a webview on a mobile devices.
System.CommonResponse Component Attachment Type
The built-in component templates in Oracle Digital Assistant skill dialog flow builder contain a template that you can use to build a dialog flow state, which references the System.CommonResponse component configured with the attachment response.
For this, select the + Components button in the dialog flow builder and choose the User Interface option
Select the Common response – attachment menu item and choose the location where the new state should be added to using the Insert After select list. Optionally, remove component comments from the added state. I recommend you keep the comments if this is the first time you work with the System.CommonResponse component attachment response.
The image below shows two dialog flow states from the sample skill that you can download at the end of this article.
Both states have been created using the component templates. Only the type property and the attachmentUrl property were changed. At runtime, the sample skill provides you an option to select a document type to download.
Selecting an item in the list then navigates to a state within the dialog flow to download and display the attachment. Selecting the Globus (Video) menu item, shows the following content in the embedded skill tester.
The image below shows the same conversation using the Oracle JavaScript Client SDK that provides a messenger you can embed to your website or into your web application.
Unlike the embedded conversation tester in Oracle Digital Assistant, media types like audio and video are rendered as clickable URLs. The content then is rendered in a separate browser tab, or webview
Note that Oracle Digital Assistant does not have control over the messenger. It's the messenger that decides how to handle documents.
When you download and import the sample skill, and then look at the dialog flow's BotML code, you see that the URLs are read from an array also defined in the dialog flow. In a production environment you are more likely to use an implementation that reads the URLs from a REST services accessed through a custom component. The custom component can either save an array of document URLs along with their types in a context variable, or as shown next, use the custom component SDK's MessageModel to directly render the attachment.
Using Custom Components
Oracle built-in components and custom components share the same message model. The message model defines a metadata format that represents the Oracle Digital Assistant incoming and outgoing messages. The channel configuration takes the metadata messages and converts them to the payload format expected by the target messenger. Similar, wen an incoming message arrives (e.g. from Facebook Messenger) then the messenger proprietary format gets converted into the Oracle Digital Assistant message model format.
To build the message model format in a custom component, you use the MessageModel class, which you access through a call to conversation.MessageModel() in a custom component.
The custom custom code shown below is all that it takes to programmatically render attachments. The sample receives the URL to render and the document type information as input parameters from the dialog flow. However, its easy to see how the code can be changed to read the URL and document type from a remote service.
Notice that the custom component allows you to also define actions to an attachment (url, postback, call), a functionality that is not available on the System.CommonResponse component.
The actions added to the attachments, in the sample, are URL actions that open the referenced content in a new browser window or webview.
A third option to download content is to use a URL action.
Using a URL action in the System.CommonResponse component
If you simply want to redirect to a website to display content, then you can add a URL action to a menu item or a card item in the Oracle System.CommonResponse component. The sample skill you can download for this article uses a global action to display a URL action for users to access the Oracle Digital Assistant documentation
URL actions are always opened in a separate browser window (or tab) or webview.
Downloads
– You need to run "npm install" on the command line if you want to further develop and deploy the component
Sample SKILL (v. 19.1.5) (ZIP)
– Skill contains the custom component. You can directly run the skill in the embedded tester. Just type "hi" for a start
Related documents
TechExchange: How-to Populate a Common Response Component Iterator from a Custom Component
TechExchange Quick-Tip: Customizing the Oracle Bots Node.js SDK Component Template
TechExchange: How-to Build Card Layout Responses from Custom Components
