This document details some of the method calls and call-backs available with the Talkative Widget Scripts. All the methods here can be utilised to handle custom scenarios and allow your website to interact with the widget on a limited level. Please note, the API calls in the __unsafe namespace are built for a custom implementation, managed by Talkative, and should not be used.
Note: we recommend you be on the latest Widget version in order to access all the API methods.
API Methods
| Method Name | Description |
|---|---|
| talkativeApi.ui.canShow() | This call will return a boolean value to indicate if the UI can be shown. This is a check to ensure there are cards available in the loaded config for the current page |
| talkativeApi.ui.isVisible() | This call will return a Boolean value to indicate if the card UI is currently visible or not. Please note, this is specific to the card UI showing, not the widget bubble. |
| talkativeApi.ui.show() | This call will make the talkative card UI show. If the UI is already showing, this call will not do anything. |
| talkativeApi.ui.hide() | This call will make the talkative card UI disappear. If the UI is already hidden, this call will not do anything. |
| talaktiveApi.ui.isAvailable() | This call will check if the talkative UI has been deactivated, unlike the isVisible() method above, this relates to the activate() and deactivate() method which will hide the entire UI, including the widget bubble and any nudges |
| talkativeApi.ui.activate() | This call will activate the UI, this is used to show the entire UI if it has previously been hidden using the deactivate() call |
| talkativeApi.ui.deactivate() | This call will deactivate the UI, this is used to hide the entire UI, including any nudges and widget bubbles. This differs from the hide() method above which just hides the card UI. |
| talkativeApi.__unsafe.* | There are many methods under this namespace. They are not for public consumption as they are not versioned and intended for specific custom implementations built by the Talkative support team. |
| talkativeApi.interaction.getInteraction() | This call will return a JSON object containing information about the current interaction. This data includes some reference numbers, a list of active features, some user information, a list of messages from the interaction, customer information, feedback information and some queuing statistics. |
| talkativeApi.interactionData.appendInteractionData(arrayOfData) | This call allows you to append interaction data to the interaction. It can be used before or during the interaction. The parameter accepts an array containing objects which should include, a name as a string, a label, as a string, the data, which is usually a string, and the type, which, at the time of writing, only accepts “string” as a value. An example of such an object is: { name: “accountNumber”, label: “Account Number”, data: “12345”, type: “string” } |
| talkativeApi.interactionData.setSignedInteractionData(signedIntData) | This call allows you to pass signed interaction data to Engage. This is used when the data being sent must be signed to confirm it has not been tampered with. For further details on this, please visit https://support.gettalkative.com/knowledge/signed-interaction-data-1 |
| talkativeApi.cards.triggerCardAction(id, options) | THIS CALL IS DEPRECATED AND SHOULD NOT BE USED. INSTEAD UTILISE PROGRAMMATIC ACTIONS |
| talkativeApi.actions.triggerAction(id) | This call allows you to trigger programmatic actions, this is used to create custom CTA actions within your own website, which can trigger the widget. For details on their setup, please visit: https://support.gettalkative.com/knowledge/using-programmatic-actions-1 |
| talkativeApi.actions.getActions() | This call returns a Promise containing a list of the configured programmatic actionables. This can be used to check an action exists before calling it, or for reference during development. |
| talkativeApi.queues.getPresences() | This call will return an array of presence data for the queues loaded via the config for this widget. Please note, this will only show the presence data for queues related to the config, and not the entire estate. In addition to this, the data shown will not update when you call again. This is populated when the widget first loads. The data is also cached at a server level, so updates to this will be delayed by a minute. |
| talkativeApi.customer.getQos() | This will return a JSON payload of our QoS data. This indicates the features which the customer can use depending upon device availability and bandwidth check. For example, this may be used to determine if a CTA button to start a video call is enabled or shown. You might choose to hide a CTA for video chat or show a different button if a customer does not have a webcam and microphone. |
Events & Callbacks
The Talkative Widgets emit events at certain points during the applications lifecycle. These events can be hooked into by registering a callback on the application.
The widget will look for an object on the window called “talkativeCustomConfig” this object will trigger a method called “customTracking” which will have an arguments variable injected into it. This variable is an object, with the item with a key of 0 being the event name. I.e., “enterInteraction”
The table below is a non-exhaustive list of potential events you may see.
| Event Name | Description |
|---|---|
| enterStandby | Enter standby is triggered when the interaction goes into standby mode. This fires when the widget returns to standby mode, meaning the widget bubble would be showing (unless you have configured to be hidden). It is at this point the widget can begin an interaction. |
| enterInteraction | This event is fired when an interaction is entered, this means the user has completed any data collection stage and made a request to the server to begin an interaction |
| enterInteraction(FeatureNameHere) | This event is fired in addition to the event above but will have a suffix indicating the interaction type. Ie, “enterInteractionChat” or “enterInteractionVideo” this indicates the primary feature of the interaction. This can be useful for when you want to hook into, or track different behaviour based on the interaction type. |
| resumeInteraction | This is fired when an interaction is resumed. This generally happens when a customer minimized and then opened their widget again mid interaction, or during a page change. |
| exitInteraction | This occurs when the interaction has ended, but before the feedback collection stage. |
| completeInteraction | This occurs when the feedback stage has been completed by the user. Please note, that if the feedback stage is not completed, either because it is ignored, or a page refresh occurs, this will not be fired. |
| ready | The ready state is fired when the interaction first loads and has completed retrieving its config. It is important to note this does not necessarily mean the widget is ready to start an interaction. You should wait for the first enterStandby event before trying to start an interaction. |
| qosFail | The quality of service fail check is triggered if someone attempts to start an interaction, but their device has less than the required amount of bandwidth, or the user’s device is not supported. IE, no web camera for a video call etc. |
| presenceFail | Whilst generally you would use the widgets visibility rules to prevent cards from showing to customers if the agents were all offline, if you did decide to show the widget and give the option to start an interaction when the queue was unavailable, this event would fire. |
| rateLimitFail | If there have been too many requests to the server from a specific IP address, we may rate limit requests. This event fires should any request make from the widget be returned a 422-rate limit status. |
| visibilityChange | This fires when the widgets visibility changes, i.e., someone clicks on the widget bubble to show the interaction, or they subsequently hide it. |
| availabilityChange | This fires when the widgets availability is changed. This is different from visibility change, as it requires a call to the talkativeApi.ui.activate() and talkativeApi.ui.deactivate() API calls. When it is unavailable, it is hidden from view completely, including any nudges or widgets so cannot be interacted with. |
| sendEmail | This is triggered when the system sends an email, be it an offline email, or via an escalation through chatbot or chat wait messages. |
| enterDataCollection | This event is fired when the customer has clicked to start an interaction and has entered the data collection phase. At this point, the interaction is not active, but we are no longer in standby mode. |
| exitDataCollection | This is fired when the user exists the data collection phase, either because they completed it and started the interaction, or because they cancelled it. If they cancelled it, you would expect to see an event for enterStandby also fire afterwards. |
| agentJoined | This event fires when an agent joins the interaction. The arguments available include the user who joined, which includes a boolean to indicate if the user is a chatbot user, and the time the event occurred |
| agentLeft | This event fires when an agent leaves the interaction. The arguments available include the user who joined, which includes a boolean to indicate if the user is a chatbot user, and the time the event occurred |
Rather than using the customTracking, you can hook into these events directly by defining another object within the talkativeCustomConfig object called events, the events object accepts callbacks to any of these events.
For examples of how to implement these callbacks, please refer to the examples in the GitHub repo here: https://github.com/talkative-tech/widget-examples/tree/main/event-hooks
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article