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 "Send us a message" option 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 "Send us a message" link at the bottom.
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 Settings > Widget in the dashboard. In the widget settings, turn on the "Enable messaging" toggle. This adds the "Send us a message" option to the widget.
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."
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 Settings > 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 Settings > 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.
POST /api/messaging/widget/:helpdeskId/message
Creates a new conversation from the widget. Requires email and message fields; name is optional. 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.
Troubleshooting
"Send us a message" 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 Settings > 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.