사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/hubspot/agent-cli-skills --skill visitor-identification시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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
# Minimal — email only
hubspot conversations visitor-identification create-token \
--email visitor@example.com
# With name (populates the contact preview in the widget)
hubspot conversations visitor-identification create-token \
--email visitor@example.com \
--first-name Jane \
--last-name DoeOutput:
{"ok":true,"data":{"token":"eyJhbGciOiJIUzI1NiJ9..."}}If the private app token is missing the required scope the CLI returns a 403 with a scope hint:
{"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:
- In HubSpot: Settings → Integrations → Private Apps → [your app] → Scopes
- Under "CRM", enable
conversations.visitor_identification.tokens.create - 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:
const { token } = await fetch('/api/hs-visitor-token').then(r => r.json());
window.hsConversationsSettings = {
loadImmediately: false,
identificationEmail: 'visitor@example.com',
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. identificationEmailmust 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.
