How do I use directives?

Owned by Rajkiran Alla (Deactivated)
Last updated: Apr 18, 2022 by Bharathi Manohar (Deactivated)
14 min read

Directives control how a client application renders an experience to an endpoint, such as an Echo Show, Google Home Hub, chatbot, Facebook messenger, and an IVR/phone experience, to name just a few.

It is used to control the experience, for example, log a user out, add a control to record audio, or add a carousel control for rending a list of objects, or buttons, or dynamic ajax adaptive cards, or any HTM5 card.

Directives are instructions sent from the server to the client, instructing the client to perform a specific action such as playing audio, displaying an image.

Directives can be created by a function node, injected after a SAY node in the Experience Designer.

You can Validate the directives using postman.

Orbita makes use of two kinds of directives:

Directives that render information to the client

When the client invokes a flow that contains this kind of directive, the server will send the relevant information to the client and no further communication will happen.

HTML5

The HTML directive shows an HTML string or URL content within the chat bubble. If the directive object type is html5, then the server will render.

  • HTML String. The response will be in string format. The Options object should contain html key in it.

  • URL content. The response will be the content from the URL. The Options object should contain url key in it.

If the Options object contains both html and url keys, the html key will get the priority.

Output Payload: This code includes both html and url

msg.payload.orbita.directive = [{     type : "html5",     options : {         template : "500x500",         html : "<!DOCTYPE > <html> <head> <style> div { width : 900px; height : 100px; background-color : red; -webkit-animation-name : example;  -webkit-animation-duration : 4s; animation-name : example; animation-duration : 4s; }   @-webkit-keyframes example { from {background-color: red;} to {background-color: yellow;} }  @keyframes example { from {background-color: red;} to {background-color: yellow;} } </style> </head> <body> <p><b>Note:</b> This example does not work in Internet Explorer 9 and earlier versions.</p> <div></div> <p><b>Note:</b> When an animation is finished, it changes back to its original style.</p> </body> </html>",     } }, {     type : "html5",     options : {         template : "500x500",         url : "https://orbita.ai"     } }]; return msg;

The Output of “Options – html”.

The Output of “Options – url”.

Logout

When the client invokes the logout directive, the server responds with a popup window with a custom message.

Clicking OK redirects you to the home screen of the app.

Output Payload:

msg.payload.orbita.directive = [{ type : "logout", title : "Session logOut", options : {message: "You are logged out"} }]; return msg;

 

Text Break

The Text Break can be used on the chatbot where we need to provide breaks between conversations, like while transferring to a Live Agent.

Code snippet

msg.payload.orbita.directive = [{ type: 'textbreak', options: { primaryMessage: "Transferring you to a live agent.", //mandatory secondaryMessage: "12:45pm", //optional tertiaryMessage: "Sharron has entered the chat." //optional } }];

Directives that request information from the client and then render information

When the client invokes a flow that contains this kind of directive, the server responds by asking for input from the client. After the input from the client is received, the server stores the information and responds with a success or failure message.

Audio Recorder

If the type of the directive object is audiorecording, the Audio Recorder widget is rendered. It is a floating widget.

Output Payload:

The Audio Recorder widget is used to send the voice recording to the server.

The title property value is displayed at the top of the widget as shown.

If the title property is empty, the title field will be blank in the UI.

When you click the record button, the voice recorder starts recording. The recording state of the Audio recorder is shown.

Once recorded, you can play or upload the audio recording using the play or upload buttons.

You can get the recording stop time property form the directive object, use the stopTime property to get the recording time.

The success response from the audio upload contains the URL of the recorded audio.

Transcribe

If the type of the directive object is transcribe, the Transcribe widget is rendered. It is a floating widget.

Output Payload:

The Transcribe widget is used to send the converted text to the server.

The title property value is displayed at the top of the widget. If the title property is empty, the title field will be blank.

By default, the mic is off; you must click the mic button to start the speech to text conversion. While conversion of speech-to-text is in progress, the buttons at the bottom of the screen such as the keyboard, mic, and menu are disabled. However, the speaker button at the top is accessible anytime.

To stop the conversion, click Stop or give a pause in the speech for a specified time.

The Speechtotext property value decides which speech to text converter to use.

  • If the value is set to native, the speech to text converter of the OS is used.

  • If the value is set to google, Google’s speech to text converter is used.

Therefore, the pause time to stop the speech to text conversion depends on the Speechtotext property value.

After the conversion from speech to text is stopped, you can delete or upload the transcribed file using the Stop or upload buttons.

Date Picker

The Date picker directive lets you pick the date.

Sample flow

Copy the following code into a function node to enable the Date picker in the chatbot.

Sample Code

The from and to properties from the options object is for validation and is optional.

The Date picker bubble is rendered as shown.

Click the calendar icon to open the Date picker widget.

Time Picker

The Time picker directive lets you pick the Time.

Sample flow

Copy the following code into a function node to enable the Time picker in the chatbot.

Sample Code

The Time picker bubble is rendered as shown.

Select the hours or minutes or am/pm and use the up/down arrows to change.

Date and Time Picker

The Date and Time picker directive lets you pick the date and time simultaneously.

Sample flow

Copy the following code into a function node to enable the Date and Time picker in the chatbot.

Sample Code

The Date and Time picker bubble are rendered as shown.

Click the calendar icon to open the Date and Time picker widget.

Select the hours or minutes or am/pm and use the up/down arrows to change. You can also choose Today’s date.

Reminder Directive

As an admin user, If the chatbot user does not reply for more than a predefined time, then you would like to remind the user that the bot is awaiting a response from the user. Reminder Directive is available to exactly fit this use case.

Using this directive, you can send a custom re-prompt message or even send custom buttons for the users to choose from.

Sample Flow

Copy the below code into a function node to enable the Reminder Directive in the chatbot.

Sample Code

Required parameters

type

The type field should be “reminder”

waitTime

The waitTime is the time, the chatbot will wait, before sending the reminder message.

text

The text is the reminder message.

Sample Code

Note: If the response already contains buttons and if you don’t provide the buttons property in the directive, then the chatbot will recall the buttons from the current response.

Optional Parameters

buttons

If you want custom buttons in the reminder directive, you can make use of buttons property. This is an optional field.

When you place the custom buttons in the reminder directive, it will override the buttons from the current response.

Validating directives in Postman

  1. Login to Postman.

  2. Select the method - POST.

  3. Place the login endpoint in the space provided.

  4. In the Body tab, paste the login credentials as input and click Send.

  5. If successful, you will receive a token.

  6. Switch to the Headers tab, and paste the token that you obtained from the earlier step.

  7. Provide the endpoint URL of your chatbot.

  8. Click Send.

  9. In the Body tab, Paste the code below to test the directive and click Send.

You will have to provide the utterances that will trigger the respective directives.

HTML

Logout

Audio recording

Transcribe

Example flow

The following image shows an example flow that triggers the directives when invoked with the respective intents.

Related Articles