The Helpdesky widget is a floating help button that appears on your website and provides access to your knowledge base. When messaging is enabled, a Message tab appears in the widget, allowing visitors to start a conversation without leaving the page.
No extra embed code needed. If you have already added the Helpdesky widget to your site, enabling widget messaging is a dashboard toggle. No code changes required. If you have not set up the widget yet, the setup steps below will walk you through it.
Widget messages flow into the same Messages inbox as Contact Form and Ticket Center conversations. Visitors are identified by a browser token, and they can optionally provide their email to receive reply notifications.
How It Works
Visitor clicks the widget button. The Helpdesky widget opens with your knowledge base search and, if messaging is enabled, a Message tab.
Visitor sends a message. They enter their email address, an optional name, and their message. A browser token is generated so they can return to the conversation later.
You reply from the dashboard. The message appears in your Messages inbox. When you reply, the visitor sees it the next time they open the widget, and they receive an email notification at the address they provided.
Setup
Enable messaging. In your Helpdesky dashboard, go to Messages and make sure messaging is turned on.
Enable widget messaging. Go to Embeds > Widget in the dashboard. In the widget settings, turn on the Show messaging in widget switch. This adds the Message tab to the widget.
Turn on Show messaging in widget. The blue switch, with its handle on the right, shows the enabled state.
Customize the welcome note (optional). You can set a welcome note that appears at the top of the messaging view in the widget. This is a good place for text like "We usually reply within a few hours" or "Leave us a message and we will get back to you."
Looking for the "We usually reply within a few minutes" line? That text sits at the top of a live chat and is a separate setting, the Live chat reply time note. Change it under Embeds > Widget > Messaging > Live chat reply time note. It only appears once the messaging mode includes live chat.
Choose a messaging mode (optional). The same section has a Messaging mode setting. Keep Ticket only for the email plus message form described in this guide, switch to Live chat only so visitors can chat without leaving an email, or pick Let the visitor choose to offer both. See Live Chat vs Ticket Messaging in the Widget for how each mode looks to visitors and in your inbox.
Done. If your widget is already embedded, visitors will see the messaging option immediately. If not, follow the Widget Embed Code section below to add the widget to your site.
Widget Embed Code
If the widget is already on your site, skip this section. Widget messaging is controlled entirely from the dashboard. Otherwise, add this snippet before the closing </body> tag:
<script src="https://helpdesky.io/widget.js"
data-helpdesk-id="YOUR_HELPDESK_ID"></script>
Tip: Get your exact embed code from Embeds > Widget in the dashboard. It already has your helpdesk ID filled in.
| Attribute | Required | Description |
|---|---|---|
data-helpdesk-id |
Yes | Your helpdesk's unique identifier. |
Widget appearance (position, color, etc.) is configured in the dashboard under Embeds > Widget.
Email Notifications
When you reply to a widget conversation, the visitor receives an email notification if they provided an email address. Notifications are delayed by 60 seconds and can be skipped if the visitor reads the message before the email is sent. You can also send emails immediately using the Send Instantly toggle. See Email Notification Timing for full details.
API Endpoints
These endpoints are called by the widget script. You do not need to use them directly. They are documented here for transparency.
GET /api/widget/:helpdeskId/config
Returns the public widget configuration, including a messagingConfig object with the messaging mode and live chat texts. Two fields tell the widget how to treat operator availability: liveChatShowAvailability (true by default; false hides the Online now badge and the offline message inside an open chat) and liveChatOfflineBehaviour ("ticket-form" by default, or "keep-live-chat" to leave live chat open while nobody is online). The response also carries an online flag, and GET /api/widget/:helpdeskId/presence returns the current value while the Message tab stays open. See Live Chat vs Ticket Messaging in the Widget for what each setting does.
POST /api/messaging/widget/:helpdeskId/message
Creates a new conversation from the widget. Requires email and message fields; name is optional. When the helpdesk offers live chat, the widget sends mode: "live-chat" and may omit email. Returns a contactId and contactToken for subsequent requests.
POST /api/messaging/widget/:helpdeskId/reply
Sends a reply to an existing widget conversation. Requires contactId, contactToken, conversationId, and message.
GET /api/messaging/widget/:helpdeskId/history
Retrieves conversation history for a widget contact. Requires contactId and contactToken as query parameters.
POST /api/messaging/widget/:helpdeskId/update-email
Associates an email address with a widget contact so they can receive reply notifications. Requires contactId, contactToken, and email.
Restrict Where the Widget Loads
You can limit which websites are allowed to load your widget and its messaging. Open Settings > Messages in the dashboard and add your domains to the Allowed Embed Domains setting. Subdomains are included automatically, and leaving the list empty allows every domain. For the full walkthrough, see Restrict Embeds to Specific Domains.
Troubleshooting
Message tab not appearing in the widget. Check that both messaging conditions are met: messaging is enabled for your helpdesk (Messages page toggle), and widget messaging is enabled in Embeds > Widget. Also make sure the messaging feature is activated for your account.
Visitor lost their conversation. Widget conversations are tied to a browser token stored in localStorage. If the visitor clears their browser data, switches browsers, or uses a private/incognito window, the token is lost and they cannot access previous conversations. Encouraging visitors to provide their email helps with continuity. They will receive email replies regardless of browser state.
Widget not appearing at all. Verify that your embed snippet is correct and that your data-helpdesk-id is valid. Open your browser's developer console and check for any JavaScript errors. The widget script should load from helpdesky.io/widget.js.
Messages not appearing in the dashboard. Widget messages appear in the Messages inbox alongside Contact Form and Ticket Center conversations. Make sure you are looking at the All filter (not filtering by status). New widget messages arrive as "Pending" status.