Skip to main content
skill CX Codex

visitor-identification — Claude Code skill: setup and usage

Generates HubSpot Conversations visitor identification tokens by email to connect website chat sessions directly with CRM records.

Apache-2.0 348 installs ★ 30 updated 2026-10-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add HubSpot/agent-cli-skills --skill visitor-identification -a claude-code
Open on GitHub

What visitor-identification does

The skill guides the generation of short-lived signed tokens using hubspot conversations visitor-identification create-token. When an identified contact visits your site, this token links the live chat widget to their HubSpot record. Each token lasts 12 hours, meaning backend services should cache and refresh it on schedule.

Generating tokens requires a HubSpot private app token inside HUBSPOT_ACCESS_TOKEN with the conversations.visitor_identification.tokens.create scope. On Starter or Free tiers the endpoint returns a 403 status, because this feature requires Professional or Enterprise plans. Batch requests are impossible; the command processes a single email per execution.

On the client, the token and corresponding email attach to window.hsConversationsSettings before invoking window.HubSpotConversations.widget.load(). Running token generation directly inside the client browser leaks your secret private app key.

What it helps with

  • associate web chat sessions with HubSpot CRM contacts
  • issue visitor identification tokens on the server
  • verify private app scopes for Conversations API
  • pass signed identification tokens to the frontend chat SDK

Example prompts for the agent

  • Generate a visitor identification token for [email protected] using the CLI
  • Show how to configure the chat widget settings on the frontend with a visitor token
  • Check what scope is required for visitor token generation

How to install visitor-identification

1Skills CLI (Vercel)

npx skills add HubSpot/agent-cli-skills --skill visitor-identification -a claude-code

2Manually: put the files in place

~/.claude/skills/visitor-identification/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/visitor-identification/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about visitor-identification

How to install visitor-identification in Claude Code?

Run npx skills add HubSpot/agent-cli-skills --skill visitor-identification -a claude-code in your terminal.

What does visitor-identification do?

It guides the creation of server-side tokens for the HubSpot Conversations chat widget so live chats attach to existing CRM records.

Why does token generation return a 403 error?

This happens when your private app lacks the conversations.visitor_identification.tokens.create scope or when the account is on a Starter or Free subscription.

Source text

SKILL.md · Apache-2.0
---
name: visitor-identification
description: Generate a HubSpot Conversations visitor identification token for a known website visitor by email, with guidance on required scopes, account tier requirements, and how the frontend must use the token with the HubSpot Conversations SDK.
triggers:
  - "visitor identification"
  - "visitor id token"
  - "visitor token"
  - "identify visitor"
  - "conversations sdk token"
  - "chat widget identification"
  - "identify website visitor"
  - "visitor-identification"
  - "create visitor token"
---

Requires the `conversations` command group from hub-cli PR #251. `hubspot conversations visitor-identification --help` is authoritative.

## What visitor identification is

When a known contact (someone whose email you have) visits your website, the HubSpot Conversations chat widget can identify them — linking the live chat session to their CRM record. To do this, your server generates a short-lived signed token and passes it to the HubSpot Conversations JavaScript SDK. The SDK sends the token to HubSpot, which verifies it and associates the chat session with the contact.

The token is **NOT** a general authentication credential. It identifies one visitor for one chat session and is useless outside the Conversations SDK.

## Requirements

| Requirement | Detail |
|---|---|
| Account tier | Professional or Enterprise |
| Required scope | `conversations.visitor_identification.tokens.create` |
| Token lifetime | 12 hours; cache across page loads and refresh at least every 12 hours |
| Generation side | **Server-side only** — never generate in browser JavaScript; your private app token must remain secret |

## Generate a token

```bash
# Minimal — email only
hubspot conversations visitor-identification create-token \
  --email [email protected]

# With name (populates the contact preview in the widget)
hubspot conversations visitor-identification create-token \
  --email [email protected] \
  --first-name Jane \
  --last-name Doe
```

Output:
```json
{"ok":true,"data":{"token":"eyJhbGciOiJIUzI1NiJ9..."}}
```

If the private app token is missing the required scope the CLI returns a 403 with a scope hint:
```json
{"ok":false,"error":{"status":403,"message":"Missing scope: conversations.visitor_identification.tokens.create"}}
```

## Setting up the private app token

The `conversations.visitor_identification.tokens.create` scope must be granted on the HubSpot private app whose token is in `HUBSPOT_ACCESS_TOKEN`. To add the scope:

1. In HubSpot: **Settings → Integrations → Private Apps → [your app] → Scopes**
2. Under "CRM", enable `conversations.visitor_identification.tokens.create`
3. Rotate the token if required after scope change

## What the frontend must do with the token

After generating the token server-side, set `loadImmediately: false` before the widget loads. Then set the identification properties and load the widget:

```javascript
const { token } = await fetch('/api/hs-visitor-token').then(r => r.json());

window.hsConversationsSettings = {
  loadImmediately: false,
  identificationEmail: '[email protected]',
  identificationToken: token,
};

window.HubSpotConversations.widget.load();
```

Key rules:
- Generate the token server-side for authenticated users; cache it across page loads only if it is refreshed at least every 12 hours.
- Do **not** expose your `HUBSPOT_ACCESS_TOKEN` (private app token) to the frontend.
- `identificationEmail` must match the email used to generate the token.

See HubSpot's public documentation for the full Conversations SDK reference.

## Known constraints

- Requires Professional or Enterprise HubSpot subscription. On Starter or Free the API returns a 403.
- One token per email address per call. Bulk generation is not supported.
- The token payload is opaque — do not attempt to decode or store it beyond passing it to the SDK.

© HubSpot · Apache-2.0 · HubSpot/agent-cli-skills

Similar skills

All skills for Backend and APIs →

From the same set19

The whole set →
data-enrichment data-enrichment matches CSV or JSONL records to HubSpot contacts or companies and updates CRM records in batches without search-before-create loops. CX Codex +1 1,900installs sales-reporting sales-reporting pulls HubSpot deal briefings into the terminal: what closes this week, open pipeline by stage and owner, and win/loss over a period. CX Codex +1 1,900installs deal-management deal-management runs HubSpot deals from the terminal: finds MQLs, creates deals with associations, moves stages in bulk and closes stalled ones. CX Codex +1 1,900installs workflow-automation workflow-automation guides coding agents to manage HubSpot v4 automations via the hubspot agent CLI. Handles JSON inspection, branch flows, safe updates, and deletion. CX Codex +1 1,900installs quote-to-cash quote-to-cash — a skill for driving HubSpot from the CLI: it creates products, assembles quotes with line items and associations, and reads invoices and subscriptions. CX Codex +1 1,800installs conversation-inbox-triage conversation-inbox-triage audits HubSpot conversation inboxes: lists open and unassigned threads, flags stale ones, assigns owners and bulk-archives resolved threads. CX Codex +1 352installs conversation-history-brief conversation-history-brief pulls a CRM contact's thread history across all HubSpot inboxes, maps channel types, and compiles message excerpts into an account brief. CX Codex +1 351installs work This Claude Code skill reads and updates projects in HubSpot Work. It finds tasks, checks their status and owners, edits records, and reads project documents. CX Codex +1 158installs

Project sponsors

Companies that keep this analytics open