Set up the widget

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

Enable the widget

1. Go to Support in PostHog and click Settings
2. Click Enable support
3. Go to the In-app widget section and enable it
4. Configure your settings
5. Click 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.

Configuration options

Configure these settings 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. PostHog uses this information to link the ticket to a person.

Customize widget behavior

Control where the widget loads and how it appears.

Restrict domains

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.

Show and hide the widget

show() adds the widget, including the launcher button. hide() removes it from the page. show() does nothing until the widget bundle has loaded. These methods are part of the JavaScript API.

// Add the widget, including the launcher button
posthog.conversations.show();

// Remove the widget from the page
posthog.conversations.hide();

// Check if the widget is on the page
const isVisible = posthog.conversations.isVisible();

Use this to show the widget only on certain pages, or to hide it during a flow such as checkout. To open the chat from a button in your own UI, use open().

Open and close the chat panel

open() and close() control the chat panel. The launcher stays on the page. open() renders the widget first when it is not already there.

// Open the chat panel. Renders the widget first if it is not on the page.
posthog.conversations.open();

// Close the panel. The launcher stays.
posthog.conversations.close();

If you call open() or close() before the widget bundle has loaded, the last call runs once the bundle loads. A hide() call cancels an open() that is still waiting. open() does nothing on a domain that is not in Allowed domains. These methods need posthog-js 1.442.0 or later.

Theme the widget

Button color in Support settings sets the primary color. To match the rest of your site, including dark mode, fonts, corner radius, and shadows, pass a theme when you initialize PostHog, or call setTheme() later.

Theming needs posthog-js 1.444.0 or later.

posthog.init("<ph_project_token>", {
  api_host: "https://us.i.posthog.com",
  conversations: {
    theme: {
      colorScheme: "auto", // "light" (default), "dark", or "auto"
      primary: "#111827",
      borderRadius: "16px",
      launcherShadow: "none",
      dark: { primary: "#f9fafb" },
    },
  },
});

colorScheme picks the palette:

• light is the default.
• dark uses the built-in dark colors.
• auto follows the visitor's prefers-color-scheme.

The top-level colors apply to the light scheme only. dark holds the colors used when the dark scheme is active, so set background, text, and the other colors there for dark mode. A color you leave unset in dark falls back to the built-in dark color. primary and primaryText are the exception: they keep the light values until you set them under dark.

// Switch the widget to dark mode after init
posthog.conversations.setTheme({ colorScheme: "dark" });

setTheme() merges the object you pass over the current theme. The dark object merges the same way, so a later call can change one dark color without clearing the others. It is safe to call before the widget loads, and posthog.reset() keeps the theme.

You can set the same values in your own stylesheet. The widget reads them as CSS custom properties on #ph-conversations-widget-container. A rule that selects #ph-conversations-widget-container overrides the theme from the SDK.

html.dark #ph-conversations-widget-container {
  --ph-conv-bg: #0b0f19;
  --ph-conv-text: #e5e7eb;
}

Values apply in this order: built-in defaults, the Button color from Support settings, the theme in posthog.init(), setTheme(), then your CSS.

Color options take any CSS color. fontFamily, borderRadius, launcherShadow, and windowShadow take the CSS value for that property. The widget ignores a value that contains {, }, ;, <, or >, and logs a warning.

Disable the widget

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.

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 and 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 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 Identity verification secret from Support settings
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.

Find your identity verification secret

1. Go to Support > Settings
2. Open the Identity verification secret section. If it is empty, click the button next to it to generate a secret
3. Copy the key. Use it only on your server

The secret lives at Support > Settings.

If you sign the hash with a key that does not work, the widget API answers 403 Forbidden and gives no detail about the cause. The response is the same for a wrong key, a bad signature, and a project with no key, so that the API tells anonymous callers nothing about your setup. If GET /widget/tickets or POST /widget/message answers 403, check your key first. See troubleshooting.

When you rotate the key, PostHog keeps the previous key verifying for 48 hours. Update your server-side code within that window. After 48 hours, the previous key expires on its own. No manual deletion is needed. If the previous key may be compromised, click Expire now in the settings banner to stop it verifying immediately.

Server-side implementation

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

import hmac
import hashlib

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

const crypto = require("crypto");

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

require 'openssl'

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

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

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

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

Pass 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, such as on a server-rendered page, pass it in the init config:

posthog.init("<ph_project_token>", {
  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 project has no identity verification secret, requests that carry identity fields get 403 Forbidden. Generate one in Support settings. Requests without identity fields keep using the browser session.

Notifications

Get notified when new tickets arrive, by email or in your browser.

Email notifications

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

1. Go to Support > Settings in PostHog
2. Open the Notifications tab and find Email notifications
3. Select team members who should receive alerts

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