Widget setup and configuration

The Support widget is a chat interface that appears on your website, allowing users to start conversations with your team. It loads automatically when enabled and captures session context for each ticket.

Enabling the widget

1. Go to Support in PostHog and click Settings
2. Click Enable conversations (if not already enabled)
3. Go to the In-app widget section and enable it
4. Configure your settings (see below)
5. Save

The widget appears as a floating button on your site. By default it appears in the bottom-right corner, but you can customize its position in the settings.

Widget configuration

These settings are configured in the In-app widget section of Support settings.

Identification form

You can optionally require users to identify themselves before starting a conversation:

When enabled, the form appears before they can send their first message. The collected information is used to link the ticket to a person in PostHog.

Domain restrictions

You can restrict which domains the widget appears on for security:

// Configured in PostHog settings
domains: [
  "example.com",              // Exact match
  "*.example.com",            // Wildcard: matches sub.example.com
  "https://app.example.com"   // With protocol (protocol is stripped)
]

If domains is empty or not set, the widget shows on all domains.

Controlling widget visibility

Use the JavaScript API to programmatically show or hide the widget:

// Show the widget (renders it if not already rendered)
posthog.conversations.show()

// Hide and remove the widget from DOM
posthog.conversations.hide()

// Check if widget is currently visible
const isVisible = posthog.conversations.isVisible()

This is useful for:

• Showing the widget only on certain pages
• Triggering the widget from a custom button
• Hiding the widget during specific user flows

Disabling the widget via config

You can disable conversations entirely via the PostHog init config:

posthog.init('<ph_project_token>', {
  disable_conversations: true  // Prevents loading the conversations module
})

This is different from hiding the widget – it completely disables the feature.

Recover tickets across browsers

Support tickets are tied to the browser session by default. If a user switches browsers or clears their storage, they won't see their previous tickets. The widget includes a Recover your tickets link to handle this.

How recovery works

1. Click Recover your tickets in the ticket list
2. Enter the email address used in previous conversations
3. A recovery link is sent to that email (expires in one hour)
4. Click the link to open the widget and restore tickets in the new browser

If the page URL contains a ph_conv_restore query parameter (from clicking the recovery link), tickets are automatically restored on page load. The parameter is removed from the URL after processing.

Identity verification

If your app has logged-in users, identity verification works better than email-based recovery. You sign the user's distinct ID on your server, and tickets persist across browsers and devices automatically – no user action required.

How it works

1. Your server computes an HMAC-SHA256 hash of the user's distinct_id using your team's secret_api_token
2. You pass this hash along with the distinct_id to the widget
3. The widget API verifies the signature and uses the distinct_id for ticket lookup instead of the browser session

With identity verification enabled, users see all their tickets on any browser or device.

Server-side implementation

Generate the identity hash on your backend. Never expose your secret_api_token in client-side code.

import hmac
import hashlib

def compute_identity_hash(distinct_id: str, secret_api_token: str) -> str:
    return hmac.new(
        secret_api_token.encode(),
        distinct_id.encode(),
        hashlib.sha256,
    ).hexdigest()

const crypto = require('crypto');

function computeIdentityHash(distinctId, secretApiToken) {
  return crypto
    .createHmac('sha256', secretApiToken)
    .update(distinctId)
    .digest('hex');
}

require 'openssl'

def compute_identity_hash(distinct_id, secret_api_token)
  OpenSSL::HMAC.hexdigest('sha256', secret_api_token, distinct_id)
end

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func ComputeIdentityHash(distinctID, secretAPIToken string) string {
    h := hmac.New(sha256.New, []byte(secretAPIToken))
    h.Write([]byte(distinctID))
    return hex.EncodeToString(h.Sum(nil))
}

function computeIdentityHash(string $distinctId, string $secretApiToken): string {
    return hash_hmac('sha256', $distinctId, $secretApiToken);
}

Passing identity to the widget

Once you've computed the hash on your server, pass it to your frontend and set it on the PostHog SDK.

Option 1: Set identity at initialization

If you know the user's identity when PostHog initializes (like on a server-rendered page), pass it in the init config:

posthog.init('<ph_project_api_key>', {
  api_host: 'https://us.i.posthog.com',
  identity_distinct_id: 'user_123',       // From your auth system
  identity_hash: 'a1b2c3d4e5f6...',       // HMAC hash from your server
})

Option 2: Set identity after login

For single-page apps — or when the user logs in after page load — call setIdentity():

// After user logs in, your server returns the hash
const identityHash = await fetchIdentityHashFromServer(userId)

// Pass it to the SDK
posthog.setIdentity('user_123', identityHash)

Clear identity on logout

When a user logs out, clear their identity so the widget falls back to session-based access:

posthog.clearIdentity()

When to use identity verification

If your team doesn't have a secret_api_token configured, identity verification is ignored and the widget falls back to session-based access control.

Email notifications

Configure your team to receive email alerts when new tickets arrive.

Setting up notifications

1. Go to Settings > Support in PostHog
2. Find the Email notifications section
3. Select team members who should receive alerts

What emails include

• Team name
• Ticket number
• First message preview
• Direct link to the ticket

Recipients must have access to the team to receive notifications.

Browser notifications

Individual team members can enable browser notifications for new ticket activity.

1. Go to Support in PostHog
2. Enable Browser notifications in the notification settings

When enabled, a desktop notification appears when the unread ticket count increases. This works independently of email notifications – you can use one or both.

Public token

The widget uses a public token for authentication. This token is automatically generated and shown in your Support settings. It's safe to expose in client-side code.

If you need to reset the token:

1. Go to Support > Settings
2. Click Regenerate token