1.1. Mailbox Setup - Microsoft / Office 365 Email Configuration

Office 365 (Exchange Online) email connections are now configured using the mail authentication flow instead of traditional IMAP and SMTP sending settings. Office 365 (Exchange Online) email is received and sent via Microsoft's API using oAUTH authentication. 

If you are migrating from existing IMAP and SMTP connections for your mailboxes, we recommend first disabling your old mailbox, then following the steps below to create a new mailbox connection.

Video Tutorial

Connecting an Office 365 Mailbox

Before beginning this process make sure that your browser is signed into the Office / Microsoft 365 mailbox that you wish to integrate with HelpSpot.

1. Navigate to Admin > Email Mailboxes
2. Select "Microsoft 365" from the menu
   
   
   
3. Enter the Account Name. This is the name that customers will see in emails sent from this account.
4. Next enter the Reply to Email Account This is the email address that maps to this box ie: support@mydomain.com
5. Click on the link to the HelpSpot email authentication service
   
6. This will open a new tab. Select Sign in with Microsoft.
   
   
   
7. Make sure that the email account listed on the permissions confirmation screen is the one that you want to integrate with HelpSpot.
   
   
   
8. Next copy your credentials from the screen displayed.
   
   
9. Enter the credentials provided back in your HelpSpot mailbox setup screen.
   
   
   
10. Set any other options as desired and then select "Add Mailbox" at the bottom.
11. Important! If you are using Office 365 for all of your mailboxes you will also need to go to Admin > Settings > Email Integration and select a configured mailbox your outgoing email in the "Send Outbound Email Via" setting.

Your Microsoft / Office 365 (Exchange Online) mailbox is now connected to HelpSpot.

1.2. Mailbox Setup - Microsoft Advanced (Self-Managed)

Self-Managed or "Advanced" Microsoft Mailboxes connect HelpSpot to Microsoft 365 email using a registered application within your organization's Microsoft Entra tenant. This type of connection is available to any commercial Azure customer, and is a requirement for strictly regulated environments, including Microsoft Government Cloud (GCC, GCC High, or DoD).

Register a Microsoft Entra Application

The first step is to register an application within your Enrta ID environment. Azure has many layers of security, roles, and permission scopes; this process will likely require an organizational Global Administrator.

1. From the Microsoft Entra landing page, navigate to Entra ID → App registrations in the left navigation (shortcut) then the New Registration button. 
   
   
2. Configure the registration:
   • Name: "HelpSpot Mail Integration" (or your preferred name)
   • Supported account types: "Single Tenant Only"
   • Redirect URI:
     • Platform: Web
     • URI: https://[your-helpspot-url]/admin/microsoft-custom/callback]]
       
       
       
       
3. Click Register
   
   
4. On the app overview page, note the:
   • Application (client) ID
   • Directory (tenant) ID
     
     
5. Create a client secret:
   • Go to Certificates & secrets → Client secrets → New client secret
   • Add a description and select an expiration period
   • Copy the secret value immediately (it won't be shown again)
     
     
6. Add API permissions:
   • Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions
   • Add these permissions:
     • Mail.Read
     • Mail.Send
     • Mail.ReadWrite
     • MailboxSettings.Read
     • User.Read
     • offline_access
     • openid
     • profile
       
       
       
       
7. Click Grant admin consent for [Your Organization]
   
   

Configure the HelpSpot Mailbox

1. In HelpSpot, Navigate to Admin → Email Mailboxes
2. Select Advanced Microsoft Mailbox
   
   
   
   
3. Fill in the basic mailbox information:
   • Mailbox Name: A descriptive name for this mailbox
   • Reply-To Email: The email address for this mailbox
4. Configure the Microsoft credentials:
   • Cloud Environment: Select your Microsoft cloud (Commercial, GCC, GCC High, or DoD)
   • Client ID: Paste the Application (client) ID from the app registration
   • Tenant ID: Paste the Directory (tenant) ID from the app registration
   • Client Secret: Paste the client secret value you copied earlier
     
     
     
     
     
5. Click Save
6. After saving, click Connect to Microsoft to authorize the mailbox
7. Sign in with a Microsoft account that has access to the mailbox you want to connect (using an "incognito" or "private" window is recommended)
8. Grant the requested permissions when prompted
9. You'll be redirected back to HelpSpot - verify the status shows Connected
   
   
   
10. Click Test Connection to verify the mailbox can read emails.
11. Set any other options as desired and then select "Add Mailbox" at the bottom.
    

    Your "Microsoft Advanced" mailbox is now connected to HelpSpot.

1.3. Mailbox Setup - Google G Suite and Gmail Email Configuration

Google G Suite and Gmail Email Connections are now configured using the mail authentication flow instead of traditional IMAP and SMTP sending settings. Google Suite email is received and sent via Google's API using oAUTH authentication. 

If you are migrating from existing IMAP and SMTP connections for your mailboxes, we recommend first disabling your old mailbox, then following the steps below to create a new mailbox connection.

Connecting an Google Suite Mailbox

Before beginning this process make sure that your browser is signed into the Google Suite mailbox that you wish to integrate with HelpSpot.

1. Navigate to Admin > Email Mailboxes
2. Select "Google" from the menu
   
   
   
   
3. Enter the Account Name. This is the name that customers will see in emails sent from this account.
4. Next enter the Reply to Email Account This is the email address that maps to this box ie: support@mydomain.com
5. Click on the link to the HelpSpot email authentication service
   
6. This will open a new tab. Select Sign in with Google.
   
   
   
7. Make sure that the email account listed on the permissions confirmation screen is the one that you want to integrate with HelpSpot. Also ensure that the bottom two checkboxes are checked if provided.
   
   
   
8. Next copy your credentials from the screen displayed.
   
   
9. Enter the credentials provided back in your HelpSpot mailbox setup screen.
   
   
10. Set any other options as desired and then select "Add Mailbox" at the bottom.
11. If you are setting up your default mailbox you will also want to got to Admin > Settings > Email Integration and select your new mailbox as the default sending option.

Your Google Suite / Gmail mailbox is now connected to HelpSpot.

1.4. Default Send From and Send Outbound Email Via Settings

Two email settings control how outgoing messages are sent and which mailbox is used by default when staff create requests from inside the workspace. One setting selects the default mailbox for new requests. The other setting controls the method used to send staff notification emails and the default sending method for IMAP mailboxes.

Both of these settings are accessed in Admin > Settings > Email Integration

Default Send From

Controls which mailbox is selected automatically when a staff member creates a new request from inside the workspace.

• Select an integrated mailbox for normal operation.
• Select "Do not send email" to prevent outbound email by default when a new request is created.

Send Outbound Email Via

Determines the method used to send staff notification emails and the default sending method for IMAP mailboxes.

• IMAP mailboxes are usually pared with SMTP settings selected here for a default sending behavior. You can choose to have custom SMTP settings per mailbox as well in the mailbox setup.
• API-based mailboxes, such as Google Mail and Microsoft 365, use their own API for sending email by default. If you use Google Mail or Microsoft 365, select one of your existing mailboxes to send staff notifications.

Change the settings

1. Go to Admin > Settings > Email Integration.
2. In the "Default Send From" dropdown, choose an existing mailbox or select "Do not send email" to disable outbound email by default.
3. In the "Send Outbound Email Via" dropdown, you have to options:
   1. Choose the mailbox to be used for sending staff notifications and for default IMAP outbound email.
   2. Select SMTP Servers to configure your own SMTP settings.
4. Save the changes.

Notes and troubleshooting

• If staff notifications are not being sent and you use Google Mail or Microsoft 365, confirm the mailbox is integrated and authorized, and that a mailbox is selected for staff notifications.
• If you use IMAP mailboxes, ensure the mailbox selected in "Send Outbound Email Via" is configured correctly and has outbound send permissions.
• To stop all outbound messages by default, set "Default Send From" to "Do not send email."
• After changing settings, you can use the Outbound Email Test button to test your settings.

1.5. What Happens When You Migrate to an OAuth-based Mailbox?

Introduction to OAuth Based Mailbox Migration

Migrating your mailbox to an OAuth-based system is an important step towards enhancing security and efficiency in your email operations. This process involves creating a new mailbox and subsequently disabling the old one. Understanding the implications of this migration is crucial for a seamless transition.

Effects of Migrating to an OAuth Based Mailbox

The migration to an OAuth-based mailbox entails several significant changes that affect how users interact with their emails and the portal. Here are the key impacts:

• Inaccessibility of Requests in the Old Mailbox: Following the migration, any requests made under the old mailbox cannot be accessed in the portal using the previous access key. This necessitates a process to either migrate or archive these requests for future access.

• Resetting of Secondary Portal Mailbox Assignments: Secondary portal mailbox assignments lose their configuration and need re-setup. This means updating the settings to ensure they point to the new oAuth-based mailbox, maintaining the flow of communication without disruptions.

• Triggers, Automation, and Mail Rules May Be Affected: If triggers, automation setups, and mail rules are configured to rely on the old mailbox ID, they will no longer function correctly with the new mailbox. It is essential to review and update these configurations to align with the new mailbox ID, ensuring that automated processes and rules continue to work as intended.

1.6. Troubleshooting O365 OAuth Mailboxes

This document provides troubleshooting guidance for HelpSpot Email Mailboxes connected to O365 email accounts. If you're experiencing trouble with mailflow or if you received an email error notification in HelpSpot, the tips below can help you identify and correct many common problems. 

Connectivity

To begin with, the Admin > Email Mailboxes page displays each mailbox's Last Successful Check timestamp. If this reflects the current time, it means connectivity to the email account is working. If the Last Successful Check reflects any timestamp more than 1-2 minutes old, it means that was the last time that HelpSpot was able to successfully connect to the email account. Stale Last Check times sometimes offer clues to the cause of such issues (new firewall rules applied at a known time, network changes affecting on-prem HelpSpot servers, etc.)

If you see stale Last Check times, the first recommendation for restoring connectivity is to regenerate the API token  from https://auth.helpspot.com. Make sure you use an incognito/private browsing window to prevent any account caching issues. Generate the token in an incognito window and paste it into your mailbox settings in HelpSpot to attempt reconnecting to the email account.

If the Last Check is already current or if it still isn't refreshing after generating a new API key, the next most-likely cause is that the HelpSpot services aren't running correctly.

Queue Worker Services

• Troubleshooting HelpSpot Cloud Queue Worker Services
• Troubleshooting On-Premise Queue Worker Services

Other Issues

Lastly, if the services are running and you're still not getting incoming mail, you can temporarily bump up your logging output to include the details of each mail check action. Follow these directions to enable debug logging.

Contact Support

If none of the above tips resolves your email issue, reach out to HelpSpot Support for further troubleshooting assistance. You can include your helpspot.log file (or email-related stack trace excerpts from it if it's very large) when you submit your request.

1.7. Troubleshooting Gmail OAuth Mailboxes

This document provides troubleshooting guidance for HelpSpot Email Mailboxes connected to Gmail email accounts. If you're experiencing trouble with mailflow or if you received an email error notification in HelpSpot, the tips below can help you identify and correct many common problems. 

Connectivity

To begin with, the Admin > Email Mailboxes page displays each mailbox's Last Successful Check timestamp. If this reflects the current time, it means connectivity to the email account is working. If the Last Successful Check reflects any timestamp more than 1-2 minutes old, it means that was the last time that HelpSpot was able to successfully connect to the email account. Stale Last Check times sometimes offer clues to the cause of such issues (new firewall rules applied at a known time, network changes affecting on-prem HelpSpot servers, etc.)

If you see stale Last Check times, the first recommendation for restoring connectivity is to regenerate the API token  from https://auth.helpspot.com. Make sure you use an incognito/private browsing window to prevent any account caching issues. Generate the token in an incognito window and paste it into your mailbox settings in HelpSpot to attempt reconnecting to the email account.

If the Last Check is already current or if it still isn't refreshing after generating a new API key, the next most-likely cause is that the HelpSpot services aren't running correctly.

Queue Worker Services

• Troubleshooting HelpSpot Cloud Queue Worker Services
• Troubleshooting On-Premise Queue Worker Services

Other Issues

Lastly, if the services are running and you're still not getting incoming mail, you can temporarily bump up your logging output to include the details of each mail check action. Follow these directions to enable debug logging.

Contact Support

If none of the above tips resolves your email issue, reach out to HelpSpot Support for further troubleshooting assistance. You can include your helpspot.log file (or email-related stack trace excerpts from it if it's very large) when you submit your request.

1.8. Troubleshooting Custom IMAP Mailboxes

This document provides troubleshooting guidance for HelpSpot Email Mailboxes connected to email accounts via IMAP/POP3 (on-prem Exchange, SendGrid, etc.). If you're experiencing trouble with mailflow or if you received an email error notification in HelpSpot, the tips below can help you identify and correct many common problems. 

Connectivity

To begin with, the Admin > Email Mailboxes page displays each mailbox's Last Successful Check timestamp. If this reflects the current time, it means connectivity to the email account is working. If the Last Successful Check reflects any timestamp more than 1-2 minutes old, it means that was the last time that HelpSpot was able to successfully connect to the email account. Stale Last Check times sometimes offer clues to the cause of such issues (new firewall rules applied at a known time, network changes affecting on-prem HelpSpot servers, etc.)

If you see stale Last Check times, the first recommendation for restoring connectivity is to verify all of the mail connection settings. To verify connectivity:

1. Navigate to Admin > Email Mailboxes.
2. Select the mailbox that has issues.
3. Click on the test mailbox button to test connectivity.
4. If an error is shown when testing connectivity follow the directions below. If no error is shown most likely the queue worker services are the issue.

If you have a connectivity error after testing the connection confirm the hostname, port numbers, and correct SSL/auth-type settings with your email/network administrator. For external/third-party email providers, search their documentation for IMAP/POP configuration information. If you have webmail access to the affected account, confirm you can log in using the username and password.

Queue Worker Services

• Troubleshooting HelpSpot Cloud Queue Worker Services
• Troubleshooting On-Premise Queue Worker Services

Other Issues

Lastly, if the services are running and you're still not getting incoming mail, you can temporarily bump up your logging output to include the details of each mail check action. Follow these directions to enable debug logging.

Contact Support

If none of the above tips resolves your email issue, reach out to HelpSpot Support for further troubleshooting assistance. You can include your helpspot.log file (or email-related stack trace excerpts from it if it's very large) when you submit your request.

1.9. Troubleshooting On-Premise Worker Services

Admin > Settings > Workers has actions to restart workers and clear any cache locks that might be preventing mail processing.

If your HelpSpot instance is hosted on-premise, you can check the status of the services directly on your HelpSpot server.

• For Windows servers, open Windows services and look for HelpSpotQueue and HelpSpotSchedule. They should both be set to automatic and should both be running.
• For Linux servers, you can run the command sudo systemctl status supervisor to get the status of the queue service processes (two by default). You will also want to check your crontab and make sure that the schedule:run command is correctly configured.

In either case, if the Windows services or Linux processes are missing or refuse to stay running, you can submit a support request for direct assistance to resolve those issues.

1.10. Troublshooting HelpSpot Cloud Worker Services

HelpSpot Cloud instances are monitored for issues with the worker services that handle queues and job scheduling. If you're finding mail related errors in the Failed Jobs or Error Log pages (under Admin > System), you can reach out to HelpSpot Support for further assistance.

1.11. Handling Large Email File Attachments

To properly handle large file attachments it is often necessary to modify settings in your HelpSpot, PHP.ini file and database configuration.

HelpSpot Settings

Admin->Settings->Email Integration->Max Attachment Size - This defaults to 10mb. If you need to handle larger sizes, you'll first need to increase this setting.

PHP.ini Values to Review

memory_limit - PHP may require more memory to import large files then it has available. Increasing this value will give PHP more memory to use. 60mb has proven to be a good value for this variable if you want to handle attachments up to about 10mb.

max_execution_time - The time PHP has to execute a script. If you're downloading large files from across the internet, you may need more time.

upload_max_filesize - The maximum size a file upload can be. This affects files staff try to upload to attach to emails.

post_max_size - The maximum size an HTTP POST request can be, this can limit the maximum size a file can be when uploading files to attach to emails.

upload_tmp_dir - The directory uploaded files are temporarily stored in during transmission. If no attachments of any size are able to be uploaded then this value may be unset or set to a directory which is not writable by the web server.

Database Settings

MySQL: max_allowed_packet - On MySQL, increase the max packet size to greater than the biggest files you expect to handle. This is done in the MySQL configuration file. See your MySQL documentation for specific instructions for your version.

IIS Settings

IIS has a maximum content length setting that can affect the ability to upload / attach files. Here's how you can check that:

1. Open IIS Manager.
2. Select the website that you want to configure.
3. Make sure you are in Features View per the button at the bottom of the manager.
4. Select Requests Filtering and open it by double-clicking the icon. The Request Filtering pane displays.
5. From the Actions pane on the right hand side of the screen click Edit Feature Settings... link. The Edit Request Filtering Settings window displays.
6. In the Request Limits section, enter the appropriate Maximum allowed content length (Bytes) and then click the OK button.
7. Restart IIS.

NGINX Settings

NGINX has a client_max_body_size that can prevent larger attachments if the value is set too low.

2.1. Setup for Mobile Applications

HelpSpot has both iOS (iPhone / iPad) and Android mobile applications available.

HelpSpot Requirements:

For HelpSpot, these require that:

1. You use HelpSpot version 4 or greater.
2. The Private API be enabled within the Admin > Settings > Web Services API configuration.

Login To Mobile App

Since the mobile app connects to your instance of helpspot you will need the URL of your helpspot site the first time you login to the mobile app.

1. Open the mobile app
2. Enter the URL to your helpspot instance. For example https://helpspot.yourdomain.com
3. Enter your username and password

If you encounter issues logging in. Visit our troubleshooting guide.

2.2. Troubleshooting

"HelpSpot Could Not Be Reached" error

There are a few possible reasons why HelpSpot may return the "HelpSpot could not be reached error:

1. HelpSpot's private API is not enabled
2. iOS/Android limitations in connecting over "https"
3. Server does not allow or support HTTP Basic Authorization

Private API

Please be sure to enable HelpSpot's Private API from within the Admin > Settings > Web Services API configuration.

HTTPS and SSL Certificates

If the private API is enabled and you continue to receive an error, you may have an SSL certificate configuration that supports too few secure protocols. For example, Apple's iOS version 9 may only support TLS1.2, but a web server's SSL certificate may only support or enable TLS1.0.

We suggest following these configurations for a secure and functional SSL configuration.

If you are curious about your site's SSL configuration, you can run it through this SSL Certificate tester, which will inform you of any potential issues in your SSL configuration.

Basic Authentication

HelpSpot's API's are authenticated against use HTTP Basic Authentication.

• Some servers may prevent this type of authentications, perhaps by removing an incoming request's Authorization header.
• Apache servers running PHP as fast-cgi will not pass basic authentication from Apache to PHP.
  
• Nginx users may find that the "auth_basic" setting has been used either in their Nginx configuration. A setting of "auth_basic off;" would prevent the HelpSpot mobile applications from being able to authenticate against HelpSpot.

3.1. Microsoft Entra / Azure SAML Authentication

Make sure the staff configured within HelpSpot have a "Black Box/LDAP/AD/SAML Username" setup matching their Office365 email addresses in their HelpSpot staff profiles.

You also may want to enable SAML Debugging before enabling SAML for the first time.

Microsoft Entra Setup

1. Go to https://entra.microsoft.com/#home and click on Identity > Applications > Enterprise applications.
2. We'll create a "non-gallery" application.
   1. Select "New Application"
   2. Select "Create your own application"
   3. Give the application a name, and keep the default option "Integrate any other application you don't find in the gallery"
3. After the app is created:
   1. Select single sign on and then choose SAML for the sign on type.
   2. Edit step 1 "Basic SAML Configuration" and enter an Identifier (Entity ID) found in HelpSpot Admin > Settings > Authentication > SAML2.0.
   3. Enter the Reply URL (Assertion Consumer Service URL) (also know as ASC URL) that is found in HelpSpot Admin > Settings > Authentication > SAML2.0
   4. Save your settings
4. Still within the application settings, head to Users and group and choose Add User to add users or role who may authenticate into HelpSpot

HelpSpot Setup

1. After completing the above, and saving the settings, step 3 on the SAML setup page should update with more information.
   1. Download the Federation Metadata XML file. In this file, you will find the <X509Certificate> tag. Copy the value that is between the <X509Certificate> and </X509Certificate> tags. Paste this value into Certificate field in HelpSpot Admin > Settings > Authentication > SAML2.0.
2. Move down to step 4 is the azure SAML setup page and copy the Login URL to the Login URL (SSO) in the HelpSpot SAML setup page.
3. Copy the Logout URL to the Logout URL (SLO) in the HelpSpot SAML setup page.
4. Copy the Azure AD Identifier to the Entity ID in the HelpSpot SAML setup page
5. Save your settings in HelpSpot and then head back to the Azure SAML setup page and validate your single sign-on with SAML

3.2. Google Suite SAML Authentication

3.3. Staff LDAP / Active Directory Authentication

LDAP (Lightweight Directory Access Protocol) allows you to authenticate staff members against an Active Directory or other LDAP-based directory. Follow these steps to configure LDAP authentication in your HelpSpot application.

Steps to Configure LDAP Authentication

1. Access the LDAP Configuration Settings

1. Log in to your HelpSpot admin dashboard.
2. Navigate to Admin in the top menu bar.
3. Click on Settings.
4. Click on Authentication,
5. Choose LDAP/Active Directory.

2. Enter LDAP Configuration Details

You will need to enter the following details in the LDAP/Active Directory section:

Username Prefix

• Example: uid= or cn=
• For OpenLDAP where a full dn is often required, enter 'uid=' or 'cn=' to allow you to form the full dn needed. Leave empty for Active Directory.

Account Suffix

• Example: @mydomain.local
• This is typically the domain name your Active Directory is associated with. It is not always needed depending on configuration. For OpenLDAP type configurations where a full dn is needed you'll often need to include a path like this with a leading comma: ,ou=Users,dc=mydomain,dc=local.

Base DN

• Example: DC=mydomain,DC=local
• The Base DN (Distinguished Name) is the starting point for your LDAP queries, defining where in the directory tree your users are located.

Domain Controller

• Example: dc01.mydomain.local
• Enter the hostname or IP address of your domain controller.

Use SSL

• Check this box if your LDAP server is configured to use SSL (LDAPS).

Use TLS

• Check this box if your LDAP server is configured to use TLS for secure communication.

Custom CA Certificate

• If your LDAP server requires a custom Certificate Authority (CA) certificate, provide the path to the certificate file here.

3.4. Two Factor Authentication (2fa) Support

Helpspot supports native 2fa authentication for staff members when using HelpSpot's internal authentication. To enable this option, follow these steps:

1. Navigate to your user preferences:
   
2. Select "Enable Two Factor Authentication"
   
3. You can then scan the displayed QR code with your authenticator app such as Google Authenticator, 1Password, Microsoft Authenticator or Authy. Alternatively, if you don't have a device that can scan QR codes you can manually enter the key in your authenticator app.
   
4. After doing this, enter the enter the code from your authenticator app to confirm the key. Two factor authentication will not be enabled on your account until the key is confirmed.

After enabling 2fa authentication you will be prompted to enter your login code whenever you authenticate to HelpSpot. Administrators can disabled 2fa authentication to unlock accounts.

Enabling 2fa will also disable basic authentication on the API. API keys will need to be used for any API interactions.

3.5. Black Box Authentication (agent login) with Active Directory

These instructions should work with most Active Directory installations, however, minor adjustments may need to be made to fit your exact setup.

• Download the Active Directory/PHP Helper library from http://adldap.sourceforge.net/
• Unpack the download and place the adLDAP library files (as of this writing, the 'adLDAP.php' file and the 'classes' and 'collections' directories) into the /custom_code folder of your HelpSpot installation.
• Open adLDAP.php in a text editor. Around line 82 there starts a few variables you'll need to modify so that an AD connection can be made to your AD server. You'll likely need to modify at least $accountSuffix , $baseDn, and $domainControllers variables. When finished save the file.
• Copy the file /custom_code/BlackBox-base.php to /custom_code/BlackBox.php
• Open BlackBox.php in a text editor. Replace the BlackBox function with this code (sample file also available at the bottom of this page):

  //include the class
  require_once("adLDAP.php");
  	
  function BlackBox($username, $password){
  	
  	//create the AD LDAP connection
  	$adldap = new adLDAP();
  
  	//authenticate a user
  	if ($adldap->authenticate($username,$password)){
  		return true;
  	}else{
  		return false;
  	}
  
  }
  

• Login to HelpSpot and go to Settings in the upper right hand corner. Make sure the 'Black Box Username' field contains your Active Directory username or you will not be able to login. Every other user must also have this field filled in or they will not be able to login. You don't need to enter them all right now though.
• Go to Admin->Settings and under 'Authentication' select 'Black Box'. Save the settings and Black Box/Active Directory authentication will be enabled. You should log out, if the system doesn't do it for you and attempt to login with your Active Directory username and password.

3.6. Black Box Authentication (agent login)

Black box authentication allows you to integrate your organizations authentication system with HelpSpot. Configuration requires only a few simple steps.

Summary: Steps to enable BlackBox Authentication

• Customize the BlackBox function in the file /custom_code/BlackBox-base.php to authenticate the username and password passed to it against your own authentication system.
• Rename BlackBox-base.php to BlackBox.php
• Confirm that your staff has the "Black Box Username" field set correctly in their accounts.
• Enable Black Box authentication in Admin->Settings

Customizing the BlackBox function

In the root of your installation there's a folder called /custom_code. Within that folder is the BlackBox-base.php file. This file contains the empty BlackBox function:

function BlackBox($username, $password){

	/* DO YOUR AUTHENTICATION HERE */

	return false;

}

Customize this function to do authentication against your internal system by using the username and password provided. Here is an example of the function customized to authenticate against a MySQL database: (some security procedures left out for clarity)

function BlackBox($username, $password){

       $dblink = mysql_connect('localhost', 'mysql_user', 'mysql_password');
       mysql_select_db('database', $dblink);
       
       $username = mysql_real_escape_string($username);
       $password = mysql_real_escape_string($password);

       $result = mysql_query("SELECT userid 
       						  FROM users 
       						  WHERE users = '$username' AND pass = '$password'", $dblink);
       $num_rows = mysql_num_rows($result);

       if($num_rows == 1){
			return true;
       }else{
			return false;
       }
}

Returning true will authenticate the user, while false denies access. Note that even after you return true, HelpSpot looks up the username to make sure the username is that of a valid HelpSpot user. If you have not assigned the username to any of your staff then authentication will still fail.

Enabling Black Box Authentication

Before enabling check each account account that will be impacted by this authentication changes to make sure they have "black blox username" set. If they do not, they will not be able to login.

Enabling Black Box authentication is a two step process. First you must rename the BlackBox-base.php file to BlackBox.php. Second, you must change the authentication type to Black Box [Admin->Settings]. After changing the setting you will likely have to login again at which point the login box should say "username" instead of "email".

HelpSpot Password

HelpSpot still requires a password for all accounts even though it's not used for your custom authentication. This is because HelpSpot will attempt to login against it's own internal authentication when your custom authentication returns false. This allows users to get into HelpSpot even if the custom function is not working correctly using their HelpSpot email and password.

3.7. Customer Portal LDAP/AD Authentication

LDAP (Lightweight Directory Access Protocol) allows you to authenticate users of your customer portal against an Active Directory or other LDAP-based directory. Follow these steps to configure LDAP authentication in your HelpSpot application.

Steps to Configure LDAP Authentication

1. Access the LDAP Configuration Settings

1. Log in to your HelpSpot admin dashboard.
2. Navigate to Admin in the top menu bar.
3. In the left-hand sidebar, expand Customer Tools and click on Portal.
4. Scroll down to the Portal Authentication Settings section and select LDAP/Active Directory from the Request History Login Type dropdown.

2. Enter LDAP Configuration Details

You will need to enter the following details in the LDAP/Active Directory section:

Username Prefix

• Example: uid= or cn=
• For OpenLDAP where a full dn is often required, enter 'uid=' or 'cn=' to all you to form the full dn needed. Leave empty for Active Directory.

Account Suffix

• Example: @mydomain.local
• This is typically the domain name your Active Directory is associated with. It is not always needed depending on configuration. For OpenLDAP type configurations where a full dn is need you'll often need to include a path like this with a leading comma: ,ou=Users,dc=mydomain,dc=local.

Base DN

• Example: DC=mydomain,DC=local
• The Base DN (Distinguished Name) is the starting point for your LDAP queries, defining where in the directory tree your users are located.

Domain Controller

• Example: dc01.mydomain.local
• Enter the hostname or IP address of your domain controller.

Use SSL

• Check this box if your LDAP server is configured to use SSL (LDAPS).

Use TLS

• Check this box if your LDAP server is configured to use TLS for secure communication.

Custom CA Certificate

• If your LDAP server requires a custom Certificate Authority (CA) certificate, provide the path to the certificate file here.

3.8. Black Box Portal Authentication (customer portal login)

Black box authentication allows you to integrate your organizations authentication system with HelpSpot. Configuration requires only a few simple steps.

Summary: Steps to enable BlackBox Authentication

• Customize the BlackBox function in the file /custom_code/BlackBoxPortal-base.php to authenticate the username and password passed to it against your own authentication system.
• Rename BlackBoxPortal-base.php to BlackBoxPortal.php
• Enable Black Box authentication in Admin->Settings->Portal->Request History Login Type

Customizing the BlackBox function

In the root of your installation there's a folder called /custom_code. Within that folder is the BlackBoxPortal-base.php file. This file contains the empty BlackBox function:

function BlackBoxPortal($username, $password){

	/* 
		DO YOUR AUTHENTICATION HERE 
		
		Here's an example of how to return a valid user:
		return "john.smith@company.com";
	*/

	return false;

}

Customize this function to do authentication against your internal system by using the username and password provided. Here is an example of the function customized to authenticate against a MySQL database: (some security procedures left out for clarity)

function BlackBoxPortal($username, $password){

       $dblink = mysql_connect('localhost', 'mysql_user', 'mysql_password');
       mysql_select_db('database', $dblink);

       $username = mysql_real_escape_string($username);
       $password = mysql_real_escape_string($password);

       $result = mysql_query("SELECT email FROM users WHERE users = '$username' AND pass = '$password'", $dblink);
       $num_rows = mysql_num_rows($result);

       if(mysql_num_rows($result) == 1){
              $row = mysql_fetch_assoc($result);
              //An email must be returned
              return $row['email']; 
       }else{
              return false;
       }
}

Returning an email will authenticate the user and show them any requests for that email, while false denies access.

3.9. SAML Debugging

** These notes are for self-hosted customers only. HelpSpot Cloud customers will need to contact support **

If you become locked out of your SAML authenticated HelpSpot server you can enable a debugging mode to use local accounts to login and change SAML settings.

1. Edit the .env file located in your HelpSpot directory
2. Change APP_DEBUG=true and save the file
3. In your browser navigate to https://myhelpspotsite.com/altlogin
4. You will then be presented with a local authentication form to temporarily authenticate to the admin area

3.10. SAML User Login Redirects to Portal Instead of Admin Workspace

When SAML authentication is enabled HelpSpot will search the "Black Box/LDAP/AD/SAML Username" field of the staff profiles to find a matching profile. If no matching profile is found, the user will be redirected back to the customer portal.

To correct this issue follow these steps:

1. Navigate to Admin > Staff  and select the staff member.
2. Update or add the correct "Black Box/LDAP/AD/SAML Username" value to that account. In most cases this will be the users email address.

4.1. HelpSpot Command Line Tool

Commands Available

HelpSpot 5 has some new commands available, along with most commands from HelpSpot 4.

HelpSpot includes an hs command that can be used to run or automate certain tasks.

Linux:

The hs command installed with HelpSpot is the command line utility. On Linux servers, you can run it using PHP:

# List the available commands and options:
php hs

Windows:

On Windows, you need to run the hs command using the PHP that comes with HelpSpot using Cmd or PowerShell, and let it know which configuration file to use:

C:\'Program Files (x86)'\helpspot\php\php.exe -c C:\'Program Files (x86)'\helpspot\php\php.ini C:\'Program Files (x86)'\helpspot\helpspot\hs

It might be easier to first "change directory" into the HelpSpot directory so these file paths are shorter:

cd C:\'Program Files (x86)'\helpspot\helpspot
..\php\php.exe -c ..\php\php.ini .\hs

For both Linux and Windows, running hs without any parameters will simply list out the available commands.

Command Details

Each command has a list of options you can pass to it. To see the details of available flags, use the -h flag:

php hs install -h
Description:
  Install HelpSpot.

Usage:
  install [options]

Options:
      --agree                                    Agree to HelpSpots License Terms
      --name[=NAME]                              Full Name (first name last name)
      --admin-email[=ADMIN-EMAIL]                Admin User Email Address

...and so on

Available Commands

Here are the commands available for HelpSpot:

• install
• portal-language-update
• update
• attachments:tofile
• automation:rules
• cache:clear
• config:convert
• mail:check
• portal:migrate
• request:delete
• request:delete-spam
• request:delete-trash
• report:logs
• scout:populate-index

install

This will guide you through installing HelpSpot. For installing without prompts, you can use the available flags to provide the needed details.

# Interactive
php hs install


# Or prefill some or all options
php hs install --agree --name="Jane Doe" --admin-email="jane@example.com" --password="secret" ...and so on

portal-language-update

Update language constants in template files to use lg() helper. This is only needed for legacy custom portal templates that used language constants without the helper when updated to HelpSpot 5.5.0+.

php hs portal-language-update --directory=custom_templates #Directory to process relative to public path

update

To update between HelpSpot 5 versions (e.g. 5.1.0 to 5.2.0), use the update command.

# Update with prompt
php hs update

# Update with no prompt
php hs update --yes

The update command is safe to run multiple times (don't worry about accidentally running it).

attachments:tofile

This command will allow you to save your file attachments from the database (the default location prior to HelpSpot version 4) to your server file system.

This command will delete file data from your database as it saves it to the disk. We highly suggest backing up your database before running this command.

# Prompted for attachment file path to use
php hs attachments:tofile

# Or provide the file attachment path:
php hs attachments:tofile --path=storage/documents

automation:rules

You can run all Automation Rules, or specific Automation Rules by their ID. Their ID is found within HelpSpot when viewing the list of Automation Rules.

# Run all automation rules
# Except those marked to run on a Custom Schedule
php hs automation:rules

# Run automation rule 1
# regardless of Custom Schedule setting
php hs automation:rules --id=1

# Run automation rule 1 and 2
# regardless of Custom Schedule setting
php hs automation:rules --id=1,2

cache:clear

HelpSpot uses some caching to save certain settings, configuration, and data to reduce database load. To clear the cache, you can run the following command:

php hs cache:clear

config:convert

When updating from HelpSpot 4 to HelpSpot 5, the config.php file can be converted to a .env file using this command:

# Assumes config.php file is present

# Create a .env file from config.php file values
php hs config:convert

# Print the contents of the converted configuration
# but do not create the .env file
php hs config:convert --dump

hs:announcement

Send a system announcement to all users or admins only.

php hs hs:announcement [options]

  --title[=TITLE]          The title of the announcement
  --message[=MESSAGE]      The message content
  --url[=URL]              Optional URL for the announcement
  --link-text[=LINK-TEXT]  Optional link text (defaults to "Learn more")
  --severity[=SEVERITY]    Severity level (info, warning, error, or success) [default: "info"]
  --admins                 Send only to admin users

mail:check

HelpSpot runs this command periodically via it's CRON task (Linux) or Scheduled Tasks (Windows).

This command fires off a queue job, which in turns checks configured/enabled mailboxes for new email.

You can check all Mailboxes, or specific Mailboxes by their ID. Their ID is found within HelpSpot when viewing the list of Email Mailboxes.

# Check all configured/enabled mailboxes
php hs mail:check

# Check mailbox id 1
php hs mail:check --id=1

# Check mailbox id 1 and 2
php hs mail:check --id=1,2

portal:migrate

This command will help move existing portals from the old HelpSpot 4 location to one appropriate for HelpSpot 5.

# Move portals, if it can
php hs portal:migrate

# Report on what changes the command would make
# but don't make the changes
php hs portal:migrate --dry-run

request:delete (-spam,-trash)

You can delete one specific request (and it's related data) by its ID:

# Delete request 1234
php hs request:delete --id=1234

You can delete all Spam as well, without using those requests to train the spam filter:

# Delete all spam, with prompt
php hs request:delete-spam

# Delete without prompting
php hs request:delete-spam --force

And you can delete requests in the Trash:

# No prompt, deletes trash.
# Does use the Trash Delete Delay setting
php hs request:delete-trash

report:logs

The report:logs command will export a CSV file of your helpspot request event logs to your data/documents/ directory.

php hs report:logs

scout:populate-index

Populate the search index with all requests. This is a resource-intensive process that can take upwards of 15 minutes. While processing, search is available, but results will be incomplete until the process finishes and all documents have been fully indexed.

php hs scout:populate-index 

# force rebuild
php hs scout:populate-index --force

4.2. How to Backup HelpSpot

HelpSpot stores all it's data in the database, this makes backing up HelpSpot very easy. To have a complete backup of all your data simply backup the database using standard database backup procedures. These will vary depending on which database system you use, though it's likely your system administrators are already doing it or can have it done easily.

Systems Using an Alternate Attachment Storage Location

For systems that handle many email attachments HelpSpot has a setting (Admin->Settings->System->Attachment Storage Location) to allow attachments to be stored on the servers disks rather than in the database. This is more efficient and makes backup of the database much easier because the size of the database is much smaller.

If your installation uses this feature you'll also need to backup the attachments which are on disk in order to have a complete backup.

HelpSpot Files

It's optional to backup the HelpSpot files themselves. You can always re-download them if you need to, but if you do want to backup the files be sure to do so in a binary safe manner as all the .PHP files in HelpSpot are binary.

Even if you don't backup all the files you may want to keep a backup of config.php which stores the database connection settings as a convenience in case a recovery is needed. This file is in the root HelpSpot folder.

Restoring

To restore your HelpSpot installation follow your databases standard restoration procedure. Restore the HelpSpot files (if necessary), replace config.php or rebuild it (if necessary) and your installation should be up and running.

Some database specific backup resources:

• MySQL: http://dev.mysql.com/doc/refman/5.0/en/backup.html
• Microsoft SQL Server: http://msdn.microsoft.com/en-us/library/ms187048.aspx
• PostegreSQL: http://www.postgresql.org/docs/8.1/static/backup.html

4.3. How to Move HelpSpot

How you move a HelpSpot installation is dependent upon how it was initially installed. The instructions differ based on if the installation was first installed manually or via the Windows Installer. Instructions for moving both types of installation methods are provided below.

Moving a Manually Installed Installation

Moving a manual installation is much like doing a backup. These instructions presume you've already setup a proper environment on the new server, PHP, database, web server, etc.

• Put the old system in maintenance mode (Admin->System Overview) to prevent any requests being created in there via email or portal form.
• Backup the database: How to Backup HelpSpot
• Restore the database on the new server (this presumes you're moving the database. If the database is not moving then skip this)
• Copy the HelpSpot files to the new server, be sure to move in a binary safe manner
• On the new server edit .env in the root HelpSpot folder to be sure it includes the proper database connection information and correct APP_URL for the new location
• On the new server setup the queue worker and cron jobs.

Moving a Windows Installer Installation

The easiest way to move an installation done via the Windows Installer is to use the installer again to re-install on the new server and then move the database.

• Run the Windows Installer on the new server, allow it to create a new empty database in SQL Server or MySQL. No need to run installer.php when it pops up.
• Place your old server into maintenance mode.
• Backup your old servers database
• Restore your database, overwriting the new one the installer just created

Other Considerations

Attachments Saved to Disk - If you've configured HelpSpot to save attachments to the file system (Admin->Settings->System->Attachment Storage Location), then you'll need to move those files as well and update the file path to them in the new servers settings.

Upgrading While Moving - If on the new server you're using a newer version of HelpSpot files than the old server was running then after the move you'll need to run installer.php to upgrade the HelpSpot database. This can only be done inside of major versions. You must use the documented upgrade process to move from v3 to v4 or v4 to v5.

4.4. Moving HelpSpot 5 Windows Installations

To move a windows installation from one server to another, first take an assessment of your current system environment.

• Database Platform: MySQL or SQL Server? - You can determine this by opening the .env file in your current environment and noting the DB_CONNECTION value
• Database Location: Application server or external? - You can determine this by opening the .env file in your current environment and noting the DB_HOST value. If the value is "localhost" or "127.0.0.1" then the database is co-located with the application server. If you have a connection to an external IP or DNS then the db is most likely external and won't need to be moved along with the application server.
• Web Server: Apache or IIS? - Determine if you are using IIS or Apache to host your helpspot instance. You may want to open the "IIS Manager" tool in windows to look for a helpspot site and check your helpspot install location to see if Apache has been installed.

Install HelpSpot on Your New Server

1. Follow the standard windows installation instructions as if you were installing a new server: https://support.helpspot.com/index.php?pg=kb.page&id=648. You can install the latest version of HelpSpot 5 even if your current installation is on an older version of HelpSpot 5. The moving process will also update your instance.
2. This guide will direct you to install HelpSpot using IIS and Microsoft SQL Server. If you determined above that you are using MySQL, you will need to modify your installation .env to connect to your mysql server. You will also need to enable the mysql extensions in your php.ini file.
3. It can be good to just login and make sure that you new server is all configured and functional before starting to move your data.

Migrate The Database

1. Place your old server in maintenance mode. This will prevent the old server from performing database changes during migration.
2. If you determined that your database location is on the Application server you will need to make a backup of that database and import it into your new database server. Standard MySQL or SQL Server backup and restore tools can be used. This article include links for database backup tool instructions (specific links at bottom): https://support.helpspot.com/index.php?pg=kb.page&id=315
3. Update the connection information in the .env file on you new server to connect to your migrated database. If your database server location is external your can simply update the connection information in the new server's env file with the parameters from your old server's .env.

Copy The Application Key

1. Copy the APP_KEY setting located .env file on you old server to your new server. This is needed to decrypt values in the migrated database.

Copy Files

1. Copy the files in these locations on your old installation to the corresponding location on your new installation. (Locations listed here are relative to the directory your .env file is located in):

   helpspot/storage/*
   helpspot/public/custom_code/*
   helpspot/public/custom_templates/*
   helpspot/helpspot/custom_pages

2. If you have created a custom language pack you will need to copy that language pack over.
3. If you have created secondary portals, those portal directories will need to be copied over.

Update HelpSpot

1. Open a command prompt on your new server and cd to your helpspot directory: cd c:\inetpub\wwwroot\helpspot
2. Run the helpspot update command: C:\php\php.exe hs update

This will move your HelpSpot installation. You may need to make DNS and webserver binding and certificate changes to direct users to the new location.

4.5. Removing virtual directory in HelpSpot on IIS

By default, HelpSpot will install as a virtual directory in IIS. This means that if you install it into your site example.com, HelpSpot will appear as a virtual directory "/helpspot", making it accessible at example.com/helpspot.

If you want to use HelpSpot in the root of a domain (perhaps support.helpspot.com), you can "move" HelpSpot out of the virtual directory and into a website in IIS.

4.6. Removing /helpspot directory in URL on Windows / Apache

This video tutorial walks through how to remove the /helpspot directory from the HelpSpot application path on a Windows / Apache installation.

4.7. Connecting To A Network File Share For Attachment Storage

HelpSpot installs based on IIS can be configured to store their attachments on a network file share allowing the file storage duties to be offloaded from the application server. IIS needs to be configured properly to allow it to write to network file systems.

1. Open the IIS Manager
2. Find your app pool for HelpSpot and open up the advanced settings
3. Set the identity to a user that has access to the local helpspot install and to the network file share you plan on using
   
   
4. Open up your website in the IIS manager and select the authentication options.
5. Edit the anonymous authentication settings and select the application pool identity.
6. Restart IIS
7. Go your HelpSpot admin screen and click on settings
8. Edit the attachment file system directory setting to point at the UNC path of your file store
   
9. When you save the settings HelpSpot will verify that it can write to that directory
10. Migrate your existing files to that new file store location.
    

4.8. Enabling SSL in Apache on Windows

SSL for HelpSpot can be enabled on windows based installations, but it does require some configuration. This document will not cover in detail how to create a CSR or obtain certs in the proper format for Apache as this varies based on the certificate provider. This document will assume that an Apache-compatible cert, certificate chain and key have been obtained. It is intended as a general guide and the exact set up for a specific installation may vary.

Editing the Apache configuration files

1. Backup your C:\Program Files (x86)\helpspot\apache\conf\ directory.

2. Place your certificate, certificate chain and key in the C:\Program Files (x86)\helpspot\apache\conf\directory.

3. Navigate to C:\Program Files (x86)\helpspot\apache\conf\ and edit the httpd.conf file as follows. Uncomment (remove the #) these lines: 
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so 

LoadModule ssl_module modules/mod_ssl.so 

Include conf/extra/httpd-ssl.conf

4. Edit the C:\Program Files (x86)\helpspot\apache\conf\extra\httpd-ssl.conf In the most basic setup you will need to verify / edit these paths:
SSLCertificateFile "${SRVROOT}/conf/cert.pem"

SSLCertificateKeyFile "${SRVROOT}/conf/cert.key" 
   
   Most certificate will also need a chain file. 

SSLCertificateChainFile "${SRVROOT}/conf/server-ca.crt"

5. Now restart your HelpSpot Apache service in the windows services area. If service does not start up, we recommend running C:\Program Files (x86)\helpspot\apache\bin\httpd.exe from the command line to obtain useful error output.

6. Once you have a working configuration make sure to take a new backup of the  C:\Program Files (x86)\helpspot\apache\conf\  directory. This backup can be used to restore changes after a HelpSpot upgrade.

4.9. HelpSpot Limits

HelpSpot has several built in limits on record counts and various other operations to ensure good performance and prevent mis-configuration from negatively impacting the system operation. Some of these limits can be adjusted on self-hosted instances using configuration variables.

• Max Note Size - Each note in a request is limited to 70,000 UTF8 characters.
• Max Request History Records - Each request is limited to 1,500 request history items. When this limit is reached a notice will be displayed staff members alerting them to the issue. This limit is configurable via the cHD_MAX_REQUEST_HISTORY setting in the HS_Settings table.
• Full Text Searches In Filters - Full text searches in filters are limited to 2000 results on MySQL and 5,000 results on SQL Server
• Automation Rule Matches - Automation rule can be run on a individual request for a maximum of 50 times.  This limit is configurable via the cHD_MAX_AUTO_RUNS setting in the HS_Settings table.
• Custom Field Creation - Creation of custom fields is theoretically limited on MySQL based installations by the maximum column count of the InnoDB storage engine.
• Filter Date Limit - The Filter Within Previous (days) setting found in Admin > Settings limits the number of days back a filter searches for records. By default this is set to 365. You can change this setting in the settings area or you can add a date criteria to your filter to override the default limit.
• Max Results to Display - The Max Results to Display setting found in Admin > Settings limits the maximum number of requests shown in filters and search results sets.
• File Upload Size - Limited to 100MB for an individual file on HelpSpot Cloud. This is customizable with server settings on self hosted installs.

4.10. .env Configuration Options

The .env file on self hosted installations controls much of how HelpSpot runs at a global level. The standard settings are setup during installation but there are additional settings that can be configured if needed. All environment variables are entered into the .env file in this format: env_var_name="value"

• SECURITY_FRAME_OPTIONS - Controls the x-frame-options http header.
  • Default: SAMEORIGIN.
  • Values: SAMEORIGIN, DENY, ""
• CUSTOM_CSP - inserts custom CSP domains to be allowed in the admin area.
  
  • Default: null
  • Values: "yoururl.com"
• PORTAL_CUSTOM_CSP - inserts custom CSP domains to be allowed in the customer portal.
  • Default: null
  • Values: "yoururl.com"
• FORCE_HTTPS - This setting is used when SSL is offloaded to a reverse proxy or load balencer and traffic between the proxy and the HelpSpot server if unencrypted. If SSL is provided by the HelpSpot web server only the APP_URL needs to be changed to reflect the https protocol. In most cases when enabling SSL on a web server the only change needed is to update the APP_URL.
  
  • Default: false
  • Values: true, false
•  DISABLE_CSRF - Disable CSRF protection to certain routes, comma separated list of routes.
  • Default: null
  • example .env setting: DISABLE_CSRF_FOR="https://example.org/my-route,https://example.org/index.php?pg=login"\
• MAIL_CRON_INTERVAL - Set custom timing for how often email mailboxes are checked for mail. Wrap expression in double quotes.
  
  • Default: "* * * * *"
  • Values: Valid CRON format schedule.
  • Example: "*/3 * * * *" (Checks mail every three minutes.)
• MAINTENANCE_CRON_INTERVAL - Set custom timing when daily db maintenance tasks are run. Wrap expression in double quotes.
  
  • Default: "0 0 * * *"
  • Values: Valid CRON format schedule.
• AUTO_COLLECT_MAIL - Enable (default) or Disable mail collection
  
  • Default: true
  • Values: true, false
• SEND_MAIL_DELAY - Add a delay between mail sends to help with services that throttle sends over time
  
  • Default: 1
  • Values: Time in seconds
• SEND_MAIL_BACKOFF - The number of seconds to wait before re-trying an email that failed to send
  
  • Default: 30
  • Values: Time in seconds
• SEND_MAIL_RETRIES - The maximum number of times HelpSpot will attempt to resend an email.
  
  • Default: 5
  • Values: An integer of reties
• MAINTENANCE_MODE - Put HelpSpot into maintenance mode
  
  • Default: false
  • Values: true, false
• SECURITY_CONTENT_TYPE_OPTIONS - Sets the X-Content-Type-Options
  
  • Default: nosniff
  • Values: nosniff or empty
• RESIZE_IMAGES - Performs a legacy image resize. Generally suggested to be turned off.
  • Default: false
  • Values: true, false

5.1. Templates: The Basics

The HelpSpot portal is fully customizable to allow integration with any website or intranet.  Please note that if you're on a hosted trial, you'll need to contact support to enable editing of portal templates.

PHP and HTML

HelpSpot templates are HTML with PHP, not an esoteric template language. This means PHP can be used within the templates themselves to call user-defined functions, includes, an other PHP constructs. This can make customizing an installation easier to allow the inclusion of templates from a main site, thereby preventing the duplication of code.

Editing Templates

The easiest way to edit the portal templates is by navigating to Admin > Customize > Portal Templates. Here you can view and edit the templates for your primary portal and any secondary portals. HelpSpot automatically versions your changes and allows you to roll them back if needed.

If you with to edit the files on the server directly, templates are located in the folder: /helpspot/templates. While it's possible to modify the files there directly it is not recommended. Instead it is recommended that the files be copied and placed in: /custom_templates. HelpSpot's template system will automatically check the /custom_templates folder and use the template from there instead of from /helpspot/templates. Using a custom templates folder prevents customizations from being overwritten during future version upgrades.

Common Files to Modify

These files are included on each page of the portal. For a basic level of integration (ie: standardizing 'look and feel), modifying only these files, in most cases, would be enough.

• header.tpl.php
• footer.tpl.php
• navigation.tpl.php
• css.tpl.php

List of All Templates

Each template contains specific documentation inside it, so please see the templates themselves for more details

5.2. Admin Themes

AS OF HELPSPOT 5.0 ADMIN THEMES ARE NO LONGER USED

Admin themes have been replaced with custom javascript and css settings.

Admin themes allow you to customize the look and feel of your staff pages in HelpSpot. A few simple uses include:

• Changing the header to your company colors
• Adjusting text sizes more to your liking
• Adding or removing UI elements

Theme Structure

HelpSpot ships with several built in themes. The code for these /themes/ with a subfolder for each specific theme. So the blue theme is in /themes/blue/. Inside the folder is the css for that theme and optionally an image folder and custom javascript file. So a theme folder with everything would look like this:

Creating a Custom Theme

It's often useful to start with one of the built in themes as those contain the most common elements you want to modify. To do so simply copy one of the folders like /themes/blue to your own folder such as /themes/pink. In this case you'd then change blue.css to pink.css and you're all set. From there you can modify pink.css to match your design.

You can find all the built in CSS elements in /static_#HelpSpot_Version#/css/base.css and any of those styles can be overridden by your custom CSS.

Using Custom Javascript

If you'd like to add your own javascript logic to HelpSpot you can do so by adding a theme_name.js file to your theme folder, such as /themes/pink/pink.js. HelpSpot will automatically include that file in the head of every page. jQuery is currently also available, however, it uses a custom shorthand of $jq instead of the more familiar $. Of course jQuery() can be used as well. For most things you'll also probably want to wait for the page to load using:

$jq(document).ready(function(){
     //Your jQuery here
});

5.3. Portal Privacy Policy and Terms of Service

The HelpSpot portal allows for the display and agreement to a Privacy Policy and Terms of Service before a customer request can be submitted. These settings are found in Admin > Settings > Portal. These two settings allow you to set a URL for where your Privacy Policy and Terms of Service are hosted. If you don’t have these externally hosted you can create them as KB pages and then link to them.

After adding one or both of these URLs a checkbox will be displayed on your portal forms asking your customers to agree to the terms and privacy policy before proceeding. 

If you are using a customized request.tpl.php template from a version of HelpSpot prior to 4.8.0, you will need to update that template in order to allow the checkbox to be properly displayed. This new code needs to be added immediately following the captcha include:

<?php include $this->loadTemplate('terms.tpl.php'); ?>

5.4. Supported Languages

HelpSpot currently ships with translations for:

• English
• German
• Dutch
• Spanish

If you need another language pack contact customer support to inquire about the translation process.

5.5. Changing HelpSpot's Display Language

HelpSpot supports multiple languages (see the current list of languages supported here). You can switch between languages by going to Admin > Settings > System and changing the dropdown option for 'Language.'  

Please note that this will change the display language for HelpSpot and your support portal(s).  It will *not* change the language for any existing email templates.  Please get in touch with HelpSpot support if you'd like to do so.

If you're interested in HelpSpot supporting other languages, don't hesitate to contact us to let us know.

Finally, suppose you need to change specific words in HelpSpot.  In that case, you can do that by visiting Admin, Customize, Customize Admin, and then enter the overrides into the "Language overrides" box.   Anything entered in this box needs to be a valid JSON object.  For more information, please read the documentation.

5.6. Language String Overrides

You may find that you want to customize a particular language string in HelpSpot to better reflect your business processes and workflows. This can be done via language overrides.

1. Navigate to Admin > Customize > Customize Admin
2. Click on the link to download your language file.
   
3. Open the downloaded file in a text editor. The file contains key/string pairs in JSON format. 
4. To customize a string copy the key/string that you need to modify back into the "Language overrides" textbox along with wrapping curly brackets. For example if you wanted to change the name of "My Queue" to "My Requests" you would insert the following customization:
   {
"lg_myq": "My Requests"
}
5. Save your changes.

Multiple strings can be customized by comma separating them just line you find in the source language file.

5.7. Populating Customer Information via Links

Creating links to the admin

Some customers find it convenient to add an HTML link to their other customer data systems, which allows them to open a new HelpSpot request. The URL you should use for this is below:

http://your-helpspot-url/admin.php?pg=request

In addition, it's possible to pass in customer information so that the customer information form fields will be pre-filled in. You may pass in the following fields via the URL.

An example:

http://your-helpspot-url/admin.php?pg=request&sUserId=12345&sEmail=tsmith@company.com&sFirstName=Tim&sLastName=Smith&sPhone=8451234567

Creating links to the portal

The portal's request form may also be populated with data via links. In addition to the above variables that can be passed in, the following are valid for the portal form.

An example:

http://your-helpspot-url/index.php?pg=request&fullname=todd%20jones

5.8. Category Management

Categories are the primary way of grouping requests inside of HelpSpot. When HelpSpot is installed it will come with pre-populated categories to get you started. Using these categories is completely optional. 

To customize the categories available in your helpspot instance navigate to Admin > Categories.

Adding a New Category

Use the add category form to add a new category to HelpSpot.

Settings in Depth:

Category Name: The name of the category that will appear in the user interface of helpspot.

Category Grouping: Sets of categories can be grouped together for easier navigation. 

Visibility: This setting will control whether a category is available on public request forms. Allowing request categorization also needs to be enabled at the portal level.

Category Staff Member: The option allows you to select staff members who are available for work requests in this category. This setting works in conjunction with the Auto Assign Requests setting to define the pool of staff used for auto assignment rules.

Default Staff Contact: This setting defines the default staff member that will be assigned requests in this category. It can be left blank. 

Auto Assign Requests: This dropdown allows an auto assignment rule to be defined for a category. The options are as follows:

• To Default Contact - Automatically assigned requests to the Default Staff Contact
• Random Category Staffer - This will randomly select a staff member from the Category Staff Member's pool.
• Random Category Staffer (No Administrators) - This will randomly select a staff member from the Category Staff Member's pool, but staff that are administrators will be excluded.
• Category Staffer With The Least Requests - This will assign requests to the category staff member with the least number of open requests in Helpspot.
• Category Staffer With The Least Requests (No Administrators) - This will assign requests to the category staff member with the least number of open requests in Helpspot, but staff that are administrators will be excluded.
• Round Robin (Even Distribution) - Category staff members will be rotated through in order (i.e. staff 1 - receives request 1, staff 2 - receives request 2, staff 3 - receives request 3, staff 1 - receives  request 4 and so on.)
• Round Robin (Even Distribution, No Administrators) - The same round robin methodology as the previous setting, but excluding administrators.

Reporting Tags: Report tags provide another level of organization beyond categories themselves. Reporting tags are unique in that more than one reporting tag can be selected at a time. 

Custom Fields: Custom fields for a specific category can be specified here. Custom fields that are checked will be included in the side bar of the request window. If the category and custom fields are marked as public they will also be visible on the customer portal form. 

Editing Categories

Each category can be edited by clicking on the category name in the categories listing. All of the settings available when creating a new category are also available when editing.

Deleting Categories 

Categories can not be deleted, but they can be made inactive. To make a category inactive, edit the category and then click on the "Make Category Inactive" button in the lower right hand corner. Once a category is made inactive, it can be accessed by clicking on the "Show Inactive Categories" button in the main categories setting page. Inactive categories can be reactivated by editing the category and then clicking on the "Restore" button.

5.9. Time Tracking

To enable time tracking go to Admin->Settings and click the Time Tracking bar. Set enabled to Yes and save the settings. Each request (after it's created) will now have a time tracking bar at the top for managing that requests time.

Other Time Tracking Tips

• Time can be entered in normal time format hh:mm or in decimal form 1.5, 4.25
• You can add a time column to your custom filters to see how much time was spent on each request right from the workspace.
• After enabling time tracking 2 new reports will be available under the reports tab which allow for time reporting by customer and staff.
• There is a preference in each users settings to default the time tracker box to open.

5.10. Formatted Text Syntax (Markdown)

HelpSpot uses the text formatting language Markdown to support building HTML documents from text.

Markdown also accepts HTML, so you can intermingle HTML tags with the Markdown syntax.

Phrase Emphasis

*italic*   **bold**
_italic_   __bold__

Links

Inline:

An [example](http://url.com/ "Title")

Reference-style labels (titles are optional):

An [example][id]. Then, anywhere
else in the doc, define the link:

[id]: http://example.com/  "Title"

Images

Inline (titles are optional):

![alt text](/path/img.jpg "Title")

Reference-style:

![alt text][id]

[id]: /url/to/img.jpg "Title"

Headers

Setext-style:

Header 1
========
Header 2
--------

atx-style (closing #'s are optional):

# Header 1 #
## Header 2 ##
###### Header 6

Lists

Ordered, without paragraphs:

1.  Foo
2.  Bar

Unordered, with paragraphs:

*   A list item.
    With multiple paragraphs.
*   Bar

You can nest them:

*   Bus
  * Yellow
*   Cars
  1.  Dodge
  2.  Honda
    * Civic
  3. Trucks
*   Cunning

Manual Line Breaks

End a line with two or more spaces:

Roses are red,
Violets are blue.

Tables

A simple table

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

A table with the right columned aligned (note the : at the end of the header line)

| Item      | Value |
| --------- | -----:|
| Computer  | $1600 |
| Phone     |   $12 |
| Pipe      |    $1 |

Formatting can be used within the table

First Header  | Second Header
------------- | -------------
Content Cell  | **Content Cell**
*Content Cell*  | Content Cell

Blockquotes

> Email-style angle brackets
> are used for blockquotes.
> > And, they can be nested.
> #### Headers in blockquotes
> 
> * You can quote a list.
> * Etc.

Code Spans

`<code>` spans are delimited
by backticks.
You can include literal backticks
like `` `this` ``.

Preformatted Code Blocks

Indent every line of a code block by at least 4 spaces or 1 tab.

This is a normal paragraph.
  This is a preformatted
  code block.

Horizontal Rules

Three or more dashes or asterisks:

---

* * *

- - - -

5.11. Widget Tab Setup

The widget tab allows you to gather questions/feedback from any page on your website or even multiple websites. With just a few lines of javascript the tab can be included on any web page.

The widget is completely configurable for seamless integration with your website, even the image used for the tab itself can be changed.

Basic Setup:

<style type="text/css">@import url('http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.css');</style>
<script type="text/javascript" src="http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.js"></script>
<script type="text/javascript">
HelpSpotWidget.Tab.show({ 
	// Nearly every aspect of the widget is customizable, complete documentation here:
	// http://www.helpspot.com/helpdesk/index.php?pg=kb.page&id=323
	host: 'http://www.YOURDOMAIN.com/helpdesk'
});
</script>

Where to Place the Code:

The inclusion code should be placed on every page where you want the tab to appear. For performance it's best to place the code at the bottom of your HTML page just inside the closing </body> tag.

Complete Example:

This example shows every configuration option in use.

<style type="text/css">@import url('http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.css');</style>
<script type="text/javascript" src="http://www.YOURDOMAIN.com/helpdesk/widgets/widgets.js"></script>
<script type="text/javascript">
HelpSpotWidget.Tab.show({ 
	host: 'http://www.YOURDOMAIN.com/helpdesk',
	alignment: 'left',
	tabtype: 'questions',
	tabtype_custom_img: '',
	top: '30%',
	width: 600, 
	color: 'white',
	background_color: '#222222',
	hover_color: '#222222',
	popup_background_color: '#fff',
	popup_border_color: '#ccc',
	popup_border_size: '10px',
	overlay_color: '#000',
	default_note: '',
	default_name: '',
	default_email: '',
	use_field_name: true,
	text_header: 'How can we help?',
	text_intro: 'Submit your question/comment for a member of our team.',
	text_note: 'Question',
	text_note_er: 'Please provide some information on your request',
	text_email: 'Your Email',
	text_email_er: 'Please provide your email address',
	text_name: 'Your Name',
	text_name_er: 'Please provide your name',
	text_submit: 'Submit',
	text_msg_submit: 'Message sent, thank you.',
	text_msg_submit_error: 'Sorry, there was an error.',
	text_msg_submit_error_link: 'Please try this form',
	text_msg_submit_error_url: 'http://www.YOURDOMAIN.com/helpdesk',
	text_loading: 'Loading...',
	text_special: ''
	//,onLoad: function(){ alert('open'); },
	//onClose: function(){ alert('close'); }
});
</script>

CSS Customizations:

The options above allow you to control the look of the tab, but the form itself can be customized via CSS. To do so put a file named widget_tab.css inside your /custom_code folder. If the system detects this file it will include it on the tabs form page automatically.

Option Descriptions:

5.12. Email Templates

Customizing Email Templates

The default email templates can be customized by navigating to Admin > Customize > Email Templates. Each template can be both edited and viewed from this page. Once edits have been made, be sure to save them with the save button at the bottom of the page. Email templates can be formatted with html and can include template tags. These can be selected from the dropdown or typed into the editor.

Most templates contain three separate tabs, HTML, Text, and Subject. The HTML template will send for those that can receive HTML emails. The text version is a plain text version of the same email for those that do not accept HTML email. When editing make sure to update both of these tabs. The subject tab allows you to adjust the subject line of the email. You can also use template tags in this area to personalize the subject line.

Per Mailbox Templates

Email templates can also be specified at the Mailbox level for Auto Reply, Public Notes to Customer, External Notes and Requests Created by Portal Form. These settings can be found in Admin > Email Mailboxes. Once a mailbox is selected the templates can be edited at the bottom of the mailbox's setup page.

When defined, these templates will override the default templates that are set up in the Email Templates page. The "Request Created by Portal Form" template will only override the main template only if the mailbox is defined as the "Send Emails From" mailbox for a secondary portal. 

5.13. Email Template Tags Reference

Email templates can process a variety of template tags. These tags can be typed directly into the template or they can be selected from the tag selector dropdown below the template editor box. Below is a reference to all the available tags. See the Email Templates document for more information on how to edit email templates. The tags below are available for the current version of HelpSpot. Note that HelpSpot versions less than 5.0.0 use a different syntax.

5.14. Custom Pages

5.15. Filter Color Tags

Filter color tags allow easy visual sorting of requests. Color tags are set on the Predefined List custom field type. To add color tags, navigate to Admin → Custom Fields. Then select an existing predefined list or add an new one. Once you have the predefined list setup open you can set the color options for each list item. The color can be selected by clicking on the color code box.

Once the color options are selected in the custom field setup, you can add the custom field to filters using the column selector under the filter editor. 

After saving these changes, color labels will appear in the filter grid.

6.1. Writing AI Prompts

To create and manage AI prompts navigate to Admin > HelpSpot AI > AI Prompts.

Writing an AI Prompt

Every AI prompt needs a name. This name will be used in the user interface when staff invoke this prompt.

Each prompt contains a Role and a Action Prompt.

Role

The Role describes how the assistant is suppose to behave. Here are some examples:

• You are a helpful customer support assistant that uses polite, informal language. You try to preserve html images and links.
• You are a HTML list writer
• You are a professional customer service representative who speaks fluent English & Spanish.

Action Prompt

The Action Prompt is the action that you want the assistant to perform. Try to be as exact as possible when describing what you want the assistant to do. Here are some examples:

• The customers name is: {{ first.name }}. Rewrite as if you were responding to an customer.  
  ---
  {{ input.text }}
  ---
  Include a greeting. Add a closing asking them to follow up as needed and signing off with the name {{ staff.first.name }}. Don't add any new information that isn't in the original message.
• Rewrite this as a list: {{ input.text }}
• Translate {{ input.text }} from English into Spanish.

Here we are using placeholders to dynamically insert data into our Action Prompt. Placeholder can be typed into the prompt or they can be inserted from the placeholder selector. There are a number of placeholders available for use in prompt design.

6.2. AI Settings

AI Settings are configurable in Admin > HelpSpot AI > AI Settings, consisting of four major capabilities:

• Staff Response Tools (AI Composer)
• Request Auto Categorization
• Generate Request Summaries
• Detect Out of Office Replies

Staff Response Tools (AI Composer)

The AI Composer is a powerful tool that with detailed documentation in the User Manual. The behavior and tone can be customized with a system-wide prompt:

While the prompt is empty by default, there are default and user-configurable settings (withing the AI Composer UI) to further customize style and tone.

Request Auto Categorization

HelpSpot AI will train on your own request history to then automatically categorize requests in selected categories. This is turned off by default, but once turned on (by going to Admin > HelpSpot AI > AI Settings), you can then select which of your categories you’d like to be auto-categorized by HelpSpot AI. Categories can also be enabled for auto categorization in the category setup screen. 

This feature requires you to have at least 10 closed requests in any selected category. If you don't yet have 10 closed requests in a category you can still turn on auto categorization and HelpSpot will automatically complete training once there are enough requests. Admins will receive a notification in the HelpSpot interface when training is complete.

Auto Categorization can also function in "Suggest Category" mode where it presents a clickable category suggestion without auto-assigning:

You can view more details on the Edit page for each individual category, where you can additionally view any requests that have been manually selected for training. It will also show you the training status for that particular category - in the example below, this category doesn’t have enough closed requests to be eligible for training:

To manually select a request as a ‘training request’, click on the three dots in the upper right corner of the request, and then select ‘Add to Auto Categorization Training’, as seen below:

Or on a closed request select to "Add to Auto Categorization Training" button.

Once training is complete, the ability to adjust the prompt used for classification is revealed, and editable:

Auto Assignment

Once a request is auto categorized it can also be auto assigned to a staff member. This means that requests will skip the inbox all together and go directly to a staff member's queue. You can learn more about auto categorizing requests in the category setup.

Generate Request Summaries

AI Request Summaries use HelpSpot AI to summarize what your customer has contacted you about and, once enabled, replaces the ‘Initial Request’ column in the Inbox & My Queue pages, along with any filters where you’ve added that column. This feature is turned on by default for new customers, and can be turned on or off by going to Admin, then HelpSpot AI, and then selecting AI Settings. 

Editing Request Summaries

Request summaries can be edited for individual requests by accessing the "request meta" dialog inside of any request.

Detect Out of Office Replies

Out of Office Reply detection use HelpSpot AI to automatically detect and place out of office replies in the trash, based on the text in the body of the email. This detection only applies to emails that would create a new request. If the out of office reply is in reply to an already running ticket the out of office reply will not be removed. This feature is mainly intended to cut down on the out of office replies that occur when a mass mailing is sent out to customers with a HelpSpot email address as the reply-to. This feature is turned on by default for new customers, and can be turned on or off by going to Admin, then HelpSpot AI, and then selecting AI Settings.

6.3. Data Sent To HelpSpot AI Services

Model Providers

HelpSpot AI Services utilizes OpenAI and Groq models to perform various tasks. This data is sent securely to those providers and is not used for training. You can find more information on this here https://openai.com/enterprise-privacy/ and here https://groq.com/privacy-policy/. 

AI Triage

Categorization

To categorize request HelpSpot AI Services needs to train on your existing requests that are in the enabled category. Sample request text body data is selected from the pool of closed requests in a category and sent to HelpSpot AI Services to build a description of that category. After the category is trained each time a new request is created the body and subject of that request is sent to HelpSpot AI Services for categorizations.

Request Summary

To summarize a request, each time a new request is created the body and subject of that request is sent to HelpSpot AI Services.

Out of Office Detection

To detect out of office replies on a request, each time a new request is created the body and subject of that request is sent to HelpSpot AI Services.

Action Prompts

Action prompts in HelpSpot allow users to invoke actions through intuitive, natural language instructions. When an action prompt is used, the data transferred to HelpSpot AI Services is limited to the information specifically stated by the placeholders in the prompt.

Here are examples of some placeholders:

• {{ first.name }} - Represents the first name of the customer. This can only be used in request prompts.
• {{ staff.first.name }} - Stands for the first name of the acting staff member.
• {{ input.text }} - This is a selected text in the editor if the user has made a selection. If no selection has been made, it represents the whole text editor content.

These placeholders define the specific pieces of information that are sent to HelpSpot AI Services.

Summarize Request History Feature

HelpSpot's Summarize Request History feature is an advanced tool that uses AI to condense extensive request histories into a brief and coherent summary. In this case, the entire request history for the specific request is sent to HelpSpot AI Services.

This is necessary to ensure the AI model has all the relevant information needed to generate a comprehensive and accurate summary.

Translate Request History Feature

The Translate Request History feature translates an individual request history item when requested. When this feature is used, only the specific request history item being translated is passed to HelpSpot AI Services.

AI Composer Feature

Composer functionalities are broad, and rely on many of the AI capabilities listed above, and more. Depending on the specific interaction, the request, response history, administrative and per-user prompts (and guidelines) will be sent to HelpSpot AI Services for content generation.

Generate KB Article from Request History Feature

In addition to agent prompts for title, book, chapter, and other options, prompts and guidance, this feature submits an entire request history, or a specific response to HelpSpot AI Services to generate content.

7.1. Triggers, Mail Rules and Automations

There are three types of automated actions in HelpSpot that can be created. The main difference between them is when a request is checked to see if it matches the conditions defined by an automation rule.

Mail Rules

Mail Rules are run when an incoming email is read and a new request is created. This is only run when the request is first created - so it can only be applied once per request. Subsequent responses to a request, even if received through email, are not run against Mail Rules.

Triggers

Triggers are run anytime a request is created or updated. This can check if some conditions are present, or if they've changed. For example, an action can be taken if a category of a request was changed specifically from "technical" to "sales".

Automation Rules

The last category of automation rules is also called "Automation Rules". These are run periodically. How often these run is configurable in the automation settings.

Automation rules are useful for time-dependent tasks. For example, if you wish to escalate a request or send an email notification if a request has not been answered within a certain time period.

7.2. Trigger-Based Auto-Replies

The advantage of trigger-based auto-replies is that you can add extra conditions to enhance functionality (compared to other mail rules and other auto-reply functionalities).

For example, you could define two triggers to send different auto-reply text to customers contacting you via two different Email Mailboxes. You can also add conditions to the triggers which exclude sending auto-replies to inbound new messages from senders containg "noreply" or "no-reply" in the email address. You can even set up a separate trigger to immediately trash incoming requests received from "noreply" or other specific email accounts.

See Defining Triggers for more on trigger configuration.

Things to keep in mind if electing to create trigger-based auto-replies:

• Only run once, when a new request is created.
• Don't preclude the need for New Request Loop Protection configuration.
• Before adding, review any existing user mailbox-level auto-replies (reactive to trigger conditions) to prevent customers from receiving duplicate new request notifications.
• The message content for trigger-based auto-replies is defined in the trigger actions, rather than in the Auto-Reply email templates associated with particular Email Mailboxes.
• Because trigger-based auto-replies get their message text from trigger actions, the message text passes through the Public Notes to Customers Email Template (or External Notes Email Template), expanding in the location of the {message} placeholder within the respective template's definition.

8.1. Overview

What Is a Trigger?

Triggers in HelpSpot are real-time automations that monitor your system for changes and respond immediately with specific actions. They are ideal for situations where you need HelpSpot to automatically react to changes—whether during new request creation or existing request updates.

There are two types of Triggers:

• Create Triggers – fire when a new request is submitted (regardless of source: email, portal, API).

• Update Triggers – fire when an existing request is updated (e.g., status change, category change, reply from end-user, etc.).

This flexibility allows Triggers to power different workflows based on how and when requests evolve.

When to Use Triggers

Triggers are best suited for:

• Reacting to changes in request data, like a category switching from “Support” to “Sales.”

• Automatically assigning requests or notifying staff based on request field values.

• Performing integrations in real time via Live Lookup, Request Push, or Webhooks.

• Ensuring new or updated requests are properly routed and handled without manual intervention.

Examples:

• When a request’s category changes from “Support” to “Sales,” notify the sales manager and assign to the correct rep.

• Automatically run Live Lookup on all new requests to populate custom fields and customer details.

• Send a Webhook to your external system when a request is created, creating links between HelpSpot and your CRM.

Summary

Triggers give you real-time automation power over your HelpSpot environment, allowing you to instantly act on request creation or updates. Their ability to detect field changes and execute integrations makes them indispensable for dynamic workflows, immediate triage, and cross-platform coordination. Whether you’re streamlining internal processes or linking HelpSpot to external systems, Triggers ensure that the right actions happen right when they should.

Best Practices

• Use “Changed From…To…” when your logic needs to detect specific transitions.

• Use “Now Is” when you only care about the current value, regardless of how it got there.

• Limit Update Triggers in high-volume environments—every update runs every relevant Trigger in real time.

• Use advanced actions like Live Lookup and Webhooks to integrate HelpSpot with other tools.

• Avoid overlapping logic across Triggers and Automation Rules to prevent redundant or conflicting automation.

8.2. Defining Triggers - Conditions

How Triggers Work

Triggers evaluate their conditions immediately when a relevant action occurs:

• “Create” Triggers are used for new requests.

• “Update” Triggers are used for existing requests.

Once you select which type of trigger to use, you will need to specify the conditions that will identify matching requests, and select which actions to perform as the result of a match.

Defining Conditions

Conditions can match on both current values and state changes. For example, consider the following conditions:

• "Status ... Now is ... Problem Solved" – fires if the request's status is Problem Solved, regardless of how it got there.

• "Category ... Changed from ... Unassigned" plus "Category ... Changed to ... Development" – fires only if the field transitioned from one specific value to another.

Conditions are available for a variety of request details, such as:

• Customer fields (first name, last name, email address, Customer ID, etc.)
• Request fields (category, status type, assigned to, etc.)
• Custom fields (drill down lists, date/time fields, text fields, checkboxes, etc.) 

The available operators for each condition vary depending upon the field type. Some examples of operators are:

• Is
• Is not
• Less than
• Greater than
• Contains
• Does not contain

8.3. Defining Triggers - Actions

Defining Actions

Actions define the value and state changes your trigger should perform. Examples of actions that are well-suited to triggers include:

• Change the status, category, assignee, etc., when a request is created matching specific conditions.
• Send notifications to specific people when a request is placed in "Problem Solved" status in a selected category.
• Automatically run a Live Lookup on each request as they're created to insert customer details based on matching email or names.
• Customize auto-replies to exclude specific email addresses or send separate "business hours" and "outside business hours" replies.

Actions can change request state, set field values, or perform advanced functions, such as:

• Change the state of request details (category, status type, assigned to, etc.)
• Set the values of custom fields (drill down lists, date/time fields, text fields, checkboxes, etc.) 
• Send email notifications to staff, customers, and/or external recipients
• Automatically run a Live Lookup or post request data to a webhook

The available operators for each action vary depending upon the field type. Some examples of operators are:

• Is
• Is not
• Less than
• Greater than
• Contains
• Does not contain

9.1. Overview

Automation Rules (Admin->Triggers and Rules->Automation Rules) provide a means to preform actions on a set of requests that meet a specific set of conditions. With highly flexible rules-based logic, Administrators have the power to create rules that allow for improved management of support requests.

Automation rules are commonly used for:

• Request escalation
• Workflow creation
• Staff/Management notification
• Customer notification
• Setting/changing request detail values

Designing Rules

With such flexibility, and varied uses, Automation Rules allows for tasks to be accomplished in a number of ways.

While there might not always be one set way to design a rule, the following should always be considered to ensure the rules accomplishes the desired end result.

• Which conditions should be used to pull the appropriate requests?
• What actions should be preformed?
• How frequently should this rule run?
• Should this request be allowed to run more than once per request?

Subsequent pages in this chapter well show the creation and running of automation rules as well as specific examples.

9.2. Rule Creation: Defining Conditions

Automation Rule conditions, just like Filter conditions, are based on individual elements of the request, Customer, or actions taken on a request. Administrators must define if the requests should match any or all conditions defined for the rule.

For each condition there is a means to define the value, via either a drop-down or text field. Each condition provides an additional drop-down for selecting the operator(s) to define how the specified value is applied.

Sample operators include:

• greater than
• less than
• is not
• is

Using category and email as a very simple example, it can be seen how Administrators would work through defining these conditions. Conditions are added and removed by using the plus and minus signs to the right of the condition definition.

A complete list of all conditions, defined, can be found in the attached file found at the bottom of this page.

Testing Conditions

Automation Rules require the defined conditions be tested prior to saving. Because the subsequent actions that are applied can make unreversible changes to requests, testing allows Administrators to verify the conditions defined truly meet the business need.

9.3. Rule Creation: Defining Actions

Once conditions are tested and defined, Administrators can move on to defining the subsequent action(s) to be preformed.

Actions can be divided into two types:

• Actions that change information within the request.
• Actions that notify specified individuals.

Important to remember: the actions defined in a rule will apply to all requests that meet the condition(s). Since some actions result in changes to the request, it's critical Administrators verify the conditions prior to making rules live.

Many times the 'change' and 'notify' actions must be used together within a rule to complete the automated process.

For example, a rule can have actions that notify two staffers and change a category; three individual actions working together to complete the automated process.

9.4. Preventing Reoccurring Matches

Special Note: As of HelpSpot v4.9.0 new automation rules will only run once per request by default. The actions below are only needed if the "Run Once" checkbox is deselected in an automation rule.

Beyond the creation of conditions and actions to define the rule, Administrators must also consider how to use conditions and actions to prevent the rule from continually pulling the same requests as matches.

Rule matches the same requests over and over when it shouldn't?!

This is a common question when first creating rules. To understand why this happens, let's quickly review how rules work.

When a rule runs (details on rule scheduling can be found via the links below) requests are identified, via conditions, and the defined actions are taken.

The next time the rule is run the same requests will be picked up and action taken unless an action is set that makes a change to the request. This change will be the indicator that the request(s) has already been processed.

In practical terms, when creating a rule Administrators need to ask themselves:

• What component of the request do I have to change? (set applicable action)
• Do I have a condition that will look for something outside of what I changed in action? (verify conditions)

Let's work through an example. To support internal procedures, a rule is created to notify Sally Smith (help desk supervisor) when a request hasn't been updated in 4 hours.

To ensure Sally isn't notified continually on the same requests, there needs to be an indicator in the rule that changes. In this example we choose status as the indicator.

So, when creating this rule we must:

• have a condition that looks for those NOT in the Escalated status.
• have an action that changes the status to Escalated. Depending on installation configuration, custom fields or category could also be used.

Below is a look at how the conditions and actions of this rule would be configured.

9.5. Custom Scheduling Automation Rules

automation:rules

You can run all Automation Rules, or specific Automation Rules by their ID. Their ID is found within HelpSpot when viewing the list of Automation Rules.

# Run all automation rules
# Except those marked to run on a Custom Schedule php 
hs automation:rules 

# Run automation rule 1 
# regardless of Custom Schedule setting 
php hs automation:rules --id=1 

# Run automation rule 1 and 2 
# regardless of Custom Schedule setting 
php hs automation:rules --id=1,2

9.6. Examples

Now let's look at how to create Automation Rules that support specific business needs. When reviewing these examples, keep in mind:

• Different combinations of conditions/actions may be used; we attempted to use the most direct way of accomplishing each.
• When considering how to apply to your business, conditions and/or actions may need to be added/taken away.

Escalation: No update to customer after 24 hours

Notification: Request due tomorrow

Scenario: ABC support desk wants to notify staff (via SMS notification) of requests that are due tomorrow (a custom field). Due date is only tracked for those requiring off-site work, specifically hardware installation.

Email Results Set: Creating daily management reports

Scenario: Department managers in the company are expected to have an understanding of the types of issues the support desk is handling on behalf of the areas they manage. To facilitate this, the support manager wants to create a report that shows all each departments requests, opened in the past 24 hours. For ease this report should be emailed daily to each manager.

Here's how this need would be translated, for one of the departments, into an Automation Rule.

Important to Notice

• Conditions are:
  • categories since it's related to each department in the company, and
  • relative date opened, so the manager can see all new requested worked in the past day.
• The results set will be sent every day when the rule is run (using default, once per day).
• Recipients must have a HelpSpot account.
• A rule would have to be created for each manager in the company.

10.1. Secondary Portal Overview and Limitations

HelpSpot's secondary portal system provides the unique ability to create multiple portal instances, all of which feed into a single installation. Secondary portals are ideal for HelpSpot installations that need to support distinct website domains or require custom portals for different departments, groups or brands.

How it Works

All secondary portals are initially based on the primary portal (default, built-in portal), however can be customized to meet the needs of the target customers. As such, Administrators can choose to exclude/include:

• Knowledge Books and Forums
• Public Categories
• Public Custom fields

Because each secondary portal has it's own set of templates, Administrators have full control over giving each their own look and feel.

Limitations

Given the current design of secondary portals, Administrators should be aware of the following limitations / considerations prior to implementing.

* Secondary portals currently all share logins with the primary portal. For departments this is likely fine. If you're using it across websites this may be an issue if you expect customers to use both websites. In that case you could disabling logins or use Black Box logins to enforce your own login logic.

* Secondary portals cannot show requests that were manually created by staff. Only requests created by the customer via email or the secondary portal can be shown to customers when logged in.

* All secondary portals must be on the same server as the main HelpSpot installation or at least available across a network drive. Secondary portals must be able to read files from the main HelpSpot installation.

* Several settings are currently not able to be overridden and default to what the primary portal is set for in Admin->Settings->Portals. Examples include which captcha to use and if the request form should use the simple or detailed format.

* The reCaptcha keys (for installations using reCaptcha) are shared across all portals so a global reCaptcha key must be used.

* Public components (knowledge books and forums) created for secondary portals will be shown on the primary portal. If this is not desired, a secondary portal must be created to override the default primary portal. Details on that process are here.

In the subsequent pages we'll look at the creation process, including file placement, and how to address special considerations.

10.2. Adding a Secondary Portal

There are two main steps to adding a Secondary Portal:

1. Configuring the portal within HelpSpot
2. Creating the Secondary Portal files as instructed from HelpSpot (If you are using HelpSpot Cloud please contact support)

Configuring a Secondary Portal

To configure a new Secondary Portal, head to Admin > Customize > Secondary Portal. There you can edit an existing or create a new Secondary Portal. For details on the configuration options available, see the section Explanation of Each Portal Setting.

Once you create a new Secondary Portal, you'll be provided with a set of instructions on setting up the portal.

Create the Secondary Portal files

HelpSpot will attempt to setup your portal files system and URL automatically (If you are using HelpSpot Cloud please contact support):

If HelpSpot is unable to automatically setup your portal, there is a View Instructions link available at the Admin > Customize > Secondary Portal page (the same page which lists existing Secondary Portal).

10.3. Explanation of Each Portal Setting

Administrators should go to Admin area->Tools->Manage Secondary Portals. It is from here the process begins. The following fields, described below, are the first phase of two phases in the creation process.

Remember: Because every secondary portal is based on the primary portal, settings not described here use the values in Admin->Settings->Portal.

Portal Name - This overrides the organization name that is used in the Primary portal. This name will be shown in the header of the secondary portal and is also used as a label when reference is made to this portal in the request history, workspace, filters, and reports.

Portal URL - The URL of the secondary portal. This may be an alternate domain or a subfolder of where HelpSpot is currently installed. For instance, if HelpSpot is installed at:

http://www.mydomain.com/helpdesk

and this secondary portal is going to support a different website at www.cookies.com then you would set this URL to be:

http://www.cookies.com/helpdesk

Note that there should be no trailing slash at the end of the URL.

File System Directory Path - The file path to the URL. This path need to be on the same server as the main HelpSpot installation or a network accessible path. This path is used to reach the /custom_templates folder for this secondary portal and include an override files in that folder.

Note that there should be no trailing slash at the end of the file path.

Categories to Display - This is a list of all the public categories created in Admin->Categories. Any categories checked will be available in the category drop down of the secondary portals submit a request form.

This allows flexibility in customizing the request form for this portal. For example, if this secondary portal is for another department only categories related to that department would be checked.

Checking no categories will prevent the category selection drop down from being visible on the request form for this portal.

Custom Fields to Display - This is a list of all public custom fields created in Admin->Tools->Custom Request Fields. Any custom fields checked will be available on the secondary portals submit a request form.

Note that they will still be restricted to whatever visibility has been specified for them so if the custom field only shows up for particular categories you'll want to make sure those categories are checked in "Categories to Display" as described above.

Knowledge Books to Display - A list of all public knowledge books. Selected books will be available on this secondary portal.

Forums to Display - A list of all public Forums. Selected forums will be available on this secondary portal.

Remember that all public categories, custom fields, books and forums are always visible on the primary portal (built in portal). If this is not desirable in your situation you should read this page on how to change that.

Send Emails From When an email is generated from this portal (ie: auto reply for when a request is created or User/Staff replies to requests) this is the mailbox that will show as the FROM. This is an important setting if you're supporting a secondary website where you want the email domain to match the portals domain.

Customer Log-in View - Mailboxes selected allow requests created via those mailboxes for a logged in portal visitor to be shown in the request history for that customer. So, logging into this secondary portal will allow customers to see all requests they created via the portal form as well as requests emailed in to any of the mailboxes selected in this setting.

Portal Phone - Show a phone number for this secondary portal in the portals left navigation.

Portal Homepage Message - Override the default portal message that's in Admin->Settings->Portal. This message appears on the portals homepage. It can include HTML.

The second phase of the creation process requires directories be created and files be moved to specified locations. Each step of the process is outlined on screen and should be followed to completion.

10.4. How Portal Templates Work in Secondary Portals

When a secondary portal is created a /custom_templates folder is created for the portal. Having it's own /custom_templates folder allows the secondary portal to be modified to match the look of an existing website or have a look of it's own.

The location and procedure for editing templates in a secondary portal is the same as the primary portal (information here), the only difference is that the edited templates should be placed in the secondary portals /custom_templates folder instead of the primary portals /custom_templates folder which is in the root HelpSpot directory.

Important to Remember: Secondary portal templates are stored in it's own /custom_templates folder. Any template changes for a secondary portal should be saved to this location.

10.5. The Primary Portal as a Secondary Portal

By default the primary portal shows every public category, custom field, knowledge book and forum created in the system. In most installations this is the desired behavior, however, in some installations (typically those using secondary portals) some of those items may not be appropriate for the primary portal. For example, a knowledge book may be created which is only for the secondary portal and should not be shown on the primary portal.

For these instances, a simple way to control what appears on the primary portal is to create a secondary portal to be used to override the primary portal. Technically and functionally, the primary portal becomes a secondary portal that can be customized with the desired components.

Because the creation process assumes the secondary portal will exist along side the primary portal, the following process should be used to override the primary portal.

Procedure

1. Create a secondary portal which will override the primary portal. This portal should use the primary portals URL for it's URL and have the same file path as the HelpSpot installation itself.
2. Check the checkbox in the secondary portal for "Use as Primary Portal."

Your primary portal is now overridden by the newly created secondary portal and should conform to the settings specified.

10.6. Adding a Secondary Portal within Microsoft IIS

There are two ways in which Secondary Portals are typically used.

1. As a sub-directory so your site. This will create a Secondary Portal under the same domain as your HelpSpot installation, but under a different directory. For example, if HelpSpot is located at http://support.example.com, and you would like a secondary portal at http://support.example.com/portal, the /portal portion of the URL if the sub-directory under which the Secondary Portal will be installed.
2. As a different domain or subdomain. This will create a Secondary Portal under a domain or sub-domain which is different from your HelpSpot installation. For example, this describes if HelpSpot is located at http://support.example.com, but you'd like the secondary portal to be a different subdomain such as http://portal.example.com OR if you would like the secondary portal to be at a different domain altogether such as http://another-example.com.

Here we will cover how to accomplish either situation.

Assumptions

In both situations, we will cover these basic steps:

1. Creating a secondary portal within the HelpSpot Admin configuration.
2. Configuration the secondary portal location within the system (via IIS Manager)
3. Configuring PHP to be used within the secondary portal.
4. Create needed PHP files

Note: We're using IIS7 for this configuration and are basing these instructions off of a default installation of a new HelpSpot instance.

Create a Secondary Portal

The first task to complete in either case (sub-directory or additional domain name) is to create a Secondary Portal within HelpSpot's Admin area.

1. Click to Admin > Customize > Secondary Portal.
2. Fill out the appropriate forms:
   • Portal Name - This will be the name that portal users see when they visit it. It can be anything you'd like.
   • Portal URL - This will be the full URL for the portal. If you are using a sub-directory, include the directory path. For example, a subdirectory for this field may be http://example.com/portal. If you are using a subdomain or domain, fill that in. An example of a domain would be http://portal.example.com or http://new-example.com.
   • File Directory Path - This should be the full file path for your portal files. If your HelpSpot web files are located in it's default install location of C:\Program Files (x86)\helpspot\helpspot, we recommend putting your Secondary Portal files alongside them. For example, C:\Program Files (x86)\helpspot\new-portal. If this directory does not already exist, you can create it
   • The remaining settings you can set up as you wish. You can find more information on them in the documentation here.
3. After clicking "Add Portal", HelpSpot will create unique index.php and config.php files and a "custom_templates" directory within the FileDirectoryPath for (optional) customization.
   
   

Note that the URL settings in the new Secondary Portal need to match the Virtual Directory or Domain created in the next steps.

Secondary Portal as a Sub-Directory

If you are installing HelpSpot's Secondary Portal in a sub-directory, continue on with these instructions. Otherwise, you can skip to the next section "Secondary Portal as an Additional Domain".

This assumes you have followed the steps above under "Create a Secondary Portal".

By default, HelpSpot installs under a "site", usually the "Default Web Site". Within the Default Web Site, it creates a Virtual Directory named "helpspot" and configures it to work with PHP via the PHP_FastCGI module mapping.

These are the same configurations used to create a Secondary Portal under a new Virtual Directory.

1. Create a New Virtual Directory

Under the same website HelpSpot is under (usually Default Web Site), create a new Virtual Directory by right-clicking Default Web Site (or the name of your site) and choosing "Add Virtual Directory".

Fill out the fields as follows:

• Alias - This will be the subdirectory of the url. If you fill in new-portal, the sub-directory will then be http://example.com/new-portal.
• Physical Path - This will be the same path used when creating the new Secondary Portal within HelpSpot. Select the directory you created above when creating a Secondary Portal within HelpSpot. In this example, that path is C:\Program Files (x86)\helpspot\new-portal

2. Configure PHP

Next and lastly, the virtual directory will need to be told to use PHP FastCGI to interpret the PHP files. There are two steps to this.

First, set a Default Document. This tells IIS to search for a document (such as index.php) if no document is specified. A url such as http://example.com/my-portal has no document specified, while http://example.com/my-portal/index.php does.

The document index.php needs to be added as a default document. Click on the new Virtual Directory "new-portal" and then double-click on the Default Document icon. If you do not see index.php listed as a default document, then you can choose the 'Add...' link on the right-hand menu in order to add it as shown.

Next, enable PHP to be run by adding a Handler Mapping. Once again, click on the new-portal Virtual Directory and then double click on the Handler Mappings icon.

PHP FastCGI needs to be added as a handler. Click on the "Add Module Mapping" link on the right-hand menu. The fields are as follows:

1. Request Path - Let IIS know which documents to use FastCGI with. HelpSpot needs to run any PHP file through Fast CGI, so a wildcard path *.php should be used.
2. Module - The HelpSpot installer ensures that the FastCGI Module is already available to use. Here we can use that module for this Virtual Directory. Choose "FastCgiModule" from the list of available Modules.
3. Executable Path - This is the path to the php-cgi.exe file installed by HelpSpot to run PHP. This is installed with HelpSpot and can be found in it's install location. By default, this is "C:\Program Files (x86)\helpspot\php\php-cgi.exe". Note that use of quotes, to account for the space within the file path. Lastly, note that when you check the file path, you may need to set the file type from *.dll to *.exe as pictured below in order to make the php-cgi.exe file visible.
4. Name - The name is arbitrary. We recommend naming it "PHP FastCGI".
5. Click OK and then choose Yes to make it an application.

Now when you enter http://example.com/my-portal (adjusting the domain as appropriate), you should see the newly created Secondary Portal home page.

Secondary Portal as an Additional Domain

Adding a secondary portal under an additional domain is very similar to adding a new Virtual Directory.

1. Create a New Site

This assumes you have followed the steps above under "Create a Secondary Portal".

In order to use a different domain for the Secondary Portal, create a new Site within IIS. In this example, we'll assume the additional domain will be portal.example.com.

Right-click on Sites and choose "Add Web Site". Fill out the fields as follows:

1. Site Name - This is arbitrary. In this example, we'll use "Example Portal".
2. Physical Path - This is the path to the directory created when adding a new Secondary Portal. In this example, we created the "new-portal" directory alongside the main HelpSpot files at C:\Program Files (x86)\helpspot\new-portal.
3. Type/Binding/Port - These can remain as default in most cases. If you are using an SSL certificate with this additional domain, you may need to change the Type to "https".
4. Host Name - This is the domain used, in our example portal.example.com.

Configure PHP

In many cases, because HelpSpot is already installed, PHP will already be configured for new sites created within IIS. The settings will often be the same as the Default Web Site.

However, to make sure PHP is properly configured, ensure the following two configurations are set:

Default Document - Ensure the Default Document includes index.php. Within the IIS manager, click on the newly created web site, then double-click the Default Document icon. Ensure that index.php is listed there.

If index.php is not listed, choose the 'Add...' link on the right-hand menu in order to add it as shown.

PHP FastCGI - Ensure that the FastCGI Module is set to run for any PHP file. Once again, click on the newly created web site and double-click the Handler Mappings icon. The setting "PHP FastCGI" should be enabled for the path *.php.

If "PHP FastCGI" is not listed, then it needs to be added as a handler. Click on the "Add Module Mapping" link on the right-hand menu. The fields to complete are as follows:

1. Request Path - Let IIS know which documents to use FastCGI with. HelpSpot needs to run any PHP file through Fast CGI, so a wildcard path *.php should be used.
2. Module - The HelpSpot installer ensures that the FastCGI Module is already available to use. Here we can use that module for this Virtual Directory. Choose "FastCgiModule" from the list of available Modules.
3. Executable Path - This is the path to the php-cgi.exe file installed by HelpSpot to run PHP. This is installed with HelpSpot and can be found in it's install location. By default, this is "C:\Program Files (x86)\helpspot\php\php-cgi.exe". Note that use of quotes, to account for the space within the file path. Lastly, note that when you check the file path, you may need to set the file type from *.dll to *.exe as pictured below in order to make the php-cgi.exe file visible.
4. Name - The name is arbitrary. We recommend naming it "PHP FastCGI".
5. Click OK and then choose Yes to make it an application.

Now when you enter http://portal.example.com/ (adjusting the domain as appropriate and assuming the DNS settings for the domain are set), you should see the newly created Secondary Portal home page.

11.1. SSN & Credit Card Redaction

HelpSpot now has options to redact credit card and/or Social Security Numbers from new requests & updates to existing requests.  When enabled, HelpSpot automatically detects when either credit card and/or Social Security numbers are part of a new ticket or an update to an existing ticket and redacts the sensitive data inside HelpSpot, the support portal, and even public notes to the customer.

To turn redaction on or off, go to Admin -> Settings -> System.

Please note that custom fields are not checked, and updates (private, public, or external) to requests that have already been written aren't retroactively checked once these options are enabled.

11.2. Time Tracker

HelpSpot's time tracker feature allows Users to log time spent working individual requests, right within the request page.

To enable this feature, navigate to Admin > Settings > Time Tracker.

Once this is done, Users will see the time tracker module at the top of the request page for every request.

For more on how the time tracker is used by Staff, see the Users Manual.

11.3. License Information

The Admin area contains the details of the installation such as: customer ID, number of users, version, and support contract information.

Below all the installation information, Administrators will find an file upload area for the license key. Upon initial installation a license file must be uploaded. Any subsequent changes to the installation such as the purchase of additional licenses or a support renewal will also require uploading a new license file, which will be emailed to the primary contact on file with UserScape.

11.4. Maintenance Mode

This option is only available on self hosted Helpspot.

Maintenance mode allows Administrators to suspends the creation and updating of requests while upgrades or other maintenance is being completed.

Maintenance mode suspends:

• Email integration. All emails will remain on the mail server until maintenance mode is disabled, at which time all emails sent during the maintenance period will be pulled.
• Portal submission. Customers will not have access to the portal during maintenance mode periods. Subsequent sections discuss on this page discuss how this looks to the customer.
• API integration. Those creating/updating requests via an automated process (API) will find during a maintenance period that an error to the application calling the API.

Enable Maintenance Mode

php hs down

php hs down --message="We are upgrading our systems. Please check back in 30 minutes."

Disable Maintenance Mode

php hs up

11.5. Status Types

HelpSpot offers the flexibility of creating customized status type which are typically used to denote the current progress made on a request.

By default, HelpSpot provides 5 status types. These can be edited or set to inactive and replaced by those created by an Administrator. To add a status type, Administrators simply type the name of the status in the Add a New Status box. Hitting Save at the bottom of the Settings page will create the status and set it as active.

While the use of status is required, it's important to note that the status must be changed to something other than Active to close a request.

Status Types in Use

Beyond using as an indicator of where on the continuum of resolution an issue sits, Administrators may opt to have status serve as milestones in a process to resolution. When status types are used as milestones, they can be coupled with automation/mail rules or even filters to create specific workflows.

11.6. Custom Fields

HelpSpot custom fields allow for the creation of user-defined fields that store data on a given request. Custom fields are full-fledged data items in HelpSpot. They can be filtered on, modified with automation, used in templates, etc.

Custom Field Types and Creation

Custom fields are created and modified in Admin > Custom Fields. Below is a list of the available custom field types.

• Predefined List - Creates a dropdown list of options that a user can select.
• Drill Down List - Creates multiple levels of dropdown lists that are dependent on the parent selection.
• Text Field - Stores text data on a single line.
• Large Text Field - Store multiline text data.
• Date Field - Stores date data and presents a calendar date-picker for date entry.
• Date and Time Field - Stores date and time data and presents a date and time picker for entry.
• Regular Expression Field - Validates text data against a regular expression before allowing data entry.
• AJAX Selection Field - A programmatic field that dynamically populates options. More info here: Ajax Fields
• Checkbox - Creates a single checkbox fields
• Numeric Field - Stores whole number data.
• Decimal Field - Stores decimal number data.

Custom Field Options

When creating a custom field you can attach the custom field to particular categories. The requests in the categories selected will be the only requests that present those custom fields. You can also choose to make custom fields public which will show them on the public customer portal.

You can also choose to make a custom field required. If a custom field is required. Users will not be able to update / create a request without providing a value.

11.7. Permission Groups

Permission Groups in HelpSpot allow administrator to define the rights for helpspot staff members. Permission groups also serve a secondary function in controlling access to resources like shared filters and responses. Permission groups are defined in Admin > Organize > Permission Groups. HelpSpot comes with several predefined permission groups each of these can be edited or deleted with the exception of the Administrator group. To edit a permission group simple select it from the list. Permission groups can also be copied by choosing the clone link. Below is a summary of the available permission group options.

Assigning Staff to Permission Groups

Administrators can assign staff members to a permission group on the Staff page inside of the Admin panel. Only one permission group can be selected per individual.

Using Permission Groups in Filters and Responses

When setting up a filter or response, permission groups can be selected as a criteria for sharing the item. Multiple permission groups can be selected for sharing in the filter or response. 

11.8. System

The Systems box within the Settings page contains the general system configurations for the installation. Each group of settings are described below.

Keep in mind: any changes to these settings will take effect once the Save button is hit at the bottom of the page.

Help Desk Name

The name provided here will be used throughout the installation where the name of the desk is referenced. For example: the top left corner of the HelpSpot for logged in Users, the display name in placeholders, and on the portal.

Default Send From

HelpSpot will look to the mailboxes for populating the drop-down for selecting the default send from account, therefore email integration is required prior to setting this default.

The default selected here will be used as the default 'From' in the recipients mail client. IAN: what happens if I'm not using email integration?

Language

By default, HelpSpot ships with one language file, English-US. You can however create additional language files for HelpSpot to use (see Language Files - Modifying Language Packs). If additional language files have been created they will appear within this drop down field.

Default Contact Method in Request Form

Administrators can set the default contact method on the drop-down when Users use the Create Request form. Contact methods include: phone, email, walk-in, mail, other, forum, instant message, fax, and voicemail. Administrators can also opt to set no default which will force the User to select the contact method prior to initially saving.

Allow Batch Closing of Requests

Enabling batch closing gives all Users the ablity to change the status and close multiple requests, without going into each individual request.

See the Quick Actions section of the Users Manual for more detailed information on how batch processing is preformed.

Allow Batch Responding/Editing of Requests

Selecting 'Yes' for this will allow Administrators and Help Desk Staff level Users to preform a batch updating/editing. Similar to batch closing, batching responding/editing allows for responding and/or editing any field within the request details without entering the request page for each request.

See the Quick Actions section of the Users Manual for more detailed information on how batch processing is preformed.

Guest and Level 2 Limited Access Modes

Guest/Level 2 level Users will be limited to seeing, working, and assigning only within the categories to which they are assigned. Requests outside of those categories will not be accessible to these level Users while this mode is active.

This mode is most often used when an installation allows access to multiple organizations, such as external vendors, for the purpose of working Customer requests.

IP addresses authorized to call tasks.php and tasks2.php

Tasks.php and tasks2.php are the files resposible for mail integration and the excuation of all automation and mail rules. Administrators that wish to create an level of security around these files should list the IPs in the box provided that are authorized to run the files. When IPs are provided, no other IP will be able to run either file. If the field is left blank, the files will be accessible by any IP.

RSS Feeds Enabled and RSS Feeds Copyright Notice

The simple 'Yes/No' drop-down sets if the installation will offer RSS feeds for any of the filtered views. For those that opt to allow RSS feeds, they many also wish to specify a copyright/usage notice to all readers.

Delete requests after this many days in the trash

HelpSpot will hold all request that have been put into Trash for the amount of time designated within this drop-down. Administrators can choose from 1 day-never. HelpSpot defaults to 30 days, however Administrators should be aware that no matter the time frame selected, deleted items are in no way accessible.

Request Note Draft Save Frequency

HelpSpot has a built in draft save function that periodically saves a Users note and with one click allows them to apply any saved version of a note. The default frequency is every 30 seconds, however this can be changed by using the field provided to type (in seconds) the desired save frequency.

Request History Rendering

Administrators can set how the request history is rendered for Users on the request page. HTML can be displayed, escaped, or removed. HTML is the default and recommended for most installations.

11.9. Workers

Queue workers, or "workers", perform various unseen background processes for email processing, trigger and automation rules, AI features, and other scheduled activities. Tools for maintaining them are available in Admin > Settings > Workers.

Restart Workers
This action is useful if something seems stuck or otherwise advised by HelpSpot Support as a system remediation.

High and Default Queue Length 
Statistics that are useful in evaluating queue health and performance. A large number of either metric (anything consistently above 100) should be brought to the attention of support.

Cache Locks (self-hosted only)
Like "restart workers", the "clear all locks" action in this section is sometimes a useful remediation for "stuck" work. 

11.10. Date and Time

HelpSpot provides Administrators the ability to configure date/time display to conform to local preference.

Each setting within this box relates to a date/time format used within the installation.

System Time Zone

As part of the installation process, Administrators are asked to provide the time zone. This time zone will be used to display all dates in the system.

Date Format

This long date format can include: month, day, date, year, and time and can be configured in a number of ways. For example: DD, MM YYYY, TT:TT or Day DD, MM YYYY, TT:TT.

The provided drop-down is a quick way to select format or Administrators can type the desired PHP date format.

Short Date Format

The primary difference between the short date and long date, above, is the exclusion of time in the short date. A sample use of short date includes the check request page on the portal.

Configuring short date functionally is the same as the long date, as described above.

Popup Calendar Date Format

To ensure the date/time used by the popup calendar conforms to all other date formats, Administrators can configure the format through the use of the drop-down provided.

Popup Calendar Short Date Format

As with short date configuration, this setting option allows Administrators to set the short date format for the popup calendar.

11.11. Business Hours

Business hours allow you to configure your helpdesk's hours of operation. These settings are accessed in Admin > Settings > Business Hours. Business hours are important to configure because HelpSpot uses these settings for calculations such as First Response Speed and Resolution Speed. In addition these settings can be used to control when triggers and automations are in effect.

The first area of the business hours page allows the configuration of HelpSpot's default business hours. The lower area of the screen allows you to configure holiday hours. These hours override the default settings. Holidays can be configured to block off an entire day or to modify the hours of operation.

Video Tutorial

11.12. Email Mailboxes

Mailbox Settings

Admin > Email Mailboxes

Mailboxes are how HelpSpot imports new emails from customers and converts them into requests or request updates. A mailbox in Helpspot establishes a POP3 or IMAP connection with the mailbox on your email server. It then imports messages found in the inbox and processes them for inclusion in Helpspot.

Account Name —Name shown in emails sent from this account. You can use placeholders in this field to dynamically insert data like the acting agent's name.

Account Name — The email account that maps to this box ie: support@mydomain.com.

Mailbox — Normally INBOX but can be any folder within the account. This can be used to retrieve email from a different IMAP folder if desired.

Archive Mail — With this enabled mail will be moved to a "helpspot_archive_folder" instead of deleting the email. This only works with imap. Note: HelpSpot deletes emails from the mailbox if this is disabled.

Host Name — This is the hostname of the IMAP or POP3 server you wish to retrieve email from. You will obtain this information from your email provider.

Username — The username used for IMAP or POP3 authentication.

Password — The password used for IMAP or POP3 authentication.

Account Type — The protocol of the account your are connecting to. Options are:

• POP3
• POP3s
• IMAP
• IMAPs
• NNTP
• NNTPS

Port — The port that you wish to establish a connection with your email server on. Usually 110 for POP3, 143 - IMAP, 995 - POP3S, 993 - IMAPS

Security Type — If you are establishing a secure connection you will need to select the correct security type for your email provider.

Default Category — Email to this mailbox will automatically be assigned to the selected category.

Enable Auto Reply — This setting will send an automatic reply to a customer when they create a new request through this mailbox.

SMTP Setting to Use — You can set this to use the system default settings that are found in Admin > Settings > Email Integration or you can specify custom settings here. This is especially important if your SMTP provider requires that the reply-to address match the sending account credentials.

Email Templates —Templates here will override versions found in system email templates (Admin > Customize > Email Templates) when emails are sent from this mailbox. If you do not specify a custom template the default will be used.

11.13. Email Integration

This email integration area allows Administrators to configure outbound messaging, as well as general mail preferences.

Administrators should keep in mind that to properly integrate an existing email support account with HelpSpot, they must set up email integration and create a Mailbox. For more on creating a mailbox, see the Mailboxes page referenced below.

Outbound Email Configuration

Note: HelpSpot will use this configuration for all outbound emails (User notices and outbound customer messages), however these settings can be overridden (if configured as such) by the creation of a mailbox.

Send Outbound Email Via

If you have already set up a mailbox with an API integration or SMTP configuration you can select that mailbox to send your outbound email via. This is the best option in most cases.

A separate SMTP configuration can also be configured on this screen if desired.

Administrators can opt to use PHP mail function or an SMTP server to send all outbound messages. Note that PHP mail is limited in use to only non-Windows installations.

SMTP Configuration (not displayed if a modern authentication mailbox is selected above)

When SMTP is used, the following settings must be provided:

• SMTP Security Protocol. Most installations will not have to configure this and can leave the default, none. Those running servers requiring a security protocol, can configure as such.
• SMTP Host. Provide the host name. Multiple names should be listed without any spaces and separated by a semicolon.
• SMTP Port. The standard port is usually 25, secure is 465. These can vary by server, so check with mail provider.
• SMTP Authentication. Indicate if your mail server requires username/password for authentication.
• SMTP Username/password. If required, and Yes is selected above, provide account username and password.
• SMTP HELO. Most installation will not require this, however those that do can provide it here.

Notification Email Address

In order to send notifications and replies, HelpSpot must have a 'reply to' email address designated. For the recipient of these messages, this email will be the 'From' in the mail client.

For Administrators using email integration this will simply be an account specified when creating mailboxes. By selecting an existing integrated account, they ensure all message sent to the notification email are integrated into HelpSpot.

For those not using email integration, keep in mind the notification email is for outbound use only and no messages sent to this address will be captured by HelpSpot.

Notification Email Address Name

In addition to specifying the notification/outbound email address, administrators must set the name of the account as it will display in the recipient's mail client.

Default Send From

Dropdown selector to specify which Email Mailbox to use for outbound sending of public notes when creating requests. There is also the option of selecting "Do not send email" which will prevent outbound notifications of public notes. 

Request ID Prefix

This is used only for those attempting to send requests between HelpSpot installations. For example, the IT and maintenance department have separate installations but have the need to send requests to each other. So no installations requests are overwritten, they can proceed each request ID with letters to identify their installation.

Global BCC

An email address entered here will receive blind carbon copies of all outbound emails (not visible to other recipients). The dropdown selector allows electing to BCC only public notes or all outbound emails.

Reply Above Text

This field allows administrators to customize the text used to automatically remove quoted history inserted by email clients.

The balance of the settings on this page apply to all INBOUND messages, regardless of the mailbox the message entered in from.

Allow Email Attachments

This simple yes/no drop-down allows Administrators to specify if attachments are imported with incoming email messages. If no attachments are permitted, HelpSpot will strip the attachment prior to importing the message.

Because HelpSpot deletes all messages from the mail server after importing, it is recommended that this be left at the default of yes to ensure no important attachment are lost.

Do Not Allow Attachments with These Extensions

To prevent potentially malicious files from entering HelpSpot, Administrators can specify file types that will be stripped from imported messages. By default HelpSpot lists: exe and vbs. Additional file extensions can be provided in a comma separated list.

Max Attachment Size

The default maximum file size for attachments is 50MB; providing a reasonable balance between sharing of critical files and conserving database space. This can be increased/decreased based on individual organization need.

Reopening Closed Requests

By design, HelpSpot will re-open a request if an update is sent in within 30 days of closing. Administrators have the option of specifying the number of days or setting to 0, which will always force HelpSpot to re-open closed requests when updated. 

Using the default setting helps in keeping new issues from being lost among those that are newly submitted, but done using an old request.

Maximum Emails to Retrieve at Once

To prevent the system from attempting to pull in more emails that in can handle, and run the risk of timing out before messages are retrieved, HelpSpot allows Administrators to limit the number of messages pulled in, per mailbox, for each run of tasks.php. The default provided is 10. It's not recommended that you ever set this to higher than 30.

New Request Loop Protection

HelpSpot will attempt to prevent email loops with other systems based on the rules defined in Admin > Settings > Email Integration > New Request Loop Protection. Two of the three rules in New Request Loop Protection work in concert to stop email loops, and the third rule works independently to prevent duplicate looping. 

Time Period and Max emails in time period work in concert, engaging New Request Loop Protection if one email address sends more than the defined Max number of emails within the defined Time Period.

The Duplicate Check works independently, comparing the subject and body content of incoming emails for exact duplicates within the defined time period (in seconds).

More details about each feature are available on the New Request Loop Protection page.

Enable tasks.php Debugging Output

When setting up your email integrations or if a problem arises you may want to turn this on. Once enabled, when you visit tasks.php via your browser to manually run the process debugging information will be show (it can be useful to 'view source' in the browser for a cleaner view).

11.14. New Request Loop Protection

HelpSpot will attempt to prevent email loops with other systems based on the rules defined in Admin > Settings > Email Integration > New Request Loop Protection.

TL;DR;

• Two of the three rules in New Request Loop Protection work in concert to stop email loops, and the third rule works independently to prevent duplicate looping. 
• Time Period and Max emails in time period are engaged if one email address sends more than the defined Max number of emails within the defined Time Period.
• Duplicate Check compares the subject and body content of incoming emails for exact duplicates within the defined time period (in seconds).
• Trigger-based Auto-Replies are a special-case, customizable option which allow adding extra conditions to enhance functionality.

Time Period and Max emails in time period work together, disabling the mailbox-level auto-reply feature if one email address sends more than the defined Max number of emails within the defined Time Period. This feature only compares inbound email from the same email address over the defined Time Period, without considering the content of the email body or subject.

The mailbox-level auto-reply feature generates new requests for each new email received and sends your configured auto-reply notification back to the sender with their new Request ID appended to the subject line. Any subsequent replies to that notification email contain the Request ID in the subject and are added to the same request rather than generating additional new-request notifications.

So with the settings depicted above, four individual emails from one sender address within an hour would generate four separate new requests and four new request notifications. The fifth individual email from the same sender within one hour would engage the loop protection feature, and a fifth new request would not be generated. This also means they would not receive a fifth new request notification. If they sent the fifth request an hour and a half after the first, it would fall outside of the defined time period and generate a new request and corresponding notification auto-reply as usual.

The Duplicate Check works independently of the other two settings, comparing the subject and body content of incoming emails for exact duplicates within the defined time period (in seconds). Incoming emails are monitored over the defined time period and any with identical subject lines and body contents trigger duplicate protection and prevent new, duplicate requests from being generated.

With the settings depicted above, two duplicate emails received within 600 seconds (i.e., 10 minutes) would trigger the duplicate check and prevent a second, duplicate request from being created. However, two duplicate emails received eleven minutes apart would fall outside the defined time period, and a second, duplicate request would be generated.

It is important to note that emails generated by other automated systems which contain timestamps in the subject line or body may result in non-identical subject/body contents which result in HelpSpot's duplicate check conditions not being met. This is one of the conditions we commonly check for in figuring out how some emails circumvent the duplicate check loop protection.

The New Request Loop Protection settings on the Email Integration page target specific conditions to reduce the likelihood of false positives which could prevent legitimate, similar incoming emails from generating appropriate requests. Because of the chances of other automated systems sending emails which inadvertently fall outside of the Loop Prevention definitions, some HelpSpot customers have also elected to disable the mailbox-level auto-reply functionality and instead opt to utilize trigger-level auto-replies.

11.15. Customer Tools

HelpSpot Customer Tools allow for the export and deletion of customer data. You will find the customer tools in the Admin area of HelpSpot.

Export

The export option in the customer tools will export all request details and public notes as well as public attachments for the entered customer email address. This export is generated as a zip file that can be downloaded and sent to the customer.

Deletion

Customer information deletion has a few more options as it can be used with GDPR requests, purging passwords, PHI, and payment information that accidentally makes its way into HelpSpot. All of the deletions done through this screen are permanent so it is important to make sure that you select the right data to delete.

Request Note Deletion

Customer information can be deleted at the individual request note level. Request note IDs can be retrieved by using the request note menu next to each note. When you delete a request note that individual note along with any attachments in that note will be deleted from HelpSpot.

Request Deletion

Moving one level up. An entire request ID can be deleted from HelpSpot by providing the request id. All notes, history events and attachments will be deleted in this case.

Customer Deletion

Customer information can be deleted based on Customer ID or Customer Email address. This will delete all requests and attachments found for this customer in HelpSpot. 

Attachment Deletion

Individual attachments can be deleted by first obtaining the attachment ID and then using the attachment deletion tool in the customer tools. Mousing over the download button for any attachment will display the ID. Alternatively, you can click on the download link, and the URL for the download will include the ID. 

11.16. Announcements

The Announcements feature allows administrators to send in-app notifications to staff members. These notifications appear as a prominent banner at the top of the HelpSpot workspace, making them ideal for communicating critical information such as system outages, changes in hours, or urgent action items.

Video Tutorial

Creating an Announcement

To create a new announcement, navigate to Admin > System > Announcements. As you fill out the fields, a live preview at the bottom of the screen will show you exactly how the banner will appear to your staff.

• Title. The main header of the announcement. This should be short and descriptive (e.g., "VPN Down").

• Message. The body text of the notification where you provide full details.

• URL. An optional link where staff can find more information.

• Link Text. The text displayed on the action button. If left blank, this defaults to "Learn more."

• Severity. Controls the visual style and color of the banner to convey urgency:

  • Info: Standard blue styling for general updates.

  • Warning: Orange styling for cautionary alerts.

  • Error: Red styling for critical issues or outages.

  • Success: Green styling for positive confirmations (e.g., "System Restored").

• Admins only. If checked, the announcement will be visible only to users with Administrator permissions.

If your HelpSpot is self-hosted, announcements may also be created with the HelpSpot command line tool. See the hs:announcement command.

Staff View

Once Send Announcement is clicked, the notification is immediately pushed to the Workspace of all targeted staff members.

• Banner Display. The announcement appears at the very top of the page, ensuring high visibility.

• Action. Staff can click the button (e.g., "VPN Status") to visit the linked URL.

• Dismissal. Staff can click Dismiss on the right side of the banner to remove it from their view once they have read the message.

11.17. Audit Log

Introduction to the Audit Log

The Audit Log feature, which was introduced in HelpSpot version 5.4.8, allows administrators to track and log important changes and activities in one centralized location. This simplifies the process of monitoring changes and ensures that an accurate record of all changes is maintained.

What is Logged in the Audit Log

The Audit Log tracks a variety of changes made within the system. These include:

• Changes to any settings in the admin panel, including additions, edits, and deletions of mailboxes, users, and more.
• Login activities to HelpSpot.
• Actions involving custom reports such as their creation, modification, and deletion.
• Deletions made using the customer tools, such as when a user or note is deleted. Note that detailed information about the deleted item is not logged.
• The user name and IP address associated with every logged change.

The Audit Log can be scoped by date and filtered by various parameters like user name, what was altered, the action taken, and the corresponding IP address. Once the Audit Log has been filtered, you can even download the Audit Log as a CSV file.

The Audit Log is turned on by default but can be turned off by going to Admin -> Settings -> System.  You can also change the retention settings for the Audit Log; the default setting is 90 days, but you can select as few as 30 days or as many as 730 days (2 years).

12.1. How to Use a Custom Domain Name with HelpSpot Cloud Instance

If you're looking to use a custom domain name with your HelpSpot cloud instance, there are a few steps you need to follow. Here's what you need to do:

1. Create a new request at https://support.helpspot.com/index.php?pg=request: This is the first step in the process. Contacting customer support will get you in touch with the right people who can help you set up your custom domain name.
2. Request a static IP: Customer support will provide you with the static IP of your instance. This IP is required to point the A record of your domain name at.
3. Point the A record of your domain name: Once you have the static IP, you'll need to point the A record of your domain name at it. This is typically done through your domain registrar's control panel.
4. Notify your support contact: Once you've pointed the A record of your domain name, you'll need to let your support contact know. They will then swap your HelpSpot configuration and issue an SSL certificate for your domain.

And that's it! With these four steps, you'll be able to use a custom domain name with your HelpSpot cloud instance. If you have any questions or need assistance, don't hesitate to reach out to our support team at https://support.helpspot.com/index.php?pg=request.

13.1. Turn On Debugging and Logging In HelpSpot 5

There are two debugging / logging settings in HelpSpot 5 that can be enabled. Both of these settings are found in the .env settings file in the root of your HelpSpot install directory.

HelpSpot Cloud customers, please contact customer support for debugging assistance.

The first setting that can be enabled is:

• APP_DEBUG=true

This setting will enabled the display of errors and stack traces in the browser when they are encountered. It is set to false by default. This should not be enabled long term and should be turned back off when debugging is complete.

The second setting is not included in the .env file by default. To enable it you will need to add this string:

• LOG_LEVEL=debug

This setting will cause more details on certain processes in HelpSpot to be written to the helpspot.log file located in helpspot/storage/logs/helpspot.log. 

• On Windows systems, note that when changing these settings you will need to restart the Windows HelpSpot services in order for them to take effect for logging items like mail retrieval and sending queue jobs.
• For Linux systems, you can issue the command sudo supervisorctl restart all (or sudo supervisorctl restart helpspot:* if you run other processes via supervisor).

Also note that setting LOG_LEVEL=debug produces more verbose log output, so be sure to monitor the helpspot.log file size. Remove the LOG_LEVEL=debug directive from the .env file once you've completed troubleshooting to prevent file bloat.

The log file will surface issues with filesystem folder permissions, email connectivity details, configuration errors, or even specific trouble with individual email messages.

13.2. HelpSpot Speed and Performance

If you are noticing speed or performance issues within your HelpSpot installation, here are a few places to check on.

Note that these apply to HelpSpot Cloud installations as well.

Updating Requests are Slow (only applies to HelpSpot v4 and below)

If HelpSpot hangs / is slow when updating a request, this is most often related to HelpSpot sending emails when updating the request. This usually happens when a request update sends multiple emails

Multiple email notifications may be sent under a few different conditions:

• Triggers may add an email notification if a condition is met when updating a request
• Any staff who are subscribed to a request will generate an additional email send
• Any staff being notified on a Private or External request update will generate an additional email send

However, some Exchange mail servers intentionally cause delays between sending multiple requests.

Slow Workspace

Sometimes staff see slowness when navigating around the Workspace section of HelpSpot.

This is often related to having many filters defined, or having a filter that results in a "heavy" database query.

Often filters have a count of found requests next to them. HelpSpot has to run the filter in order to get this number, so in some conditions, many filters are being run all at once as users click around the Workspace. This can result in a pile up of expensive database queries.

The filter result count is saved (cached) for up to 5 minutes, however depending on how HelpSpot is used, the cached count may get invalidated often enough to cause slowness within HelpSpot.

HelpSpot admins can check on what filters may be causing issues in Admin > System > Filter Management. Problem filters will often be highlighted in red. These are ones whose database queries take over 1 second to complete.

The query time is an average, so seeing something take over 1 second often means many queries are taking longer. Query time may vary depending on the current load against the HelpSpot database.

To reduce issues caused by filters, you can:

1. Delete unused or rarely-used filters
2. Remove the option to show the request count next the filter ("Display count in Workspace" option)
3. Reduce the number of people who can see a filter
4. Reduce filters to only query within certain times or filter down to more specific sets of requests (this often helps but has potential to make the queries take longer! Test your filters with the "Run Filter" button before saving them).

13.3. Microsoft SQL Server

Connecting to a Named Instance

In order to connect to a named instance of SQL Server you will need to configure an alias for that instance as described in the Create an Alias section on this page: https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/create-or-delete-a-server-alias-for-use-by-a-client?view=sql-server-ver16

General SQL connectivity troubleshooting tips from Microsoft are available here: https://learn.microsoft.com/en-US/troubleshoot/sql/database-engine/connect/resolve-connectivity-errors-overview

Common Connection Troubles

• SQL Client Tools - On some servers you will need to install the SQL Server client tools. This is especially true if your SQL Server is on a different server than your web server.
  
  
• (local) Registration - If your SQL Servers registered name is (local) you'll need to delete that registration and change the registration to the machine name. You should then be able to set the DB_HOST in your .env file to 'localhost' and be able to connect.
  
  
• SQL Authentication - The SQL Server must be setup to use both SQL Server authentication and Windows authentication. Both for the user as well as the server as a whole. This setting is in SERVER_NAME->Properties->Security
  
  
• privileges - The HelpSpot database user must have sufficient privileges to access the database. Making them the database owner will work, though other configurations may also be effective. The database user will also usually need to have public access enabled.
  
  
• port number - On some PHP/SQL Server installations you'll need to provide the port number your SQL Server listens for requests on. You can do this by specifying the port number in the DB_PORT variable like in your .env file. (MS SQL is configured for port 1433 by default.)
  
  
• TCP/IP in SQL Server Configuration - In order to connect by IP you may need to specifically allow that protocol by going to the SQL Server Configuration Manager, go to Protocols and then enable TCP/IP.
  
  
• ntwdblib.dll - The most common issue is that you do not have the ntwdblib.dll file installed in your PHP directory (where php.exe is, or sometimes placing it in the ext directory works as well). This library can be found with your Enterprise Manager dll's or in your SQL servers system32 folder. It's generally best to take the file from the server where SQL Server is installed.
  
  
• ntwdblib.dll Version - On some systems the ntwdblib.dll version is too old to work correctly with PHP. If your version does not end in 80.194.0 it's probably too old. You can download the 80.194 version here.
• Registry key - In rare cases an edit to the registry may help.
  [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSSQLServer\Client\ConnectTo]
  "DSQUERY"="DBNETLIB"

Error: "The statement has been terminated."

In extremely rare cases SQL Server can lose seeding on the HS_Request table or another tables, primary key. If this occurs inserts to the database will fail with this error. You can check if this is the case by running the following in management studio:

DBCC CHECKIDENT ('HS_Request');

If the current seed value doesn't match the current column value (it will be less) than there's a problem. You can reseed the tables primary key with this command:

DBCC CHECKIDENT ('HS_Request',RESEED,######);

where ###### is the new ID value. Make this a few higher than the current highest value in the table. That should resolve the issue.

Moving from local SQL Server to SQL Server on RDS

13.4. Microsoft Exchange Server

Exchange 2010 Slow Delivery / Request Duplication

Exchange 2010 has a new tarpit feature that forces a 5+ second delay between each email sent on a connection. This is designed to help combat spammers, however, it's often necessary for HelpSpot to send a group of emails at once and this feature of Exchange can cause problems. At the very least it slows down email sending causing the request screen to feel slow on updates. More significant issues can be seen if your installation does a lot of notification emails to staff on import as each email will have a 5 second delay between them meaning importing a single email could take a minute or more. In such cases the scheduled tasks which pull in email may end up duplicating some requests as one running of tasks.php is still going (due to the delay) while a second is initiated.

The setting in Exchange can be checked with this command:

Get-ReceiveConnector "connectorname" | select tarpitinterval

The setting can be turned off with:

Set-ReceiveConnector "connectorname" –TarpitInterval 00:00:00

Make sure to run the command for each connector name your installation has.

Acknowledgement Delay

Sometimes Exchange 2010 still has delays in sending multiple messages. Exchange may be making HelpSpot wait until it has received confirmation that a sent email was received by the recipient mail server. This is called "acknowledgement delay".

To eliminate the acknowledgement delay, run the following command:

Set-ReceiveConnector "SMTP Application relay" -MaxAcknowledgementDelay 0

Exchange 2010 Rate Limit Exceeded

The setting in Exchange can be checked with this command:

Set-recieveconnector "Server Name\Client Connector" -Messageratelimit 500

Connection Troubles

• Pop3/IMAP - Make sure Pop and/or IMAP is enabled on your Exchange server. These options are often off by default.
• Password - If your POP or IMAP password contains a backslash (ex: \ ) this will break the connection. Remove the backslash from your Exchange password and the connection should work.
• NOTLS - On Exchange 2007 it is sometimes necessary to choose the NOTLS security option.

Kerberos Error

"Kerberos error: Credentials cache file '/tmp/krb5cc_33' not found (try running kinit)" Note that the number appended to the cache file may be different.

This error can occur if the number of simultaneous connections exceed the limit. The Exchange error log should show the errors. Restarting Exchange usually clears the issue.

Using IMAP or IMAPS instead of POP/POPS within HelpSpot's Email Mailbox configurations can also alleviate this issue if the error is seen.

Routing through IIS

It can sometimes be useful to route email via IIS's built in SMTP relay system. Note, that in some configurations you may want to set this up to forward the email to Exchange from IIS. The basics on setting it up can be found in this article: http://www.geeksengine.com/article/php-microsoft-smtp.html

PHP Bug 33500

There is some evidence that Microsoft Exchange Rollup 7 fixes the issues below. Please upgrade to rollup 7 before trying any of the below procedures.

Items below relate to PHP bug: http://bugs.php.net/bug.php?id=33500 which affects Exchange 2007.

Note, that the first thing to check before doing the below is that your Exchange server is set for

"Plain text logon (Basic authentication) No TLS connection is required for the client to authenticate to the server"

and NOT

"Plain text authentication logon (integrated windows authentication) No TLS connection is required for the client to authenticate to the server"

If you have multiple front end Exchange server be sure all are setup for basic plain text login.

Also be sure you don't have any # in your mailbox passwords.

Authentication Trouble on Exchange 2007 - Kerberos

Under certain configurations in Exchange 2007 having Kerberos setup is required in order to connect to the Exchange server. A customer contributed these steps on how to set that up in a Linux environment.

Step 1:
Edit the krb5.conf file to match your domain environment.

Step 2:
Create a script to check the mail that creates the ticket if it does not exist already then checks the mail. This script should be called via cron instead of tasks.php directly:

/usr/kerberos/bin/klist -c /var/tmp/apache | grep -q krbtgt || echo <mailboxusename> |
/usr/kerberos/bin/kinit -c /var/tmp/apache <mailboxusename>
export KRB5CCNAME=/var/tmp/apache

/usr/bin/php /var/www/html/helpspot/tasks.php

Step 3:
Add another crontab entry that renews the kerberos ticket every hour:

/usr/kerberos/bin/kinit -R -c /var/tmp/apache

Alternative: Recompile PHP with IMAP Adjustment

On Linux based installations recompiling PHP and making an adjustment to the IMAP source is also a possible solution. This method was tested on CentOS 5.1 and is still needed at least up to PHP 5.2.9.

1. Download the latest IMAP Toolkit release at ftp://ftp.cac.washington.edu/mail/imap.tar.Z
2. Extract the files, then open up imap-2007/src/osdep/unix/Makefile and go to line 1002. Comment out the following section:
   

   ckpgss: # Kerberos V (must have gss EXTRAAUTHENTICATOR as well)
           @echo Kerberos V password authentication
           $(LN) ckp_gss.c osdepckp.c
   

3. Save the file and exit. Change dirs back to the imap-2007 directory and build with the following: 
   make slx SSLINCLUDE=/usr/include/openssl SSLTYPE=nopwd
   
4. Once complete, download the latest PHP from php.net. Extract the files, then run configure with the following options (you may need to adjust these options as needed for your setup):
   ./configure --without-kerberos --with-zlib --with-curl=/usr/lib --enable-dba --with-gd --enable-gd-native-ttf --with-jpeg-dir=/usr/lib --with-png-dir=/usr/lib --with-zlib-dir=/usr/lib --with-imap=/PATH-TO/imap-2007 --with-imap-ssl --enable-mbstring --with-mysql=/usr/lib/mysql --with-mysql-sock --with-mysqli --enable-soap --enable-sockets --with-pear --with-mcrypt --with-openssl --with-xml --with-apxs2=/PATH-TO/apxs --enable-memory-limit --enable-track-vars --enable-wddx --enable-ftp --enable-sysvmsg --enable-sysvem --enable-sysvshm --enable-transid --enable-cli --enable-cgi --with-ldap
   
5. There may be a bunch of package dependencies (like libmcrypt, libmcrypt-devel, openssl, openssl-devel, httpd-devel, etc.) that I won't go into here. Basically, if configure errs out and complains about a package not being installed, then install it and go from there.
   
6. Then run make, make test, and finally sudo make install.
   
7. Once it's installed, you'll need to add the following to /etc/httpd/conf/httpd.conf if you don't have it already:
   LoadModule php5_module /usr/lib/httpd/modules/libphp5.so
   AddType application/x-httpd-php .php
   AddType application/x-httpd-php .phtml
   

8. Restart Apache and you should be all set.

13.5. Missing Microsoft.pem File

Email Mailboxes will not connect to O365 via new OAuth connection

On some subversions of HelpSpot v5, a file required for Microsoft OAuth connectivity is overwritten and not restored during upgrade. If you are setting up a new Email Mailbox using OAuth authentication and it fails to retrieve incoming messages, this is one possible cause. This missing file may also produce errors in the helpspot.log file (located in the /storage/logs subfolder under the site root directory) similar to either of the following:

• Error: OpenSSL unable to sign data DETAILED CONNECTION DUMP
• production.ERROR: DomainException: OpenSSL unable to sign data in C:\Program Files (x86)\helpspot\helpspot\vendor\firebase\php-jwt\src\JWT.php

You can verify this condition by searching for a microsoft.pem file in the /storage/keys subfolder under the site root directory. 

If the file or the entire /keys folder is missing, you will need to create the keys folder within the storage directory and manually copy the microsoft.pem file to that location. Reloading Apache/NGINX (on Linux) or performing an iisreset (on Windows) may be necessary to ensure the new file is identified by the system.

The download referenced in this page contains the file in a ZIP which can be downloaded and extracted into the /keys folder.

13.6. MySQL

How to Repair a MySQL Table on Windows

If you've used our Windows Installer and need to rebuild a table this is how to do it. If you're experiencing odd behavior such as filters with counts not actually showing the requests when entered this could be the case.

Steps to repair the table:

1. Open the command prompt
2. enter: cd "c:\program files\helpspot\mysql\bin"
3. enter: mysql -u HELPSOT_USER -p
4. enter your password when asked
5. enter: use HELPSPOT_DATABASE;
6. enter: repair table HELPSPOT_TABLE;

Table Creation Errors

On some MySQL servers during installation only some of the tables will be created. Normally when this error occurs it's about 19 tables that are created. When this occurs the screen of the installer will often turn blank white while trying to complete installation.

This error is caused by MySQL being set in STRICT mode. Your my.cnf or my.ini file probably has a line similar to this:

sql-mode="STRICT_TRANS_TABLES"

Removing the strict restriction should allow installation to complete normally.

13.7. MySQL - Convert Lowercase Windows Table Names to Mixed Case for Linux/Unix

When converting a MySQL database from Windows to Linux/Unix the Windows server will often export the database table names in all lowercase. HelpSpot on Linux/Unix requires mixed case table names.

This script will convert the lowercase names into proper mixed case names.

There are separate scripts for V2 and V3

Usage:

1. Place this file in the same directory as config.php
2. Visit the script in your browser
3. Delete the script

13.8. Microsoft IIS

PHP CGI Error in IIS

On some PHP installations running as a CGI on Windows IIS a CGI 502 error is received at random. This is a bug in the interaction between PHP and IIS and is not HelpSpot specific. It appears to happen most on fast servers which are under low load. One options is to run PHP as an ISAPI module. However, if you would prefer to keep it as a CGI there appears to be an effective workaround for the issue.

The workaround works by telling Windows to optimize for foreground applications instead of background services. This appears to slow down the processing enough so that IIS doesn't throw an error. Please be aware that this is a system wide setting and will affect the overall speed of your server to some degree. If you change this setting it is highly recommended that you keep close watch on the server afterwards to make sure none of your applications have been adversely affected.

On Windows Server 2003 go to: Start -> Control Panel -> System -> Advanced (tab) -> Performance (settings) -> Advanced (tab) -> and switch "adjust for best performance of" to "Programs". Apply the change and the effect should be immediate.

On Windows 2000 go to: Start -> Settings -> Control Panel -> System -> Advanced (tab) -> Performance (performance options) -> Select "applications". The change should be immediate.

This solution was discovered in the discourse of this PHP bug history: http://bugs.php.net/bug.php?id=9852

Note: that this solution does not always work when PHP is used with the MS SQL extension. When this solution fails while using the MS SQL extension the only solutions appear to be to switch PHP to ISAPI or switch to using MySQL or PostgreSQL.

IIS Crashes every few hours or more, tasks.php takes a significant time to run

An upgrade to .net version 3.0 can partially cause this issue. Note that .net is not used by HelpSpot, but the upgrade causes permission issues which cause IIS to be unstable. This situation can be fixed following the information in this article: http://support.microsoft.com/kb/918041.

If the situation persists after the fix uninstalling .net v2 may be needed using aspnet_regiis.exe -u followed by aspnet_regiis.exe -u started from: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727

Live Lookup fails to load

This can sometimes be happen when using IIS due to it's low maxQueryString setting. Resources and details on how to adjust that:

• http://support.microsoft.com/kb/942071
• http://www.iis.net/ConfigReference/system.webServer/security/requestFiltering/requestLimits
• http://learn.iis.net/page.aspx/143/use-request-filtering/

• Control Panel > Administrative Tools > Internet Information Services (IIS) Manager
• In the Connections pane, drill down to the relevant site you want to modify. Something Like SERVER > Sites > Default Web Site.
• In the Home pane for Default Web Site, open Request Filtering.
• In the Action pane, click Edit Features Settings.
• Maximum query string defaults to 2048; set it to 10240 and click OK.
• Close IIS Manager, and restart the World Wide Web Publishing Service.

Attachments Do Not Upload to a Network Drive

HelpSpot allows the Attachment Storage System to optionally save to the file system, rather than the database. If you have set the file path to a network drive (typically a path such as "\\path\to\shared\directory") and attachments are not successfully being saved, it is important to ensure proper credentials are set. If the IIS worker processes runs under a user who has permission to write to the network drive and attachments still are not saved correctly, then the Application Default settings may need to be set with the username and password of the user with permission to write to the network drive.

Process:

1. Within the IIS Manager, select your site from the Connections pane on the left by clicking on it. This is typically labeled "Default Web Site".
2. Click the "View Applications" link in the Actions pane on the right.
3. Options within the Actions pane will change. Click "Set Application Defaults" with the Actions pane.
4. Next to "PhysicalPathCredentials", click the empty field with the smaller button containing three dots(...). This will open a new window labeled "Connect As"
5. Choose "Specific User", Click the "Set" button, and enter the username and password of the user who has permission to write to the shared drive.

A. Pictured: Click the "View Applications" link in the Actions pane on the right.

B. Pictured: Set Application Defaults, Choose Physical Path Credentials, Select Specific User, Enter Credentials

13.9. IIS: WSUS (Windows Server Update Services) And HelpSpot - 500 error

If you are using Microsoft IIS and install WSUS (Windows Server Update Services), you may receive an 500 error post-installation when viewing HelpSpot. This usually says there is an issue with the web.conf file, however that is a generic error message.

If you see the Module in question in the error message is the CompressionModule, this is a known issue. (You'll have to access HelpSpot locally on a browser within the web server to see the full error message).

This issue is outlined and resolved here: http://forums.iis.net/t/1149768.aspx?500+19+Error+When+Enabling+32+bit+Application+Pool

WSUS enables a CompressionModule, which is not compatible with HelpSpot's installation. To resolve this issue, you must disable the CompressionModule. TO do so, run the following command (taken from the previous linked article) and run it in the CMD prompt. This command will not work within PowerShell:

%windir%\system32\inetsrv\appcmd.exe set config -section:system.webServer/httpCompression /-[name='xpress']

13.10. Portal Pages Sometimes Return Blank

This error is sometimes found on servers running Apache 1.3 and using the mod_gzip module. To fix this error create a .htaccess file in the base directory of your HelpSpot installation. Within the .htaccess file add the following line:

mod_gzip_item_exclude file .*

Save the file and the blank pages should stop appearing.

13.11. Month names are not translated

You can adjust the date and time that HelpSpot displays by going to "admin -> settings -> date and time" and then selecting the proper format from the drop-down lists. This setting will only adjust the way it's formatted and if you would like to have the month names translated then you can edit the lg.charset.php file and adjust the setlocale line: 

setlocale(LC_ALL, 'en-us','english');

For example to have month names displayed in Swedish you could use: 

setlocale(LC_ALL, 'sv_SE', 'Swedish', 'swedish');

If you've made that change and the month names are still in English then your server may not have the locale installed. 

You can verify a list of installed locales on Unix/Linux servers by running: 

locale -a

If yours is not displayed in the list, you can utilize the locale-gen command to install additional: 

locale-gen de_DE de_DE.utf8

13.12. fPinned Duplicate Column Error

Note: This error has been fixed in the latest version 4.5.4+ of HelpSpot. Please download the latest installer.

Some customers have run into an error when installing the 4.5 update that indicates there is a duplicate column named fPinned on the HS_Request_History table. This error can be fixed by following the steps below.

1. Open up your helpspot database in the database editor of your choice.
2. Run this query: Select * from HS_Migrations;
3. Look at the last migration listed in the results and note the number in the "batch" column
4. Run this insert query to add the needed migration history to the database

INSERT INTO `HS_Migrations` (`migration`, `batch`)
VALUES
	('2016_02_18_211111_add_pinned_to_request_history', 2);

13.13. LDAP connections with Self-Signed SSL

This condition is indicated by an error in the HelpSpot log file stating:

BindException: Can’t contact LDAP server in C:\inetpub\wwwroot\vendor\adldap2\src\Auth\Guard.php

You should first confirm that there is no firewall rule blocking port 389 (standard LDAP) or port 636 (LDAPS).

If you can telnet to the LDAP server specified in HelpSpot's settings on the LDAP ports from the HelpSpot server, but it still fails to authenticate users, select one of the options below to resolve the issue.

Note: The Windows PHP libraries are hard-coded to look for an open ldap config file (ldap.conf) in C:\openldap\sysconf\ldap.conf. On Linux you should be able to find it in /etc/openldap/ldap.conf

13.14. Blackbox ADLAD Error on PHP 7.4+

When using the adldap library for blackbox authentication with php 7.4+ the adLDAPUsers.php file needs to be updated for compatibility. In custom_code\classes\adLDAPUsers.php find this line:

        for ($i=0; $i <strlen($password); $i++){ $encoded.="{$password{$i}}\000"; }

and change it to:

        for ($i=0; $i <strlen($password); $i++){ $encoded.="{$password[$i]}\000"; }

14.1. Converting Attachments from Database Storage to File System

HelpSpot allows the option to save all request file attachments in the database. This makes for easy backups. However, on some high volume installations or installations which deal in many large attachments it's better to save the attachments to disk to prevent the database from becoming unwieldy.

Moving to File System Storage

1. Create a directory to store attachments in. This directory should be outside the web root and writable by the web server.
2. In Admin->Settings->System change Attachment Storage Location to "Server File System"
3. In the box that appears (Attachment File System Directory) put the full path to the directory you created
4. Save the settings

Converting Database Stored Attachments to the File System

HelpSpot 4.0+

By default, after the change above HelpSpot will store new attachments to the file system, but old attachments will continue to be stored and served from the database. On version 4 and greater you can use the HelpSpot command attachments:tofile 

HelpSpot 3

If you'd like to convert these old attachments on HelpSpot version 3 to the file system you can use the script linked below do to so. To use the script:

1. Download the script below, move it to the root HelpSpot folder. This is the one with config.php in it. If using FTP to move the file be sure to force binary mode.
2. Backup your database (seriously)
3. Place HelpSpot in maintenance mode to prevent new requests while the script runs (Admin->Settings)
4. From the command line do "/path/do/php -f /path/to/convert_attach_from_db_to_file.php"

14.2. Changing Custom Field Lengths

Custom field lengths at the database level are only editable on creation within the user interface. If changes to field size need to be made after creation, these changes must be made at the database level. These instructions are specific to the Text Field type. Note that the following instructions can be destructive (resulting in the truncation of data) if you are reducing field lengths. Because of this, it is recommend to make a database backup before performing these operations.

MySQL

1. Change the size of text field in the user interface via the custom field setup area (Admin > Custom Fields)
2. Note custom field ID in this interface.
   
3. Access your helpspot database and run this query to change your field size. 

// Replace 'Custom1' with the associated ID for your custom field and replace VARCHAR(25) with the appropriate length.
ALTER TABLE HS_Request MODIFY Custom1 VARCHAR(25); 

SQLServer

1. Change the size of text field in the user interface via the custom field setup area (Admin > Custom Fields)
2. Note custom field ID in this interface.
   
3. Access your helpspot database and run this query to change your field size. 

/****** Drop the current index on the custom field ******/
DROP INDEX [hs_request_custom1_index] ON [dbo].[HS_Request]
GO

/****** Alter the column length ******/
ALTER TABLE [dbo].[HS_Request]
ALTER COLUMN [Custom1] [nvarchar](80) NULL

/****** Rebuild index on the custom field ******/
CREATE NONCLUSTERED INDEX [hs_request_custom1_index] ON [dbo].[HS_Request]
(
	[Custom1] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, SORT_IN_TEMPDB = OFF, DROP_EXISTING = OFF, ONLINE = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON)
GO

14.3. Search Request History by Customer Email

This template adds the ability for customers to search for their past requests by entering their email address rather than an access key. Searching by email will give them a complete list of all requests ever submitted by that email address. Note that this is completely insecure by default. However, it would be possible to tie the search into an active directory login or LDAP user in order to make it secure, though this template does not provide the code for that integration.

14.4. Delete SPAM Without Training Filter

Some customers have very high SPAM counts and cannot delete it all conveniently via the web interface. They no longer need to train the SPAM filter with every SPAM since it's already catching them.

This script will delete all references to any requests currently marked as SPAM without training the SPAM filter. This is a destructive script. It will permanently delete requests and if any real requests are accidentally marked as SPAM when this script runs they will also be deleted.

Instructions for V4 and above

1. Follow these instructions to access the helpspot command line tool
2. Use the command: php hs request:delete-spam

Instructions for V3.2.12 and below

1. Download the delete_spam.php script below
2. Place the script on your server. It's recommended you run it from the command line and place the script outside the web root so that outsiders cannot run it
3. Make sure the 2 includes() at the top of the file have the correct paths to the files they're including
4. Run the script, usually something like: /usr/local/bin/php -f /path/to/delete_spam.php

14.5. Hidden Settings

Several settings are available in HelpSpot that are not part of the user interface in the admin area. These settings are advanced and should only be used if you know they are needed.

Config.php Settings

• Secure MySQL Connections - Some MySQL setups, especially on remote servers, require a secure client connection. Adding the line below to you config.php file will force HelpSpot to connect securely. Should be used only if you know it's necessary.
  
  define('cMYSQL_CLIENT_SSL',true);
  
  
• Additional SMTP Security Settings (Version 4.6+) — Some SMTP connections require a specific version of TLS in order to connection properly. Adding this setting will enable additional options on the SMTP setup screens in the admin area.
  
  define('cEXTRASECURITYOPTIONS', true);
  

HS_Settings Table

In the HS_Settings table, the items below relate to rows in the sSetting column. Updating the tValue column in rows where sSetting matches the values described below.

• cHD_BAYESIAN_PROB_SPAM and cHD_PORTAL_BAYESIAN_PROB_SPAM - The probability value an email or portal post must be above to be considered spam.
• cHD_LIVEREFRESH_TIME - How often in seconds the Live Refresh of the Workspace refreshes the filter currently being viewed.
• cHD_SAVE_DRAFTS_EVERY - How often in seconds to save drafts of requests notes while on the request screen.
• cHD_IMAGE_THUMB_SIZE - Size in pixels of image thumbnails created for the request history.
• cHD_DISABLESHORTCUTS - Change to 1 to disable shortcut commands from being replaced in notes (these are r: k: f: which create shortcuts to requests, KB's and forums respectively)
• cHD_IMAGE_THUMB_MAXBYTES - The number of bytes an image can be before HelpSpot will stop attempting to create a thumbnail version of the image in the request history.
• cHD_TAKEIT_DOCHECK - The "Take It" button column in filters by default will check to see if a request is already assigned and if it is, show an error not allowing the clicking user to take the request. This setting allows a change in this behavior where the clicking user will always be assigned the request, no check will be done.
• cHD_SAVE_LAST_SEARCH - The number of seconds a search done in the search tab is saved for so that when you return it's still there ready to be modified. Defaults to 1200 seconds (20 minutes).
• cHD_FILTER_COUNT_CACHE - The number of seconds to cache the counts for each filter on the workspace screen. Defaults to 300 (5 minutes). Lowering this value is not recommended. If you need to exclude a particular filter from the cache that can be done under the advanced options for that filter.
• cFORCE_MERGE_LOCKING - (MySQL ONLY) - force the database to lock all request related tables while merging requests. You should only enable this if you have a good performing server stack for HelpSpot (and plan to keep it that way as HelpSpot grows). If you're on shared hosting or running a large installation on a small server configuration turning this on can cause performance issues due to database contention.
• cHD_DISABLE_GRAVATAR - Disable gravatar images and always fall back to the default supplied by HelpSpot.
• cHD_MAX_REQUEST_HISTORY — Set the max number of request history entries that is allowed for any one request. Default is 1500.
  

14.6. Redirect HTTP Requests to HTTPS

IIS

Note you must have an SSL certificate properly installed and https bindings set up properly in IIS before completing these steps. In addition be sure to edit the APP_URL variable in your .env configuration file for HelpSpot to reflect the https:// url. 

1. Install the rewrite module in IIS following these directions http://www.iis.net/downloads/microsoft/url-rewrite
2. Open the IIS Manager and navigate to the site that your helpspot instance is installed on.
3. Select URL Rewrite and add a new rule.
4. For the pattern to match input the regular expression.*
5. Add a new condition that checks if {HTTPS} is off

6. For the action choose to redirect to https://{HTTP_HOST}/{R:0}

You site should now redirect urls that are http:// to https://

14.7. Trigger-Based Auto-Replies

Although not a part of the New Request Loop Protection settings, Trigger-based Auto-Replies can be set up to automatically reply to customers when a request is created, so the auto-replies only get sent for new incoming requests which don't contain the Request ID appended to the subject line. The advantage of trigger-based auto-replies is that you can add extra conditions to enhance functionality. 

For example, you could define two triggers to send different auto-reply text to customers contacting you via two different Email Mailboxes. You can also add conditions to the triggers which exclude sending auto-replies to inbound new messages from senders containg "noreply" or "no-reply" in the email address. You can even set up a separate trigger to immediately trash incoming requests received from "noreply" or other specific email accounts.

Things to keep in mind if electing to create trigger-based auto-replies:

• Trigger-based auto-replies don't preclude the need for New Request Loop Protection configuration.
• Users electing to set up trigger-based auto-replies should disable mailbox-level auto-replies (at least on mailboxes configured within the trigger conditions) to prevent customers from receiving duplicate new request notifications.
• The message content for trigger-based auto-replies is defined in the trigger actions, rather than in the Auto-Reply email templates associated with particular Email Mailboxes.
• Because trigger-based auto-replies get their message text from trigger actions, the message text passes through the Public Notes to Customers Email Template (or External Notes Email Template), expanding in the location of the {message} placeholder within the respective template's definition.

15.1. Connecting Thermostat.io and HelpSpot

To begin setting up the integration between Thermostat and HelpSpot go to thermostat.io and login to your account.

Next, go to HelpSpot and make sure you have upgraded to at least version 4.8.8. After this has been verified you are ready to start the integration.

1. Login to the admin area and select “Integrations.”

   

2. On the integrations page, click on “Get an API Token” in the thermostat area. 

3. This will open a new screen on thermostat.io where you can click on the “Enable HelpSpot Integration” button.

4. Once you click on that button a popup will appear with you API key.

5. Copy the token and then paste it on the HelpSpot integrations page.

6. Click on save Thermostat API Token.

Your Thermostat and HelpSpot applications are now connected.

15.2. Instantly Sending A Thermostat Survey In HelpSpot

A Thermostat survey can be configured to send instantly to the customer based on a Trigger or Automation action in HelpSpot. In this example we will be using the trigger action. When a survey is sent using the “Send a Thermostat Survey” action, the survey will be sent to the customers email when the action is triggered.

If a campaign is enabled on the survey they will also be added to a scheduled delivery of that Thermostat survey. If a campaign is not enabled on the Thermostat survey, the action will be treated as a one-time send.

In this example we will set up a trigger that emails customers a Thermostat survey when their request is closed with the status of “Problem Solved.” The criteria used here are only one example, your use case may dictate other criteria. To set up a trigger that sends a survey to customers:

1. Navigate in HelpSpot to Admin > Triggers & Rules > Triggers
2. In a new trigger define two criteria, one for a the request being changed to closed and the other for the status being “Problem Solved.
   
3. In the actions area select the “Send a Thermostat Survey” action and then select the appropriate survey that you wish to deliver to your customers
   
4. Add the completed trigger.

This is a complete example. 

Now whenever a request is closed with the “Problem Solved” status thermostat will automatically email that customer a survey.

15.3. Adding HelpSpot Customers To A Thermostat Campaign

HelpSpot customers can be added to a NPS or CSAT survey campaign via a trigger or automation in HelpSpot. Thermostat campaigns will survey customers on a regular basis as apposed to sending a one-off survey. This allows you to continually track change in your customer's sentiment.

The Add Email to Survey Campaign can be found in the actions area of both Automations and Triggers. You can choose which survey in your Thermostat account you wish to add the customer to.

When an email is added to a campaign in Thermostat, the campaign still needs to be enabled in Thermostat. This is done by logging into Thermostat and choosing the "Email Survey" option. From there you can enabled your automatic campaign.

15.4. Sending a Thermostat Survey Via a Customer Email Action

This method, uses HelpSpot to send the actual email instead of thermostat's email option campaigns. Thermostat results will still be passed back to the appropriate request id in order to be filtered and displayed in HelpSpot.

Setting up the Thermostat survey.

1. Link your Thermostat and HelpSpot accounts using the directions found here.
2. Login to thermostat and select the survey you wish to integrate with.
3. Select Fields from the left hand menu
4. Create a custom text field titled xrequest. If you wish to map other custom fields from HelpSpot into Thermostat you can create the fields here as well.

Creating the sending trigger

Now that Thermostat and HelpSpot are linked and the survey is set up to receive HelpSpot request IDs we can set up a trigger in HelpSpot to send out our survey link.

1. In Thermostat, select link, then Copy the link to your survey
2. Login to HelpSpot
3. Click on Admin > Triggers & Rules > Triggers (You can also use an automation to send the survey as well. Which one you use will depend on the criteria you want to use to send out your survey link)
4. Create a new Trigger with the desired criteria for when you want to send out a survey. For example you may want to send a survey when a request is closed with the status of "Problem Solved."
5. Add an Email Customer action. In the body of this email we will include a link with the xrequest parameter appended as a url variable. We will then automatically fill in the xrequest by using the ##REQUESTID## placeholder. A complete link will look like this: 
   <a href=https://thermostat.io/s/thesurveyid?xrequest=##REQUESTID##>Let us know how we did!</a>
   
6. If you wish to add other custom fields to be passed into Thermostat you can do so by adding additional parameters to the url in the form of &thermostatcustomfieldname=##CUSTOMFIELDTAG##

After the trigger is saved HelpSpot will begin emailing customers their unique survey links. As customers answer the survey results will flow back into HelpSpot.

15.5. Viewing Survey Results In Filters

Thermostat survey results can be viewed in HelpSpot filters as well. Thermostat results are available HelpSpot filters as both filter criteria and filter display columns.

To Use Thermostat Survey Scores as Criteria

HelpSpot filter criteria includes a thermostat score criteria. We include the usual less than, greater than and equal to options for filter numeric scores. We also make it easy to find just detractors, passives or promoters by allowing those ranges to be selected automatically.

Remember that filter criteria can also be used in reports. This means that you can surface some very interesting information. For example you could run a first response speed report for all of your detractors to see if response time may have played a roll in their rating.

Adding the Thermostat Score Column to Filter.

The Thermostat score column can be added to filters just like any other column in HelpSpot filters. 

Once the column is added, the thermostat results for each request will be available in HelpSpot. The results column shows both the NPS rating (Promoter, Passive, Detractor) and the raw numerical score.