К основному содержанию
скилл CX Codex

visitor-identification — скилл для Claude Code: установка

Скилл visitor-identification выпускает токены HubSpot Conversations для авторизованных посетителей сайта и связывает сессию чата с карточкой в CRM.

Apache-2.0 348 установок ★ 30 обновлён 2026-10-09

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add HubSpot/agent-cli-skills --skill visitor-identification -a claude-code
Открыть на GitHub

Что делает visitor-identification

Скилл помогает серверу получить подписанный токен идентификации через команду hubspot conversations visitor-identification create-token. Токен связывает сессию веб-чата с контактом в CRM по его адресу электронной почты. Действует такой токен 12 часов, поэтому на бэкенде его можно кэшировать.

Для вызова требуется закрытое приложение с областью видимости conversations.visitor_identification.tokens.create в переменной окружения HUBSPOT_ACCESS_TOKEN. На тарифах Starter и Free API вернёт ошибку 403: интеграция работает исключительно на подписках Professional и Enterprise. Массовая генерация не поддерживается, за один вызов создаётся токен только для одного адреса.

На фронтенде токен передаётся в window.hsConversationsSettings вместе с почтой, после чего вызывается метод window.HubSpotConversations.widget.load(). Генерировать токен прямо в браузере нельзя, иначе секретный ключ приложения окажется в открытом доступе.

Какие задачи решает

  • привязать сессию веб-чата к контакту в CRM HubSpot
  • сгенерировать токен идентификации посетителя на бэкенде
  • настроить права доступа для приватного приложения HubSpot
  • встроить авторизацию пользователя в скрипт виджета чата

Примеры запросов агенту

  • Создай токен идентификации посетителя чата для почты [email protected]
  • Покажи, как передать полученный токен в параметры виджета чата на сайте
  • Объясни, какие права нужны приватному приложению для создания токена посетителя

Как установить visitor-identification

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/visitor-identification/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о visitor-identification

Как установить visitor-identification в Claude Code?

Выполните команду npx skills add HubSpot/agent-cli-skills --skill visitor-identification -a claude-code в терминале.

Зачем нужен скилл visitor-identification?

Он помогает создавать серверные токены для виджета чата HubSpot, чтобы переписка на сайте сразу попадала в карточку нужного клиента в CRM.

Почему API возвращает ошибку 403 при генерации токена?

Такая ошибка возникает, если у приватного приложения нет области видимости conversations.visitor_identification.tokens.create либо если портал HubSpot работает на тарифе Starter или Free.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
hubspot membrane Подключает HubSpot и даёт агенту доступ к контактам, сделкам, тикетам и задачам. Аутентификацию и обновление токенов берёт на себя Membrane CLI. CX Codex +1 858установок lead-triage официальный Anthropic Скилл lead-triage для Claude Code ранжирует входящие лиды HubSpot по вовлечённости, соответствию компании и срочности. Он включается по запросу оценить лиды или выбрать, кому позвонить первым. CX Codex +1 ★ 36 654звёзд репо lead-qualification Cogny AI Скилл lead-qualification для Claude Code проверяет потенциальных клиентов по профилю идеального покупателя: ищет сведения о компании, оценивает соответствие и предлагает следующий шаг. Проверяет одну заявку или список лидов. CX Codex +1 ★ 116звёзд репо customer-language Cogny AI Скилл customer-language собирает реальные фразы клиентов из CRM, чатов поддержки и соцсетей в еженедельный отчёт. Помогает маркетингу говорить на языке аудитории. CX Codex +1 ★ 116звёзд репо waterfall-enrich-contacts tomgranot Скилл waterfall-enrich-contacts достаёт из внешних провайдеров почту, телефон и должность контактов HubSpot и записывает их обратно с журналом изменений. CX Codex +1 ★ 81звёзд репо suppress-hard-bounced tomgranot Скилл suppress-hard-bounced находит недоставляемые контакты в HubSpot через API, выгружает аудит-лог и помогает перевести адреса в non-marketing. CX Codex +1 ★ 81звёзд репо

Из того же набора19

Весь набор →
data-enrichment Скилл data-enrichment сопоставляет CSV или JSONL с контактами и компаниями в HubSpot и обновляет базу через upsert без лишних поисковых запросов. CX Codex +1 1 900установок sales-reporting Скилл sales-reporting собирает сводки по сделкам HubSpot прямо в терминале: что закрывается на этой неделе, пайплайн по стадиям и владельцам, win/loss за период. CX Codex +1 1 900установок deal-management Скилл deal-management ведёт сделки HubSpot из терминала: находит MQL, создаёт сделки со связями, двигает этапы пачкой и закрывает зависшие. CX Codex +1 1 900установок workflow-automation Скилл workflow-automation учит агента управлять автоматизациями HubSpot через агентский CLI hubspot. Помогает создавать, читать, обновлять и удалять сценарии v4 flows API прямо из терминала. CX Codex +1 1 900установок quote-to-cash Скилл quote-to-cash для работы с HubSpot через CLI: создаёт товары, собирает сметы со строками и связями, читает счета и подписки. CX Codex +1 1 800установок conversation-inbox-triage Скилл conversation-inbox-triage разбирает инбоксы HubSpot: находит открытые и неназначенные треды, помечает залежавшиеся разговоры, назначает ответственных и архивирует решённые. CX Codex +1 352установок conversation-history-brief Скилл conversation-history-brief выгружает переписку контакта из всех ящиков HubSpot, сопоставляет каналы и собирает выжимку диалогов для клиентского отчёта. CX Codex +1 351установок work Помогает читать и менять проекты в HubSpot Work. Находит задачи, проверяет статусы и исполнителей, обновляет записи и читает документы проекта. CX Codex +1 158установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой