Using Programmatic Actions

Using Programmatic Actions

Introduction

This article assumes you have a working knowledge of HTML and JavaScript. Actionables require minimum widget version = 0.14.

An actionable is the action you normally assign to a button in the chat widget standby card or nudge. For example, you can make the button in a standby card start an interaction. Programmatic actionables allow you to create actions that aren't tied to any buttons and can be called by custom JavaScript code on your website.

An ideal use-case for programmatic actionables is when you would like the customer to start an interaction from a link in your site menu or button on your contact page.

Creating an actionable

In the widget config editor, select API from the menu. You should now see a list of existing programmatic actionables. The list will be empty if you haven't created any yet.

To create an actionable, click the + button next to the submenu heading. A new actionable will appear in the list below the button.

Select the new actionable from the list to edit its properties.

The first property to note is Actionable name. This is the reference that will be used later when you initiate the actionable on your website. Please note: if this property is changed, you will also need to update any references to it in your website's code.

The next section is Action Settings. This will look familiar if you have specified an action for a button in the Card Editor section. Select an action from Action Type and fill in the resulting fields to configure your action.

You are now ready to use your programmatic actionable on your website.

Editing an actionable

To edit an actionable, select API from the menu. From here you can select the desired actionable from the submenu and edit its properties.

Using an actionable on your website

The chat widget's JavaScript API gives you the power to trigger any of the actionables you've previously configured. Use the following code snippet to trigger an actionable (leave the quotes around the actionable name):

talkativeApi.actions.triggerAction('your-actionable-name');

Triggering an action will return a JavaScript Promise. The promise will resolve if the action was successful and reject if an error occurred. An example of an error is if the actionable name wasn't recognized.

Please note: an action that has successfully triggered won't guarantee the interaction will start, only that it was successful in attempting to start the interaction. If, for example, the actionable was triggered out of business hours, the interaction won't start and the chat widget will provide visual feedback to the user.

While the above snippet is all you need to trigger an action, you will need to do a little more to make your code resilient. For example, if the chat widget scripts haven't finished loading, talkativeApi will not exist, causing an error.

Our GitHub repo contains a heavily commented example implementation of a custom button, which you can clone onto your own machine and run. The repo can be found here https://github.com/talkative-tech/widget-examples/tree/main/custom-trigger-button

Note: you shouldn't trigger actionables during an active interaction. While there shouldn't be any adverse effects from doing so, we can't guarantee this will always be the case.

Notes

Another JavaScript API endpoint has been created to allow you to inspect what actions are available. This can be helpful when developing your custom trigger code.

talkativeApi.actions.getActions();