Skip to content

docs(support): Document identity verification badges for tickets #18156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
inkeep wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs(support): Document identity verification badges for tickets #18156

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
25294a2
Add identity_verified property to ticket properties table
inkeep[bot] Jul 3, 2026
ab2d2d8
docs(support): add verification status badges section to widget docs
inkeep[bot] Jul 3, 2026
823a838
Add verified identity badge note to Slack tickets docs
inkeep[bot] Jul 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions contents/docs/support/inbox.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,16 +14,17 @@ Go to **Support** in the main PostHog navigation to access your inbox.

Each ticket has the following properties:

| Property | Description |
| --------------------- | ------------------------------------------------------------------- |
| **Ticket number** | Auto-incremented unique number (e.g., #1, #2, #3) |
| **Status** | `new`, `open`, `pending`, `on_hold`, `resolved` |
| **Priority** | `low`, `medium`, `high` (optional) |
| **Channel** | Where the ticket came from: `widget`, `slack`, `email`, or `github` |
| **Assignee** | User or role responsible for the ticket |
| **Session ID** | The PostHog session for events and exceptions |
| **Session Replay ID** | The session recording (if replay is enabled) |
| **Distinct ID** | PostHog distinct_id for person linking |
| Property | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Ticket number** | Auto-incremented unique number (e.g., #1, #2, #3) |
| **Status** | `new`, `open`, `pending`, `on_hold`, `resolved` |
| **Priority** | `low`, `medium`, `high` (optional) |
| **Channel** | Where the ticket came from: `widget`, `slack`, `email`, or `github` |
| **Assignee** | User or role responsible for the ticket |
| **Session ID** | The PostHog session for events and exceptions |
| **Session Replay ID** | The session recording (if replay is enabled) |
| **Distinct ID** | PostHog distinct_id for person linking |
| **Identity verified** | Whether the person's identity was verified: `Verified`, `Unverified`, or `Unknown`. See [identity verification](/docs/support/widget#identity-verification). |

## Status workflow

Expand Down
11 changes: 6 additions & 5 deletions contents/docs/support/slack.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,11 +29,11 @@ Each PostHog project can connect to one Slack workspace. If the workspace is alr

After connecting, configure the integration in **Support > Settings**:

| Setting | Description | Default |
|---------|-------------|---------|
| **Support channel** | Every top-level message in this channel becomes a ticket. Thread replies sync as ticket messages. | – |
| **Ticket emoji** | React with this emoji on any message in any channel to create a ticket from it. | `:ticket:` |
| **Bot mentions** | Always active – `@SupportHog` in any channel creates a ticket from that message. | – |
| Setting | Description | Default |
| ------------------- | ------------------------------------------------------------------------------------------------- | ---------- |
| **Support channel** | Every top-level message in this channel becomes a ticket. Thread replies sync as ticket messages. | – |
| **Ticket emoji** | React with this emoji on any message in any channel to create a ticket from it. | `:ticket:` |
| **Bot mentions** | Always active – `@SupportHog` in any channel creates a ticket from that message. | – |

### Picking a support channel

Expand Down Expand Up @@ -86,6 +86,7 @@ Slack-sourced tickets appear in your [inbox](/docs/support/inbox) alongside widg
- A Slack icon indicating the channel source
- A link to the original Slack thread in the ticket sidebar
- The Slack user's name and avatar on messages
- A **Verified** identity badge, since Slack authentication is trusted

You can filter the ticket list by channel source to see only Slack tickets.

Expand Down
92 changes: 51 additions & 41 deletions contents/docs/support/widget.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,24 +20,24 @@ The widget appears as a floating button on your site. By default it appears in t

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

| Setting | Description | Options | Default |
|---------|-------------|---------|--------|
| **Enable widget** | Show the chat widget on your site | `true`, `false` | `false` |
| **Button color** | Primary color for the widget (hex) | Any hex color | `#5375ff` |
| **Widget position** | Position of the widget on screen | `bottom_right`, `bottom_left`, `top_right`, `top_left` | `bottom_right` |
| **Greeting message** | Welcome text shown when widget opens | Any string | `"Hi! How can we help?"` |
| **Allowed domains** | Restrict which domains can show the widget | Array of domain strings | `[]` (all domains) |
| Setting | Description | Options | Default |
| -------------------- | ------------------------------------------ | ------------------------------------------------------ | ------------------------ |
| **Enable widget** | Show the chat widget on your site | `true`, `false` | `false` |
| **Button color** | Primary color for the widget (hex) | Any hex color | `#5375ff` |
| **Widget position** | Position of the widget on screen | `bottom_right`, `bottom_left`, `top_right`, `top_left` | `bottom_right` |
| **Greeting message** | Welcome text shown when widget opens | Any string | `"Hi! How can we help?"` |
| **Allowed domains** | Restrict which domains can show the widget | Array of domain strings | `[]` (all domains) |

## Identification form

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

| Setting | Description | Default |
|---------|-------------|---------|
| **Require email** | Users must enter their email to start chatting | `false` |
| **Collect name** | Additionally collect a name | `false` |
| **Form title** | Heading shown on the identification form | `"Before we start..."` |
| **Form description** | Subtext shown below the title | `"Please provide your details so we can help you better."` |
| Setting | Description | Default |
| -------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| **Require email** | Users must enter their email to start chatting | `false` |
| **Collect name** | Additionally collect a name | `false` |
| **Form title** | Heading shown on the identification form | `"Before we start..."` |
| **Form description** | Subtext shown below the title | `"Please provide your details so we can help you better."` |

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.

Expand All @@ -48,10 +48,10 @@ You can restrict which domains the widget appears on for security:
```javascript
// 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)
]
"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.
Expand All @@ -62,16 +62,17 @@ Use the JavaScript API to programmatically show or hide the widget:

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

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

// Check if widget is currently visible
const isVisible = posthog.conversations.isVisible()
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
Expand All @@ -81,9 +82,9 @@ This is useful for:
You can disable conversations entirely via the PostHog init config:

```javascript
posthog.init('<ph_project_token>', {
disable_conversations: true // Prevents loading the conversations module
})
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.
Expand Down Expand Up @@ -143,13 +144,10 @@ def compute_identity_hash(distinct_id: str, secret_api_token: str) -> str:
```

```node
const crypto = require('crypto');
const crypto = require("crypto");

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

Expand Down Expand Up @@ -192,11 +190,11 @@ Once you've computed the hash on your server, pass it to your frontend and set i
If you know the user's identity when PostHog initializes (like on a server-rendered page), pass it in the init config:

```javascript
posthog.init('<ph_project_api_key>', {
api_host: '<ph_client_api_host>',
identity_distinct_id: 'user_123', // From your auth system
identity_hash: 'a1b2c3d4e5f6...', // HMAC hash from your server
})
posthog.init("<ph_project_api_key>", {
api_host: "<ph_client_api_host>",
identity_distinct_id: "user_123", // From your auth system
identity_hash: "a1b2c3d4e5f6...", // HMAC hash from your server
});
```

**Option 2: Set identity after login**
Expand All @@ -205,18 +203,18 @@ For single-page apps — or when the user logs in after page load — call `setI

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

// Pass it to the SDK
posthog.setIdentity('user_123', identityHash)
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:

```javascript
posthog.clearIdentity()
posthog.clearIdentity();
```

<CalloutBox icon="IconWarning" title="Keep your secret API token secure" type="caution">
Expand All @@ -227,14 +225,26 @@ Your `secret_api_token` must never be exposed in client-side code. Always comput

### When to use identity verification

| Scenario | Recommended approach |
|----------|---------------------|
| **Logged-in users** | Use identity verification for seamless cross-device access |
| **Anonymous visitors** | Use the default widget session (no setup required) |
| **Mixed audience** | Use identity verification when users are logged in, fall back to widget session for anonymous users |
| Scenario | Recommended approach |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| **Logged-in users** | Use identity verification for seamless cross-device access |
| **Anonymous visitors** | Use the default widget session (no setup required) |
| **Mixed audience** | Use identity verification when users are logged in, fall back to widget session for anonymous users |

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.

### Verification status badges

When identity verification is configured, tickets display a verification badge indicating whether the person's identity was confirmed:

| Badge | Meaning |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Verified** (green shield) | PostHog confirmed this person controls the identity on the ticket. This applies to HMAC-signed widget requests, authenticated emails, and validated Slack, Teams, or GitHub events. |
| **Unverified** (amber shield) | The ticket was raised anonymously without identity verification. The claimed identity may not belong to this person. Confirm their identity before sharing sensitive account details. |
| **Unknown** (gray shield) | PostHog never assessed this identity. This applies to tickets created before identity verification existed, or outbound tickets where the recipient hasn't replied. Treat these like unverified tickets. |

The verification badge appears in the ticket list and ticket detail views. Hover over the badge for more details.

## Email notifications

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