Using Programmatic Actions (API Actions)

Using API Actions

Introduction

An API Action 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. API Actions 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 API Actions 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 API Action

In the widget config editor, go to Advanced >  API Actions from the menu. You should now see a list of existing API Actions. The list will be empty if you haven't created any yet.

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

Select the new API Action from the list to edit its properties.

The first property to note is API Reference. This is the reference that will be used later when you initiate the API Action 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 API Action on your website.

Using an API Action on your website

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

talkativeApi.actions.triggerAction('your-action-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 API Action 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 API Action 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 API Action 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();