A Custom widget lets you show data from your own systems in the widget panel next to every conversation in Herodesk. Whenever an agent opens a conversation, Herodesk asks your server (your "endpoint") for content about the customer and shows the answer in the panel.
Examples are:
- Your own CRM, ERP or webshop backend
- Account data from your SaaS product (plan, status, usage)
- Other 3rd party tools we do not have a built-in widget for
With a Custom widget you can:
- Show text, lists, tables and accordions with your data
- Show your own HTML such as cards, badges, coloured status labels, collapsible sections and progress bars (Herodesk Plus)
- Let agents run actions in your system, for example "Cancel order", "Resend confirmation" or "Extend trial by 14 days", optionally asking the agent for values first. The result is shown in the widget and recorded in the conversation timeline (Herodesk Pro)
- Receive extended context about the contact, company, conversation and agent, so you can find the customer by your own ids instead of only by e-mail address (Herodesk Plus)
- Verify that requests come from Herodesk with signed requests, an Authorization header and unique request ids
- Test and debug with built-in developer tools: send a test request, preview a response and see a log of recent requests
Existing Custom widgets keep working exactly as before. All new options are off until an admin switches them on.
Plans and availability
| Capability | Basic | Plus | Pro |
|---|---|---|---|
| Custom widget with text, lists, tables and accordions | Yes | Yes | Yes |
| Request signing, Authorization header, request ids | Yes | Yes | Yes |
| Developer tools (test request, preview, request log) | Yes | Yes | Yes |
| HTML content and collapsible sections | No | Yes | Yes |
| Extended context | No | Yes | Yes |
| Action buttons and forms, "Who can run actions", timeline entries for actions | No | No | Yes |
The Custom widget is not available on the Free plan. If a setting is not included in your plan, it is shown greyed out with an upgrade hint.
If you downgrade while a feature is switched on, Herodesk stops using it immediately, even though the setting still says "Yes":
- HTML content is not shown. The widget shows "The JSON input contains HTML elements, which are available on the Herodesk Plus plan."
- Extended context is no longer sent.
- Action buttons are disabled. If one is triggered anyway, the agent sees "Action buttons are available on the Herodesk Pro plan."
How it works
- An agent opens a conversation.
- Herodesk sends a
POSTrequest with JSON to the URL in your widget settings. - Your endpoint looks up the customer and answers with JSON in the format described below.
- Herodesk shows the content in the widget panel.
- (Pro) If the agent clicks an action button, Herodesk sends a
POSTrequest to the button's URL, and your system answers with a result such as{"status":"success","message":"Order #1080 was cancelled."}. The result is shown in the widget and added to the conversation timeline.
Good to know:
- Herodesk's server makes all calls, never the agent's browser. Your server sees requests from Herodesk, not from your agents' computers. You don't need to configure CORS or expose anything to the browser.
- The URL must be a public web address (http or https). Local or internal addresses such as
localhostor192.168.…are rejected when you save the settings. - Herodesk waits at most 30 seconds for an answer and does not follow redirects. An endpoint that redirects (for example from http to https, or to a login page) is shown as an error.
- The widget is loaded every time a conversation is opened, so the content is always fresh.
Install a Custom widget
Go to Settings → Widgets → Add widget and choose Custom widget.

| Field | What it does |
|---|---|
| Display Name | The name shown on the widget in the panel, so your team knows which system the data comes from. Letters, numbers, spaces and _ - & only (no parentheses). |
| Url | Your endpoint. Herodesk sends its requests here. Must be a public address. It also decides which addresses action buttons may call (see Action buttons). |
| Allow HTML content (Plus) | Lets your endpoint send html elements. Default: No. |
| Send extended context (Plus) | Adds a context object with contact, company, conversation and agent details to every request. Default: No. |
| Signing secret | When set, every request is signed so your endpoint can verify it came from Herodesk. Optional, at least 16 characters. Stored encrypted and shown as ********. Empty the field and save to remove it. |
| Authorization header | Sent as the Authorization header on every request, for example Bearer YOUR_API_KEY. Useful for endpoints behind an API gateway or that require an API key. Optional, one line of plain text, max 1024 characters. Stored encrypted and shown masked. Empty the field and save to remove it. |
| Who can run actions (Pro) | Everyone who can see the conversation, Admins only, or Admins and selected teams. Default: everyone. Admins can always run actions. |
| Teams that can run actions (Pro) | The teams allowed when "Admins and selected teams" is chosen. At least one team is required. |
| Enabled / Show Default / Dynamic view / Hide on Empty | Same as for every widget. "Hide on Empty" works with foundItems (see below). A disabled widget is not loaded and its buttons are refused. |
Below the Save button you find the Developer tools and the built-in reference "How to use a Custom widget" with the exact formats. The built-in reference is also available in Danish and German.
The response format
Your endpoint answers with a JSON object like this:
{
"headline": "Nordlys Living shop",
"foundItems": 1,
"elements": [
{ "header": "Notes", "type": "text", "content": "**VIP** customer, prefers e-mail" },
{ "header": "Tags", "type": "list", "content": ["Wholesale", "Denmark"] },
{ "header": "Orders", "type": "table", "content": {
"tableHead": ["Order", "Status"],
"tableBody": [["#1080", "Shipped"], ["#1074", "Delivered"]]
}},
{ "header": "History", "type": "accordion", "content": [
{ "header": "Returns (3)", "content": [
{ "type": "text", "content": "RMA-2207 refunded" }
]}
]}
]
}
headline(required, string): shown at the top of the widget.elements(required, array): shown in the order they are added. Each element has aheader, atypeand acontent. You can add as many elements as you need.foundItems(optional, whole number of 0 or more): how many results you found. If it is 0 and Hide on Empty is enabled, the widget is hidden for that conversation.
Element types
text: a string.list: an array of strings.table: an object withtableHead(array of strings) andtableBody(array of rows, each an array of strings).accordion: collapsible items. All items start collapsed and only one is open at a time. The content is an array of items, and each item needs aheader(the clickable title) and acontentarray of blocks. A block is atext,list,tableorhtmlelement with an optionalheadershown as a label above it. Accordions cannot be nested inside each other.html(Plus, requires "Allow HTML content"): your own HTML. See HTML content below.
Formatting in text and lists
- Bold:
**bold text** - Italic:
*italic text* - Code: text in backticks
- Links:
[link text](url) - Button links:
[Go to Herodesk](https://herodesk.io){:target="_blank" :class="btn btn-primary"}
Link addresses may use http, https, mailto or tel. Other schemes are removed for security. Everything your endpoint sends is shown as content: Herodesk never runs code from it.
What Herodesk sends
Every request
Herodesk sends a POST request with this JSON body:
{
"widget_id": 6,
"contact_email": "ida.skov@example.com",
"conversation_id": "17"
}
conversation_id is sent as a string. In PHP you can read the body like this:
$data = json_decode(file_get_contents('php://input'), true);
Headers:
| Header | When | Value |
|---|---|---|
Content-Type | Always | application/json; charset=UTF-8 |
User-Agent | Always | Herodesk/1.0 (+https://herodesk.io; abuse@herodesk.io) CustomWidget/1.0 |
X-Herodesk-Request-Id | Always | A unique id (UUID) for this request. Log it on your side; it makes troubleshooting much easier. |
Authorization | When set in the settings | The configured value, for example Bearer … |
X-Herodesk-Timestamp and X-Herodesk-Signature | When a signing secret is set | See Verifying requests below. |
Extended context (Plus)
With Send extended context switched on, the body also contains a context object:
"context": {
"contact": {"id": 1, "name": "Ida Skov", "firstname": "Ida", "lastname": "Skov",
"email": "ida@example.com", "phone": "+45…",
"custom_fields": {"external_user_id": "u_123", "plan": "pro"}},
"company": {"id": 7, "name": "Møbelhuset", "domain": "moebelhuset.dk", "company_number": "DK123",
"industry": "Retail", "custom_fields": {"account_id": "acc_9"}},
"conversation": {"id": 17, "subject": "…", "status": "open",
"inbox": {"id": 1, "name": "Support"},
"channel": {"id": 2, "name": "support@…", "type": "email"},
"tags": ["vip"],
"assignee": {"id": 4, "name": "…", "email": "…"},
"team": {"id": 2, "name": "Customer Care"}},
"agent": {"id": 1, "name": "…", "email": "…", "role": "admin",
"teams": [{"id": 2, "name": "Customer Care"}],
"locale": "da-DK", "timezone": "Europe/Copenhagen"}
}
- Custom fields are listed by their slug (see Settings → Custom fields) and include every field,
nullwhen empty. Multi-select fields are lists. company,assigneeandteamarenullwhen not set.statusis one of: pending, open, closed, spam, merged, snoozed, draft.channel.typeis one of: email, chat, facebook_messenger, instagram, flexfone, whatsapp, unitel, three.agentis the person viewing the conversation.roleis admin, manager or agent.
Typical use case: you store your own user id or account id in a contact or company custom field (via the Herodesk API or a rule), and your endpoint looks the customer up by that id instead of by e-mail. This solves the common "the customer wrote from a different e-mail address" problem.
Privacy: with extended context on, your endpoint receives the contact's name, e-mail, phone and custom fields, company details, conversation details and the viewing agent's name, e-mail, role and teams. Without it, only the contact's e-mail and the ids above are sent. Action requests always include the clicking agent's id and e-mail.
HTML content (Plus)
Switch on Allow HTML content. Your endpoint can then send elements of type html, either at the top level or as a block inside an accordion:
{ "header": "Latest order", "type": "html",
"content": "<p>Order <strong>#1080</strong> <span class=\"badge text-bg-success\">Shipped</span></p>" }
How it looks and behaves
- The HTML is cleaned and shown in an isolated frame in the panel, in the same font and colours as the rest of Herodesk.
- The frame always fits: it grows to the exact height of the content (no scrollbar), follows the panel's width and wraps long words, links and wide tables so nothing sticks out sideways. It also resizes when a collapsible section opens or closes.
- Links always open in a new browser tab, so the agent never leaves the conversation.
What is allowed
- Text and formatting: paragraphs, headings (h1 to h6), bold, italic, underline, strike-through, small, sub- and superscript, quotes, line breaks, horizontal lines,
preandcode. - Lists (bulleted, numbered, definition lists) and tables (with header, body, footer, caption and column widths).
- Images with
httpsaddresses, or small PNG, GIF or JPEG images embedded as data, with width and height. divandspanwithclassandstyleattributes, so you can build cards, rows, badges and coloured text.- Collapsible sections with
<details>and<summary>, for example<details><summary>Returns (3)</summary><p>RMA-2207 refunded</p></details>. Addopento show a section expanded. - Inline styles for colours, backgrounds, borders, rounded corners, margins and padding, fonts, text alignment, widths and heights, floats, line height, letter spacing and list styles.
<style>blocks. These are converted to inline styles automatically, so you can write normal CSS.- Action buttons and form fields (Pro, see below).
What is removed
These are removed silently:
- All JavaScript:
<script>, event handlers such asonclickandjavascript:links. - Forms that submit by themselves, iframes, embedded objects, SVG,
<meta>,<link>and<base>. - Positioning (
position,z-index),displayand sizes in viewport units (vh,vwand similar). - Relative addresses such as
/orders/1. Links and images must use full addresses (https://…). - Images and CSS backgrounds that point at Herodesk itself.
Ready-made classes
You can use these classes, which mirror familiar Bootstrap names:
text-muted small fw-bold text-start text-center text-end text-success text-warning text-danger m-0 mb-0 mb-1 mb-2 mb-3 mt-2 d-flex justify-content-between align-items-center flex-grow-1 badge text-bg-primary text-bg-success text-bg-warning text-bg-danger text-bg-secondary btn btn-primary btn-success btn-danger btn-outline-secondary btn-sm alert alert-success alert-warning alert-danger alert-info table-borderless
Limits
Max 100 KB per html element and 300 KB of HTML per response in total. Larger responses show "The JSON input does not match the specifications".
Action buttons (Pro)
Buttons inside an html element can trigger an action in your system. Action buttons require Allow HTML content to be switched on.
<button class="btn btn-danger btn-sm"
data-hd-action-url="https://shop.example/herodesk/orders/1080/cancel"
data-hd-payload='{"order":1080,"reason":"customer request"}'
data-hd-confirm="Cancel order #1080?">Cancel order</button>
| Attribute | Required | Meaning |
|---|---|---|
data-hd-action-url | Yes | The address Herodesk calls. It must use exactly the same scheme, host and port as the widget's Url. Only the path and query may differ. |
data-hd-payload | No | Extra information as JSON (max 8 KB) passed on with the request, for example the order number. Very large whole numbers arrive as text to keep them exact. |
data-hd-confirm | No | Shows a "Please confirm" dialog with this text before the action runs. Recommended for anything destructive. |
Example: with the Url https://shop.example/herodesk/widget, the action URL https://shop.example/anything is allowed. https://api.shop.example/… (a subdomain), http://shop.example/… (another scheme) and https://shop.example:8443/… (another port) are not.
What the agent experiences
- The agent clicks the button. If a confirmation text is set, Herodesk asks first.
- The button is greyed out while the action runs.
- The result appears under the button: green for success, red for failure, with the message from your system.
- If your system asks for it, the widget reloads to show the new state, and the message is shown as a notification instead.
- An entry is added to the conversation timeline, for example "Ran Cancel order in widget Shop: Order #1080 was cancelled. at 14:02 by Sofie Lindberg", or "Tried …, which failed: …". The same entry appears in the audit log as "Custom widget action".
Agents who are not allowed to run actions see the buttons greyed out with the tooltip "You are not allowed to run actions in this widget."
What your system receives
{
"type": "action",
"request_id": "3f2b8c1e-9d4a-4f6b-8a2c-1e5d7b9f0a3c",
"action_url": "https://shop.example/herodesk/orders/1080/cancel",
"payload": {"order": 1080, "reason": "customer request"},
"inputs": {"days": "14", "reason": "bug"},
"widget_id": 6,
"conversation_id": 17,
"contact_email": "customer@example.com",
"agent": {"id": 1, "email": "agent@yourcompany.com"},
"context": { "…": "only with extended context" }
}
- Action requests are signed and authorised exactly like content requests (same headers).
request_idis unique per click and identical to theX-Herodesk-Request-Idheader. If your system receives the same id twice, it should not run the action again. This prevents, for example, a double refund.inputscontains the form values (see Action forms), or{}when there is no form.
What your system must answer
HTTP 200 (any 2xx status) with JSON:
{"status": "success", "message": "Order #1080 was cancelled.", "refresh": true}
status: exactly"success"is shown as success (green). Anything else is shown as a failure (red).message: a short plain text shown to the agent. Max 500 characters, HTML tags are removed. If you leave it out, the agent sees "Done."refresh(optional):truereloads the widget afterwards.
Anything else (another HTTP status, no JSON, a redirect, a timeout after 30 seconds or an unreachable server) is shown as "The action could not be completed."
Action forms (Pro)
To ask the agent for values before running an action, put the button and the form fields inside a <fieldset>. When the button is clicked, the values of the named fields in the same fieldset are sent as inputs:
<fieldset>
<legend>Extend trial</legend>
<label>Days <input type="number" name="days" min="1" max="30" value="14" required></label>
<label>Reason
<select name="reason" required>
<option value="">Choose…</option>
<option value="bug">Bug in product</option>
<option value="sales">Sales request</option>
</select>
</label>
<label><input type="checkbox" name="notify" checked> Notify customer</label>
<button class="btn btn-primary btn-sm"
data-hd-action-url="https://shop.example/herodesk/trial/extend"
data-hd-payload='{"account":"acc_9"}'>Extend trial</button>
</fieldset>
- Field types: text, number, date, email, tel, url, checkbox, radio, dropdowns (
select) and multi-line text (textarea). - Validation:
required,min,max,stepandmaxlengthare checked before anything is sent. If a field is invalid, the browser points at it and nothing is sent. - How values arrive:
- Text, numbers, dates and dropdowns: as text (
"14") - A checkbox without a
valueattribute:trueorfalse - A checkbox with a
valueattribute: that value when ticked, otherwisenull - Fields whose name ends in
[](for example a group of checkboxes nameditems[]): a list of the ticked values - A radio group with nothing selected:
null
- Text, numbers, dates and dropdowns: as text (
- Limits: at most 50 fields, each at most 2000 characters.
- Not allowed: password, hidden and file fields are turned into plain text fields. Put fixed values in
data-hd-payloadinstead. - The browser's autofill is always off in these fields, so agents' saved details never end up in your form.
- While the action runs, the fields are locked.
Who can run actions (Pro)
In the widget settings, choose who may use action buttons:
- Everyone who can see the conversation (default)
- Admins only
- Admins and selected teams
Admins can always run actions. The setting is enforced on Herodesk's server, not only in the browser, so an agent who is not allowed cannot run an action in any other way. A disabled widget refuses all actions.
For finer rules, such as "only tier 2 may refund more than 500 DKK", let your own system decide: it receives the agent's id and e-mail, and with extended context also the agent's role and teams.
Verifying requests
Signing secret
When you set a signing secret, every request (content and actions) carries two extra headers:
X-Herodesk-Timestamp: the time of the request in Unix secondsX-Herodesk-Signature:sha256=followed by an HMAC-SHA256 of timestamp + "." + the raw request body, using your secret as key
Your system should reject a request when the signature does not match or the timestamp is more than 5 minutes old, and compare signatures in constant time. Always use the raw body exactly as received, not a re-encoded version.
PHP:
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_HERODESK_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_HERODESK_SIGNATURE'] ?? '') || abs(time() - (int)$timestamp) > 300) {
http_response_code(401);
exit;
}
Node.js (Express):
const crypto = require('crypto');
app.post('/herodesk/widget', express.raw({ type: 'application/json' }), (req, res) => {
const timestamp = req.get('X-Herodesk-Timestamp') || '';
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(timestamp + '.' + req.body).digest('hex');
const given = req.get('X-Herodesk-Signature') || '';
const valid = given.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
&& Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
if (!valid) return res.status(401).end();
const data = JSON.parse(req.body);
// …
});
Authorization header
If your endpoint expects an API key, for example behind an API gateway, enter it in the Authorization header field. It is sent as the Authorization header on every request. The value is stored encrypted and never shown again in full (the developer tools show Bearer ********).
Request ids
Every request carries an X-Herodesk-Request-Id header. It appears in the widget's request log and, if you log it, in your own logs. Include it when you contact our support about a problem.
Developer tools
Admins find the developer tools below the Save button on the widget's settings page. They use the saved settings, so save your changes first.
- Send a test request: enter a conversation id (or leave it empty to use your most recent conversation) and click "Send test request". You see:
- the HTTP status, how long it took, which conversation was used and the request id
- the exact request: address, all headers (the Authorization value masked), the body in readable form and the exact body as sent (the bytes the signature is calculated over, useful when debugging signature checks)
- the raw response (first 20 KB)
- the result exactly as agents will see it, at panel width (action buttons are disabled in previews)
- Preview JSON: paste a response and click "Render preview" to see how it looks without calling your endpoint. Great for designing HTML.
- Recent requests: the last 50 requests from the past 7 days (panel loads, actions and tests) with time, type, result (HTTP status or error), duration, address (without query string), user and request id. "Clear" empties the list.
Security checklist
What Herodesk protects automatically
- Your HTML can never run code in Herodesk or reach agents' sessions. It is cleaned, shown in an isolated frame without JavaScript and restricted by a strict security policy.
- Fake overlays, login forms and hidden tracking tricks are removed.
- Herodesk only calls public addresses, never follows redirects and only calls action URLs on your endpoint's own address.
- Agents' access to the conversation is checked on every request. Actions also check the plan, the widget's status and "Who can run actions".
- Secrets are stored encrypted and never shown.
What you must do
- Always HTML-escape data your own customers can write (names, addresses, order notes, reviews) before putting it in your HTML. Otherwise someone could type markup, including a fake action button, into an order note. Herodesk's cleaning protects Herodesk, but cannot tell your intended markup from markup typed into your data.
- Treat every action URL like a public API: verify the signature, check that the agent may do this, validate the payload and inputs, and ignore repeated request ids.
- Use
data-hd-confirmfor destructive actions. - Don't put secrets or tokens in the HTML or payload. Agents can see the HTML.
Complete example endpoint (PHP)
One file serves both the widget content and its actions:
<?php
header('Content-Type: application/json');
$body = file_get_contents('php://input');
// (verify X-Herodesk-Signature here, see "Verifying requests")
$data = json_decode($body, true);
if (($data['type'] ?? null) === 'action') {
// Ignore repeated clicks/retries.
if (alreadyProcessed($data['request_id'])) {
echo json_encode(['status' => 'success', 'message' => 'Already done.']);
exit;
}
$order = (int)($data['payload']['order'] ?? 0);
if (!agentMayCancel($data['agent']['email'], $order)) {
echo json_encode(['status' => 'error', 'message' => 'You are not allowed to cancel this order.']);
exit;
}
cancelOrder($order, $data['inputs']['reason'] ?? null);
markProcessed($data['request_id']);
echo json_encode(['status' => 'success', 'message' => "Order #$order was cancelled.", 'refresh' => true]);
exit;
}
$order = findLatestOrder($data['contact_email']);
if ($order === null) {
echo json_encode(['headline' => 'Shop', 'foundItems' => 0, 'elements' => []]);
exit;
}
$note = htmlspecialchars($order->customerNote, ENT_QUOTES); // ALWAYS escape customer-written text
echo json_encode([
'headline' => 'Shop',
'foundItems' => 1,
'elements' => [[
'header' => 'Latest order',
'type' => 'html',
'content' => "<p><strong>Order #{$order->id}</strong> <span class=\"badge text-bg-success\">{$order->status}</span></p>"
. "<p class=\"small text-muted\">{$note}</p>"
. "<fieldset>"
. "<label>Reason <select name=\"reason\" required><option value=\"\">Choose…</option>"
. "<option value=\"customer\">Customer request</option><option value=\"stock\">Out of stock</option></select></label>"
. "<button class=\"btn btn-danger btn-sm\" data-hd-action-url=\"https://shop.example/herodesk/widget\""
. " data-hd-payload='{\"order\":{$order->id}}' data-hd-confirm=\"Cancel order #{$order->id}?\">Cancel order</button>"
. "</fieldset>",
]],
]);
Troubleshooting
Start with Send test request in the developer tools. It answers most "why doesn't my widget work" questions.
Messages in the widget
| Message | Meaning | What to do |
|---|---|---|
| Request failed (with details) | Herodesk could not reach your endpoint, or the request was refused: not public, unreachable, timeout or redirect. | Check that the Url is public, answers within 30 seconds and does not redirect. |
| JSON syntax error: … | Your endpoint answered, but not with valid JSON. | Check the raw response in the test tool. |
| The JSON input does not match the specifications | Valid JSON, but not the required structure (missing headline or elements, unknown type, HTML too large and similar). | Compare with the response format above and use "Preview JSON". |
| The JSON input contains HTML elements, but "Allow HTML content" is not enabled for this widget | HTML was sent, but the setting is off. | Switch on "Allow HTML content". |
| The JSON input contains HTML elements, which are available on the Herodesk Plus plan. | HTML was sent, but your plan does not include it. | Upgrade to Plus, or send only text, list, table and accordion elements. |
| Contact not found | The conversation has no contact. | Nothing to do. The widget needs a contact to look up. |
| Action buttons are available on the Herodesk Pro plan. | An action was used on a lower plan. | Upgrade to Pro. |
| Actions require "Allow HTML content" to be enabled for this widget. | Buttons live in HTML, and HTML is off. | Switch on "Allow HTML content". |
| You are not allowed to run actions in this widget. | "Who can run actions" excludes this agent. | Ask an admin to adjust the setting or the agent's teams. |
| The action URL must use the same address (scheme, host and port) as the widget URL. | The button points at another address (another host, a subdomain, http instead of https or another port). | Point the button at your endpoint's own address. |
| The action payload must be valid JSON of at most 8 KB. | data-hd-payload is broken or too large. | Fix the JSON in the button. |
| The form fields could not be sent. Check that there are at most 50 named fields of at most 2000 characters each. | Too many or too long form fields. | Reduce the form. |
| The action could not be completed. | The action URL did not answer correctly (non-2xx status, no JSON, timeout, redirect or unreachable). | Check your action endpoint and the request log. |
| Done. | The action succeeded, but your endpoint sent no message. | Send a message in the response. |
Messages on the settings page
| Message | What to do |
|---|---|
| The display name can only contain letters, numbers, spaces and the following characters: _ - & | Remove other characters, for example parentheses. |
| The address must point to a public server. | Use a public address, not an internal or local one. |
| Signing secret should contain at least 16 characters. | Use a longer secret. |
| The Authorization header must be a single line of plain text. | Remove line breaks and special characters. |
| Choose at least one team. | Select a team, or choose another "Who can run actions" option. |
Frequently asked questions
Will my existing widget break?
No. Nothing changes until an admin switches on the new options. Existing endpoints keep receiving the same three fields, plus an extra request id header they can ignore.
Can we run our own JavaScript in the widget?
No, by design. Action buttons and forms cover interactive needs without JavaScript, and Herodesk makes the calls.
Why are my images not showing?
They must use full https:// addresses, or be small embedded PNG, GIF or JPEG images. Images on Herodesk's own addresses are removed.
Why do my links open in a new tab?
Always, so the agent never leaves the conversation.
Why did my layout lose its positioning?
position, z-index, display and viewport units are removed. Use normal flow, the d-flex class or tables.
Can action buttons call a different domain, for example our API subdomain?
No. Actions must use exactly the endpoint's address. Route the action through your endpoint's host instead.
Does the AI agent or Copilot use the widget?
No. Content and buttons in the Custom widget are not used by the AI agent. For AI, use AI agent custom functions. To write data back into Herodesk (for example plan or MRR into custom fields), use the Herodesk API.
What happens if we downgrade?
The features that are not included in the new plan stop working immediately, with a clear message. See Plans and availability above.
How do I remove a signing secret or API key?
Empty the field and save.
How do we prevent the same action from running twice?
Use request_id. The same click always has the same id, so your system can ignore an id it has already processed.
Can I request other data types?
Contact us at support@herodesk.io.