Drive the widget from your page
Open, close or reload the widget from your own site’s code.
The widget loader puts an EchoWidget object on the window. It lets you open the panel from one of your own buttons, close it, take it off the page, or redraw it with different settings.
// Open the panel from your own button
document.querySelector('#help').addEventListener('click', function () {
window.EchoWidget.show()
})
// Close it again
window.EchoWidget.hide()
// Take the button and the panel off the page
window.EchoWidget.destroy()
// Redraw the widget with different settings
window.EchoWidget.init({ position: 'bottom-left', color: '#0f766e' })The four functions
| Function | Effect |
|---|---|
| EchoWidget.show() | Opens the panel and turns the button’s icon into a cross. Does nothing if the widget was removed by destroy(). |
| EchoWidget.hide() | Closes the panel, with the same animation as clicking the cross. |
| EchoWidget.destroy() | Removes the button and the panel from the document and stops listening to the widget’s messages. Nothing is lost on the conversation side: the visitor is still recognised and finds their exchanges in the widget’s list next time it opens. |
| EchoWidget.init(settings) | Removes the existing widget, then draws it again. Accepts organizationId, position and color; anything left out keeps the value in place. Always pass an object, even an empty one. |
When the object exists
EchoWidget is only put on the window if the loader found an organization id. Without the data-organization-id attribute it writes an error to the console and stops before that: window.EchoWidget is then undefined. Test for it before calling it if your code can run on a page without the tag.
if (window.EchoWidget) window.EchoWidget.show()Passing the id other than by attribute
If your page cannot carry an attribute on the tag — a tag manager that rewrites it, a template that will not let you — set window.__echoOrgId BEFORE loading the widget: the loader falls back to it when it finds the attribute neither on its own tag, nor on another tag of the page whose address contains "widget".
<script>window.__echoOrgId = 'YOUR_ORGANIZATION_ID'</script>
<script src="https://widget.echo-group.ca/widget.js"></script>The button and the panel sit above the rest of the page (z-index 999999 and 999998). If something on your site has to come over them, it needs a higher value.