Widget API

🚧
Certain properties that were previously public will be private or removed from the medchatapp page object. There have also been deprecations of methods and events. These items will continue to work but it is strongly recommended to eliminate their use and use the newly recommended replacements instead. HTML elements for what was formerly called the ‘trigger’ have been removed entirely and moved into the widget iFrame. The ‘trigger’ is now called the ‘launcher’ to indicate its increased capabilities. This move will eliminate collisions and increase interoperability between MedChat’s Widget and provider platforms.

Script Query Parameters

The widget script can take certain configuration parameters in its src parameter URL query string to configure the widget’s behavior on the page. Below are the parameters available in version >= 3.0:

Parameter	Data Type	Required?	Description
api-key	string	Required	Unique widget identifier found on the admin/widgets page
expand	enum	Optional	Force the widget to expand at some point after load. Possible values for this parameter are listed below: initial -> Automatically expand the widget on the initial session page load. Subsequent page loads will not automatically expand and will defer to the cached widget state launch -> Automatically expand the widget on every page load. This will ignore cached widget state
collapse	enum	Optional	Force the widget to collapse based on some widget lifecycle trigger, set to one of the following values: leave -> Auto collapses the widget when reloading the page, for example, via refresh
hide-launcher	boolean	Optional	Hides the widget launcher at launch. From this point, the widget can only be controlled via the provided methods (expand, collapse), unless it is re-enabled by the global window.medchatapp method showLauncher()
hide-trigger	boolean	Optional	Deprecated. Alias for hide-launcher. Use hide-launcher instead

window.medchatapp property

The MedChat widget is controllable via an exposed javascript object. Referencing this object will provide access to all methods and event handlers.

Object Alias	Status	Description
window.medchatapp	Recommended	This is the primary alias, and it is recommended to use this exclusively. For legacy reasons, other aliases are available, but may be removed in the future. For guaranteed continued functionality, use this reference only
window.MedChatApp	Deprecated	Provided for legacy purposes. Use window.medchatapp instead
window.MedChat	Deprecated	Provided for legacy purposes. Use window.medchatapp instead

Event Handlers

By defining handlers for certain events you can execute custom code triggered by these events. All event callbacks listed here can be accessed using the window.medchatapp object.

For each of the following events you can add a custom function:

Handler Name	Signature	Description
onChatStart	() => void	Fires when a chat starts
onChatContinue	() => void	Fires when a chat continues (after refresh)
noChatToContinue	() => void	Fires when a widget attempts to continue a chat, but fails because there is no chat returned
onChatEnd	() => void	Fires when a chat ends
onExpand	() => void	Fires when the widget is expanded
onCollapse	() => void	Fires when the widget is collapsed
onTopicChanged	(topic: string) => void	Fires when a topic is selected. Receives the topic name as a string
onOnline	() => void	Fires after load if the widget is online (has any combination of agents or bots available, including offline bots)
onOffline	() => void	Fires after load if the widget is offline (has no agents or bots available)
onInit	() => void	Fires once widget has initialized
onOpen	() => void	Deprecated. Alias for onExpand(). Use onExpand() instead

Instance Methods

The MedChat Widget exposes a set of methods to allow for custom behavior of the widget with provider implementations. Some instance methods have changed or been deprecated since previous versions of the MedChat Widget. Make sure to review them and to update your implementation if necessary, as there is no guarantee that the deprecated items will continue to be used in the future. All methods listed here can be accessed using the window.medchatapp object.

Method	Signature	Description
registerJWT	(jwt: string) => void	Registers the user jwt with the widget to verify chat sessions with
unVerifyUser	() => void	Removed registered user jwt from the widget so chat sessions are no longer verified
registerChatProperties	([{ name: 'propName', value: 'propValue' }]) => void	Registers additional properties with the widget to be included when a user starts a chat. This data will be attached to the chat data and can be retrieved for usage outside of MedChat after the chat completes. Note: once a chat has started this data cannot be updated until the next chat starts.
collapse	() => void	Collapse the widget, if possible
expand	() => void	Expand the widget, if possible
showLauncher	() => void	Show the launcher
hideLauncher	() => void	Hide the launcher
reset	() => void	resets the widget to its default state
launch	() => void	Deprecated. Alias for expand(). Use expand() instead
showTrigger	() => void	Deprecated. Alias for showLauncher() - use showLauncher() instead
hideTrigger	() => void	Deprecated. Alias for hideLauncher() - use hideLauncher() instead

Sample HTML:

<script type="text/javascript" async src="https://medchatapp.com/widget/widget.js?api-key=owtpCZkJW02wp_gWK6-jCg"></script>
<button onclick="MedChatApp.hideLauncher()">Hide Launcher</button>
<button onclick="MedChatApp.showLauncher()">Show Launcher</button>
<button onclick="MedChatApp.expand()">Expand Widget</button>
<button onclick="MedChatApp.collapse()">Collapse Widget</button>