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 (v3.0)

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, for Chat AI params, look at the next table.

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

Script Query Parameters (Chat AI)

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 Chat AI.

Quick note: the api-key is no longer passed in as a query parameter, but is part of the main URL.

Parameter	Data Type	Required?	Description
anchor	string	Optional	Indicate where you'd want to anchor the widget. The possible options are right (default), left, or center. The center option positions the widget in the middle of the screen (horizontally and vertically). The trigger remains anchored to the right.
vOffset	number	Optional	Vertical distance (in pixels) from the anchor point.
hOffset	number	Optional	Horizontal distance (in pixels) from the anchor point.
customTriggerId	string	Optional	References an HTML element (like a button or link) by its id to act as the widget’s trigger.
embedId	string	Optional	References an HTML container element (like a <div> or <section>) by its id, where the widget frame will be embedded.
hide-trigger	boolean	Optional	Hides the widget launcher on load. After that, the widget can only be controlled via the provided methods (expand, collapse), unless the launcher is re-enabled with window.MedChatAI.showLauncher().

window.medchatapp (or window.MedChatAI) 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.MedChatAI	Chat AI version	This is the alias used by our Chat AI widget. This will only be available when you use the Chat AI widget script.
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	( 🚧 Certain properties that were pre) => 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>

Remember, if you're using the new Chat AI version, replace MedChatApp with MedChatAI