The Talkative Programmatic (API) Actions feature allows developers to control and extend the Chat Widget through JavaScript. Using these actions, you can trigger events, open or close the widget, and launch specific interaction flows from anywhere on your website.
This is an advanced customisation feature, ideal if you want to:
- Trigger the widget from a custom website button or link.
- Integrate Talkative chat triggers with your site’s navigation or call-to-action elements.
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 recognised.
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();