Helpdesk - widget (embedding on the page)

Widget - embedding on the page

The widget allows customers to submit tickets directly from your website or application.

Where to find the widget code?

1. Go to Helpdesk → Desks
2. Click on the desk name (e.g., “Technical Support”)
3. At the bottom of the page, you will find the Widget Code section with the ready-to-copy code

How to embed the widget?

Copy the code and paste it on your page before the </body> tag:

<!-- Intum Helpdesk Widget START -->
<link rel="stylesheet" href="https://your-domain.sugester2.pl/helpdesk/desks/widget.css">
<div id="intum-helpdesk-widget"></div>
<script>
  var IntumHelpdeskWidget = {
      account_url: "https://your-domain.sugester2.pl",
      desk_token: "YOUR_DESK_TOKEN",
      locale: "en"
  };
</script>
<script src="https://your-domain.sugester2.pl/helpdesk/desks/widget.js"></script>
<!-- Intum Helpdesk Widget END -->

Widget operation modes

The widget can operate in two modes:

1. New ticket form only

If you do not pass client_external_id, the customer will only see the form to submit a new ticket. They will not be able to view their previous tickets.

2. Client panel with a list of tickets

If you pass client_external_id, the customer will see:

• A list of their previous tickets (“My Tickets”)
• The ability to click on a ticket to see details and comments
• A “+ New Ticket” button

For this mode to work, you must:

1. Enable signature verification in the desk settings
2. Pass a valid signature in the widget configuration
3. Ensure that tickets have the same client_external_id assigned

Passing client data

If you know the logged-in user’s data, you can pass it to the widget:

var IntumHelpdeskWidget = {
    account_url: "https://your-domain.sugester2.pl",
    desk_token: "YOUR_TOKEN",
    // Client data (company)
    client_external_id: "CRM-123",
    client_email: "company@example.com",
    client_name: "Company Name Ltd.",
    // User data (person)
    user_external_id: "USR-456",
    user_email: "john.doe@company.com",
    user_name: "John Doe",
    user_phone: "+48123456789",
    // Signature (required when verification is enabled)
    signature: "abc123...",
    locale: "en"
};

This way:

• The form will be pre-filled
• The ticket will be automatically linked to the client in CRM
• The client will see their previous tickets (if signature verification is enabled)

Test page

Each desk has a test page where you can try the widget without embedding it on an external page. In the desk view, click the Test button.

Widget security (HMAC)

To enhance security, you can enable HMAC signature verification in the desk settings. Then, each request from the widget must include a valid signature.

Important: Signature verification is required for the client to view their previous tickets. Without it, only the new ticket form is visible.

How does HMAC work?

1. In the desk settings, enable Require Signature
2. The system will generate a secret key (secret_key)
3. On your page, calculate the signature from the client data and the secret key
4. Pass the signature in the signature parameter

Example in Ruby:

params = {
  client_email: "john@example.com",
  client_external_id: "CRM-123",
  user_email: "user@company.com"
}
data = params.select { \|k,v\| v.present? }.sort.map { \|k,v\| "#{k}=#{v}" }.join("&")
signature = OpenSSL::HMAC.hexdigest("sha256", secret_key, data)

Example in Node.js:

const crypto = require("crypto");
const params = { client_email: "john@example.com", client_external_id: "CRM-123" };
const data = Object.entries(params).filter(([k,v]) => v).sort().map(([k,v]) => k+"="+v).join("&");
const signature = crypto.createHmac("sha256", secretKey).update(data).digest("hex");