Herodesk

https://help.herodesk.io/en/
Admin
Herodesk is a customer support platform that enables teams to manage conversations across multiple...
Tokens:16,742
Snippets:304
Trust Score:8.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example Using Template Variables

Source: https://help.herodesk.io/en/57-custom-prompting-your-ai-agent

This example demonstrates how to use template variables to personalize greetings. It includes a fallback for when the customer's first name is unavailable.

```text
- Always greet the customer by name: "Hi {{contact.firstname}}, how can I help you today?"
- If the first name is unavailable, use a warm generic greeting instead.
```

--------------------------------

### Boot Herodesk Widget with Pre-filled Message

Source: https://help.herodesk.io/en/53-javascript-api

Pre-fill the chat input field with a message during the widget boot process. This is useful for guiding users to specific topics.

```javascript
Herodesk('boot', {
  email: "john@example.com",
  firstname: "John",
  auth_token: "a1b2c3d4e5f6...",
  message: "I need help with order #12345"
 });
```

--------------------------------

### Quick Reply Webhook Payload Example

Source: https://help.herodesk.io/en/18-how-to-use-webhooks-with-quick-replies

This is an example of the JSON payload sent to a webhook when a quick reply is used. It includes event details and the associated message payload.

```json
{
  id: 1,
  name: "Name of your webhook",
  object: {
    type: "message",
    data: {
      ... payload of message
    }
  }
}
```

--------------------------------

### Webhook Payload Example

Source: https://help.herodesk.io/en/19-how-to-use-webhooks-with-rules

This is an example of the JSON payload that can be sent when a Herodesk rule triggers a webhook. It includes an ID, the custom payload, and details about the related object.

```json
{
  id: 1,
  payload: "the payload you added in the rule",
  object: {
    type: ... the related object, can be conversation, message or contact,
    data: {
      ... payload of related object
    }
  }
}
```

--------------------------------

### Generate Chat Auth Token (Server-Side)

Source: https://help.herodesk.io/en/53-javascript-api

Use this GET request from your backend to generate a secure hash for contact identity verification. Ensure your API key is included in the Authorization header. This token is then passed to the frontend.

```http
GET https://api.herodesk.io/v1/contacts/chat-auth-token?email=john@example.com
Authorization: Bearer YOUR_API_KEY
```

```http
GET https://api.herodesk.io/v1/contacts/chat-auth-token?id=123
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Generate Chat Auth Token (Server-Side)

Source: https://help.herodesk.io/en/53-javascript-api

Make a GET request from your backend to the Herodesk API to generate a secure hash for contact identity verification. This token is then passed to the chat widget on the frontend.

```APIDOC
## GET /v1/contacts/chat-auth-token

### Description
Generates a secure authentication token for a contact to enable automatic sign-in to the Herodesk live chat widget.

### Method
GET

### Endpoint
`https://api.herodesk.io/v1/contacts/chat-auth-token`

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address of the contact.
- **id** (integer) - Required - The ID of the contact.

#### Headers
- **Authorization** (string) - Required - Bearer YOUR_API_KEY

### Response
#### Success Response (200)
- **contact_id** (integer) - The unique identifier for the contact.
- **email** (string) - The email address of the contact.
- **name** (string) - The name of the contact.
- **auth_token** (string) - The generated authentication token for the chat widget.

### Request Example
```
GET https://api.herodesk.io/v1/contacts/chat-auth-token?email=john@example.com
Authorization: Bearer YOUR_API_KEY
```

### Response Example
```json
{
  "contact_id": 123,
  "email": "john@example.com",
  "name": "John Doe",
  "auth_token": "a1b2c3d4e5f6..."
}
```
```

--------------------------------

### Herodesk('boot', options)

Source: https://help.herodesk.io/en/53-javascript-api

Initializes the Herodesk widget and boots it with contact details and authentication token. This should be placed before the Herodesk chat script loads.

```APIDOC
## Herodesk('boot', options)

### Description
Initializes the Herodesk widget with contact details and an optional authentication token. This function should be called before the main Herodesk chat script is loaded.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (String) - Required - Contact's email address.
- **firstname** (String) - Optional - Contact's first name.
- **lastname** (String) - Optional - Contact's last name.
- **auth_token** (String) - Optional* - HMAC-SHA256 auth token for automatic verification. If omitted or invalid, standard email verification will be used.
- **message** (String) - Optional - Pre-fills the chat input with this message.
- **z_index** (String) - Optional - Custom z-index for the widget iframe (default: auto).

### Request Example
```javascript
Herodesk('boot', {
  email: "john@example.com",
  firstname: "John",
  lastname: "Doe",
  auth_token: "a1b2c3d4e5f6..."
});
```

### Response
This method does not return a value directly but initializes the widget.

### Error Handling
If `auth_token` is omitted or invalid, the contact will not be verified automatically and will proceed with the standard email verification flow.
```

--------------------------------

### Boot Herodesk Widget with Contact Details

Source: https://help.herodesk.io/en/53-javascript-api

Initialize the Herodesk widget with contact information and an authentication token. This script should be placed before the Herodesk chat script loads.

```javascript
window.Herodesk = window.Herodesk || function() {
  (window.Herodesk.q = window.Herodesk.q || []).push(arguments);
 };


Herodesk('boot', {
  email: "john@example.com",
  firstname: "John",
  lastname: "Doe",
  auth_token: "a1b2c3d4e5f6..."  // auth_token from Step 1
 });
```

--------------------------------

### Herodesk('show')

Source: https://help.herodesk.io/en/53-javascript-api

Opens the chat widget programmatically.

```APIDOC
## Herodesk('show')

### Description
Opens the chat widget programmatically.

### Method
Herodesk

### Endpoint
N/A (JavaScript function call)

### Parameters
None

### Request Example
```javascript
Herodesk('show');
```

### Response
This method does not return a value directly but controls the widget's visibility.
```

--------------------------------

### Boot Herodesk Widget with Custom z-index

Source: https://help.herodesk.io/en/53-javascript-api

Set a custom z-index for the Herodesk widget iframe to control its stacking order on the page.

```javascript
Herodesk('boot', {
  z_index: 500
 });
```

--------------------------------

### SaaS Support Desk Prompting

Source: https://help.herodesk.io/en/57-custom-prompting-your-ai-agent

Implement empathy first and a structured troubleshooting style for technical issues. Direct enterprise customers to their account managers for billing.

```plaintext
- Always begin your response by acknowledging the customer's feeling or situation before offering a solution.
- Use phrases like "I understand how frustrating that must be" or "I'm sorry to hear that".
- Keep the empathy brief (one sentence), then move to the solution.
```

```plaintext
- For technical issues: respond with a short checklist (max 5 items).
- If tool data is insufficient: ask for the missing input and stop.
```

```plaintext
- We offer a 30-day money-back guarantee on all plans.
- Enterprise customers ({{contact.email}} ending in a company domain) should be directed to their dedicated 
account manager for billing questions.
- Always link to our status page (from website search) when customers report outage-related issues.
```

--------------------------------

### Check Widget Readiness and Show Chat

Source: https://help.herodesk.io/en/53-javascript-api

This Javascript code checks if the Herodesk widget is ready and not currently visible before initiating the 'show' command. This prevents redundant calls and ensures the widget is in the correct state.

```javascript
// Check if the widget is ready before showing
if (Herodesk.isReady && !Herodesk.isVisible) {
 Herodesk('show');
}
```

--------------------------------

### Personalized Greeting and Brand Focus Prompting

Source: https://help.herodesk.io/en/57-custom-prompting-your-ai-agent

Customize greetings with customer names and prioritize specific brands in product recommendations. Use a generic greeting if the name is unavailable.

```plaintext
- Always address the customer by their first name ({{contact.firstname}}) in the greeting.
- If the first name is unavailable: use a warm generic greeting instead.
- Use the name naturally, not repeatedly — once at the start is enough.
```

```plaintext
- When recommending products: prioritize products from "Nordic Living" when relevant to the customer's request.
- If Nordic Living does not have a matching product: recommend the best alternative from other brands.
- Do not force brand recommendations when they are clearly not relevant.
```

--------------------------------

### E-commerce Sales and Support Prompting

Source: https://help.herodesk.io/en/57-custom-prompting-your-ai-agent

Combine these blocks for a sales-focused agent. Ensure mentions are natural and brief, and avoid mentioning campaigns during support issues.

```plaintext
- When customers browse or ask about products: mention our Summer Sale — 20% off 
all swimwear and outdoor furniture until August 31st.
- Keep the mention natural and brief — do not repeat it in every message.
- If the customer is asking about a support issue: do not mention the campaign.
```

```plaintext
- When recommending a product: also suggest one complementary or higher-tier item.
- Frame the suggestion naturally as a helpful tip, not a hard sell.
- If the customer declines or shows no interest: do not push further.
```

```plaintext
- Do not recommend products that are out of stock or unavailable.
- If a requested product is out of stock: let the customer know and suggest an available alternative.
- When stock is low: mention it so the customer can act quickly.
```

--------------------------------

### Add Live Chat to Website

Source: https://help.herodesk.io/en/20-setup-a-new-live-chat-channel

Copy this script tag and add it to your website's source code, preferably near the closing </body> tag, to integrate the Herodesk Live chat widget.

```html
<script src="https://widget.herodesk.io/widget.js" defer></script>
```

--------------------------------

### Event Callbacks

Source: https://help.herodesk.io/en/53-javascript-api

Register callbacks to respond to various Herodesk widget events.

```APIDOC
## Event Callbacks

Register callbacks to respond to widget events.

### Herodesk('onShow', callback)

#### Description
Fires when the chat widget is opened (by user click or programmatic show).

#### Parameters
- **callback** (Function) - The function to execute when the widget is shown.

#### Request Example
```javascript
Herodesk('onShow', function() {
 console.log('Chat widget opened');
});
```

### Herodesk('onHide', callback)

#### Description
Fires when the chat widget is closed (by user click or programmatic hide).

#### Parameters
- **callback** (Function) - The function to execute when the widget is hidden.

#### Request Example
```javascript
Herodesk('onHide', function() {
 console.log('Chat widget closed');
});
```

### Herodesk('onUnreadCountChange', callback)

#### Description
Fires when the number of unread conversations changes. Receives the new count as a parameter.

#### Parameters
- **callback** (Function) - The function to execute, receiving the unread count as an argument.

#### Request Example
```javascript
Herodesk('onUnreadCountChange', function(count) {
 console.log('Unread conversations:', count);
});
```

### Herodesk('onUserEmailSupplied', callback)

#### Description
Fires when a contact's email is identified, either through pre-authentication (`boot` with `auth_token`) or when the user manually enters their email in the widget's contact form.

#### Parameters
- **callback** (Function) - The function to execute when the user's email is supplied.

#### Request Example
```javascript
Herodesk('onUserEmailSupplied', function() {
 console.log('User email has been supplied');
});
```
```

--------------------------------

### Show Herodesk Chat Widget Programmatically

Source: https://help.herodesk.io/en/53-javascript-api

Open the Herodesk chat widget interface using a JavaScript call.

```javascript
Herodesk('show');
```

--------------------------------

### Herodesk onShow Event Callback

Source: https://help.herodesk.io/en/53-javascript-api

Register a function to be executed when the Herodesk chat widget is opened, either by user interaction or programmatically.

```javascript
Herodesk('onShow', function() {
 console.log('Chat widget opened');
});
```

--------------------------------

### Herodesk('showConversation', id)

Source: https://help.herodesk.io/en/53-javascript-api

Opens a specific conversation by its ID. This method only works after the widget has loaded and the contact has been identified, and the conversation must belong to the current contact.

```APIDOC
## Herodesk('showConversation', id)

### Description
Opens a specific conversation by its ID. This method requires the widget to be loaded and the contact to be identified. The conversation ID must belong to the current contact.

### Method
Herodesk

### Endpoint
N/A (JavaScript function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **id** (Number) - Required - The ID of the conversation to open.

### Request Example
```javascript
Herodesk('showConversation', 231);
```

### Response
This method does not return a value directly but controls which conversation is displayed in the widget.

### Note
Attempting to open another contact's conversation will be rejected.
```

--------------------------------

### Herodesk Javascript API Methods

Source: https://help.herodesk.io/en/53-javascript-api

Control the Herodesk live chat widget programmatically and listen to events using the Herodesk function. These methods should be called after the widget script has loaded.

```APIDOC
## Herodesk Function

### Description
Provides methods to control the Herodesk widget programmatically and listen to events. Call these after the widget script has loaded.

### Usage
`Herodesk(command, payload)`

### State Properties
These read-only properties reflect the current widget status:

- **Herodesk.isBooted** (boolean): `true` after the `boot` command is processed with valid parameters.
- **Herodesk.isReady** (boolean): `true` when the widget is fully loaded and ready to accept commands.
- **Herodesk.isVisible** (boolean): `true` when the chat panel is open, `false` when closed.

### Example
```javascript
// Check if the widget is ready before showing
if (Herodesk.isReady && !Herodesk.isVisible) {
 Herodesk('show');
}
```
```

--------------------------------

### Herodesk onUserEmailSupplied Event Callback

Source: https://help.herodesk.io/en/53-javascript-api

Register a function to be executed when the contact's email address is identified, either via pre-authentication or manual entry in the widget.

```javascript
Herodesk('onUserEmailSupplied', function() {
 console.log('User email has been supplied');
});
```

--------------------------------

### Herodesk('hide')

Source: https://help.herodesk.io/en/53-javascript-api

Closes the chat widget programmatically.

```APIDOC
## Herodesk('hide')

### Description
Closes the chat widget programmatically.

### Method
Herodesk

### Endpoint
N/A (JavaScript function call)

### Parameters
None

### Request Example
```javascript
Herodesk('hide');
```

### Response
This method does not return a value directly but controls the widget's visibility.
```

--------------------------------

### Show Specific Herodesk Conversation by ID

Source: https://help.herodesk.io/en/53-javascript-api

Open a particular conversation within the Herodesk widget, identified by its unique ID. This requires the widget to be loaded and the contact identified.

```javascript
Herodesk('showConversation', 231);
```

--------------------------------

### Shopify Liquid Theme Code for Herodesk Live Chat

Source: https://help.herodesk.io/en/50-how-to-set-up-live-chat-on-shopify-markets

Add this code to your Shopify liquid theme file. It dynamically assigns a Herodesk channel ID based on the visitor's country code, ensuring the correct language or region-specific chat is displayed. Replace 'XXX' with your actual Herodesk channel IDs.

```liquid
{% liquid
  assign country = localization.country.iso_code
    if country == 'DE'
        assign herodesk_wid = 'XXX'      # Germany
          elsif country == 'NO'
              assign herodesk_wid = 'XXX'      # Norway
                elsif country == 'DK'
                    assign herodesk_wid = 'XXX'      # Denmark
                      elsif country == 'SE'
                          assign herodesk_wid = 'XXX'      # Sweden
                            else
                                assign herodesk_wid = 'XXX'      # Default (ENG / other countries)
                                  endif
%}
<script src="https://cdn.herodesk.io/livechat.js?wid={{ herodesk_wid }}" defer></script>
```

--------------------------------

### Retrieve POST Body Parameters in PHP

Source: https://help.herodesk.io/en/14-how-to-set-up-a-custom-widget

Use this PHP code to access the JSON payload sent by Herodesk when a conversation is opened. Ensure your script processes this data correctly.

```php
$data = json_decode(file_get_contents('php://input'));
```

--------------------------------

### Herodesk onUnreadCountChange Event Callback

Source: https://help.herodesk.io/en/53-javascript-api

Register a function to be executed whenever the number of unread conversations changes. The new count is passed as an argument to the callback.

```javascript
Herodesk('onUnreadCountChange', function(count) {
 console.log('Unread conversations:', count);
});
```

--------------------------------

### Herodesk onHide Event Callback

Source: https://help.herodesk.io/en/53-javascript-api

Register a function to be executed when the Herodesk chat widget is closed, either by user interaction or programmatically.

```javascript
Herodesk('onHide', function() {
 console.log('Chat widget closed');
});
```
Tokens:
Raw