Skip to main content

Hotjar

Hotjar is a behavior analytics and user feedback platform that helps businesses understand how users interact with their websites. With Hotjar, you can visualize user behavior through heatmaps, watch session recordings, collect feedback through surveys and polls, and analyze user experience data. It's designed to help product teams, UX designers, and marketers optimize their websites and improve conversion rates.

Authentication Types​

Hotjar supports 1 authentication method:

  • Client Credentials - Machine-to-machine authentication using API keys for automated access.
    • Pros: Simple setup, secure for server-side applications, no user authorization flow needed
    • Cons: API keys expire after 1 year and must be regenerated, full access to organization data, requires Scale plan for some features
    • Best for: Backend integrations, automated reporting, data exports, GDPR compliance tools

General Settings​

Before using the connector, you'll need:

  • Site ID - Your Hotjar site identifier (found at https://insights.hotjar.com/site/list under your organization)
  • Organization ID - Your organization identifier (required for user lookup operations, found at https://insights.hotjar.com/site/list)
tip

The Site ID is displayed in the Sites & Organizations page. Each site has a unique numeric identifier that you'll use in most API calls.

Setting up Client Credentials​

To use Hotjar with Webrix, you need to generate API credentials from your Hotjar account.

1. Access API Settings​

  1. Log in to your Hotjar account

  2. Navigate to Settings → API or go directly to https://insights.hotjar.com/settings/api

  3. You must have admin permissions in your Hotjar organization to access this page

2. Generate API Key​

  1. Click Generate API Key or Create API Key

  2. Give your API key a descriptive name (e.g., "Webrix Integration")

  3. Click Generate or Create

  4. You'll receive two credentials:

    • Client ID - Your API key identifier
    • Client Secret - Your API key secret

  5. Copy both values immediately

Important
  • Keep your Client Secret secure and never share it publicly or commit it to version control
  • API keys automatically expire after 1 year and cannot be extended
  • You must generate a new key before expiration to maintain access
  • Set a calendar reminder for 11 months from now to regenerate the key

3. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select Hotjar and click Use

  3. Under Authentication Type, select Client Credentials

  4. Paste your Client ID in the Client ID field

  5. Paste your Client Secret in the Client Secret field

  6. Click Save Changes

4. Test the Connection​

  1. After saving, click Test Connection to verify your credentials

  2. If successful, the connector will exchange your credentials for an access token

  3. You can now use the Hotjar tools to access your data

Plan Requirements​

Some Hotjar API features require specific plan levels:

  • Survey Response Export: Requires Ask Scale plan
  • User Lookup & Deletion: Requires Observe Scale plan or Ask Scale plan
  • Sentiment Analysis: Requires Ask Scale plan

If you attempt to use features not included in your plan, you'll receive an error message. Contact Hotjar sales to upgrade your plan.

Troubleshooting​

API Key Expired​

Users see authentication errors or "invalid credentials" after the connector was working previously.

Cause: Hotjar API keys automatically expire after 1 year and cannot be extended.

Solution:

  1. Go to https://insights.hotjar.com/settings/api
  2. Delete the old expired API key
  3. Generate a new API key with a descriptive name
  4. Copy the new Client ID and Client Secret
  5. Update the credentials in Webrix under Integrations → Hotjar → Authentication
  6. Save and test the connection
  7. Set a reminder for 11 months from now to regenerate again

Invalid Site ID Error​

API calls fail with "Site not found" or 404 errors.

Cause: The site_id parameter is incorrect or the site doesn't exist in your organization.

Solution:

  1. Go to https://insights.hotjar.com/site/list to view all your sites
  2. Find the numeric Site ID next to each site name
  3. Verify you're using the correct Site ID in your API calls
  4. Ensure your API key has access to the organization containing this site

Rate Limit Exceeded (429 Error)​

API requests fail with HTTP 429 status code.

Cause: Hotjar enforces a rate limit of 3000 requests per minute (50 per second) per API key.

Solution:

  1. Implement exponential backoff in your retry logic
  2. Reduce the frequency of API calls
  3. Use pagination more efficiently (increase limit parameter to reduce number of calls)
  4. Cache results where appropriate to avoid redundant requests
  5. If you consistently hit rate limits, consider spreading requests over time or contacting Hotjar support

Scale Plan Features Not Available​

API calls for survey responses or user lookup return permission errors.

Cause: These features require a Hotjar Scale plan (Ask Scale or Observe Scale).

Solution:

  1. Verify your current Hotjar plan in Settings → Billing
  2. Contact Hotjar sales at https://contentsquare.com/request-a-demo/ to upgrade to a Scale plan
  3. Ask Scale includes: Survey response export, user lookup, sentiment analysis
  4. Observe Scale includes: User lookup and deletion
  5. After upgrading, your existing API credentials will work with the new features

Token Exchange Failures​

Authentication fails during token exchange with "invalid_client" error.

Cause: The Client ID or Client Secret is incorrect, or the credentials were copied with extra whitespace.

Solution:

  1. Verify you copied the full Client ID and Client Secret without truncation
  2. Check for leading/trailing spaces in the credentials
  3. Regenerate the API key if you're unsure of the correct values
  4. Ensure you're using Client Credentials authentication, not OAuth
  5. Verify the API key hasn't been deleted in Hotjar settings

Missing Organization ID​

User lookup operations fail with missing organization_id parameter.

Cause: The organization_id is required for user lookup and deletion operations.

Solution:

  1. Go to https://insights.hotjar.com/site/list
  2. The Organization ID is displayed at the top of the page or next to your organization name
  3. Copy the numeric organization identifier
  4. Include it in the organization_id parameter when calling user lookup/deletion tools
  5. Note: Organization ID is different from Site ID

Empty or Null Responses​

API calls succeed but return empty results or null data.

Cause: The site may not have collected data yet, or filters are too restrictive.

Solution:

  1. Verify the site has Hotjar tracking installed and is collecting data
  2. Check that surveys, polls, or forms have received responses
  3. For recordings and heatmaps, ensure sufficient time has passed to collect data
  4. Review your filter parameters (date ranges, device types, etc.)
  5. Try listing resources without filters first to confirm data exists
  6. Visit your Hotjar dashboard to verify data is visible there

Sentiment Analysis Not Working​

Survey responses don't include sentiment data despite using sentiment features.

Cause: Sentiment analysis requires Ask Scale plan and must be enabled for the survey.

Solution:

  1. Verify you have an Ask Scale plan
  2. Check that sentiment analysis is enabled for your survey in Hotjar dashboard
  3. Sentiment is only available for text-based question types (short-text, long-text)
  4. Sentiment analysis only applies to new responses after it's enabled
  5. The sentiment field will be null for non-text answers or when sentiment isn't set

Additional Resources​