[Sugester V2 EN](https://sugester.intum.pl/kb/sugester-v2-en.md) / [Helpdesk / Tickets](https://sugester.intum.pl/kb/sugester-v2-en/helpdesk.md)

# [Helpdesk - widget (embedding on the page)](https://sugester.intum.pl/kb/sugester-v2-en/helpdesk-widget-embedding-on-the-page.md)

## 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:

```html
<!-- 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:

```javascript
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:

```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:

```javascript
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");
```