Knock SDK

@knock-ai/sdk 0.1.3 · npm · GitHub

What it is

@knock-ai/sdk is the Knock AI SDK for your logged-in app. Call init() once and it loads your Knock tag. From then on your code tells Knock who people are, records what they do, and opens your Knock scheduling modal.

Installing the Knock SDK lets you build Product workflows and open the Knock scheduling modal from inside your app.

Quick Start

Install with your AI agent

Skill Installer

# 1. Install the skill
npx skills add knock-org/knock-sdk
# 2. Enter your agent and type
/install-knock-sdk product tag ID = {{PRODUCT_ID}} , I want to implement these events {{MARKETING_EVENTS}}

No skills support? Paste this prompt

Product Tag ID: {{PRODUCT_TAG_ID}}
Marketing Events: {{MARKETING_EVENTS}}
Install the Knock SDK in this project by following these instructions:
https://raw.githubusercontent.com/knock-org/knock-sdk/main/skills/install-knock-sdk/SKILL.md

Manual Installation

npm install @knock-ai/sdk

Core Functionality

// Import the SDK
import { knock } from '@knock-ai/sdk';

// 1. Initialize the tag
knock.init({ tagId: 'YOUR_WEBSITE_TAG_ID' });
// 2. Identify a lead
knock.identify({ email, ...optionalFields })
// 3. Track a lead's action
knock.track('trial_started', { plan: 'pro' })
// 4. Open Modal / Scheduling Form
knock.modal.open({ magicLinkId: 'A96s9R' });
knock.scheduling.load({ magicLinkId: 'A96s9R' });
// 5. Open chat links (keeps the visitor's identity)
window.open(knock.wrapLink('https://start-chat.com/slack/acme/sales'));

What it can do

Identify people: knock.identify({ email, firstName, lastName, company }). It takes one object: email is required, company is the company name as a string, and you can add your own fields.
Track events: knock.track('trial_started', { plan: 'pro' }), on either tag.
Open your scheduling modal: knock.modal.open() opens your default modal, and knock.modal.open({ magicLinkId }) a specific one. To load one ahead of time, knock.scheduling.load({ magicLinkId, onStatusChange }) returns a handle you can .open() and reports each status change (slots_found, booked, …).
Control Knock's widget: knock.widget.show(), .hide(), .open(), .close().
Listen: knock.on('modal:close', fn) returns a function that stops listening. Events: ready, modal:open, modal:close, widget:open, widget:close, error.
Keep identity on chat links: knock.wrapLink(url) returns url with the visitor's identity added, for links to Knock chat (start-chat.com). Use it where you open the link yourself, e.g. window.open(knock.wrapLink(url)). Before the Knock tag has loaded, and on the server, it returns url unchanged.
No waiting: calls made before the SDK is ready are queued (up to 1,000) and sent in order.
SSR-safe: on the server every call does nothing, so you don't need typeof window guards.
Works with React 17+, Vue 3+, Angular 17+, plain JS or a CDN snippet. @knock-ai/sdk/testing gives you a mock for tests.

The framework snippets use your product tag id (a logged-in app). On a marketing site, use your website tag id instead, e.g. VITE_KNOCK_WEBSITE_TAG_ID. If your site sends a Content-Security-Policy, add the sources in docs/csp.md.

Frameworks

React (Vite)

import { KnockProvider, useKnock } from '@knock-ai/sdk/react';
import App from './App';

export function Root({ user }: { user: { email: string; firstName?: string } | null }) {
  return (
    <KnockProvider
      tagId={import.meta.env.VITE_KNOCK_PRODUCT_TAG_ID}
      user={user ? { traits: { email: user.email, firstName: user.firstName } } : null}
    >
      <App />
    </KnockProvider>
  );
}

// Anywhere inside the provider
export function ExportButton() {
  const knock = useKnock();
  return <button onClick={() => knock.track('report_exported', { format: 'csv' })}>Export</button>;
}

KnockProvider calls init() once, on mount, and identify() whenever user is set or changes.
<KnockButton>Book a meeting</KnockButton> opens your default modal. Pass magicLinkId to open a specific one, which also starts loading it on hover or focus.
<KnockLink href="https://start-chat.com/slack/acme/sales">Chat with sales</KnockLink> renders a plain <a> with href as is and adds the visitor's identity only while the link is opened (click, middle-click, Enter), so a copied link stays clean.
Hooks: useKnock(), useKnockIdentify(traits), useKnockEvent(event, handler).

Next.js (App Router): @knock-ai/sdk/react is marked 'use client', so KnockProvider can go straight into your root layout, which stays a server component. Call the hooks only from client components.

// app/layout.tsx
import { KnockProvider } from '@knock-ai/sdk/react';

// inside <body>, around {children}:
<KnockProvider tagId={process.env.NEXT_PUBLIC_KNOCK_PRODUCT_TAG_ID!}>{children}</KnockProvider>

Vue

// main.ts
import { createApp } from 'vue';
import { KnockPlugin } from '@knock-ai/sdk/vue';
import App from './App.vue';

createApp(App).use(KnockPlugin, { tagId: import.meta.env.VITE_KNOCK_PRODUCT_TAG_ID }).mount('#app');

<script setup lang="ts">
import { onMounted } from 'vue';
import { useKnock, KnockButton } from '@knock-ai/sdk/vue';

const props = defineProps<{ user: { email: string; firstName?: string } }>();
const knock = useKnock();
onMounted(() => knock.identify({ email: props.user.email, firstName: props.user.firstName }));
</script>

<template>
  <button @click="knock.track('report_exported', { format: 'csv' })">Export</button>
  <KnockButton>Book a meeting</KnockButton>
</template>

Angular

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideKnock } from '@knock-ai/sdk/angular';
import { environment } from '../environments/environment';

export const appConfig: ApplicationConfig = {
  providers: [provideKnock({ tagId: environment.knockProductTagId })],
};

Angular has no public env-var prefix: keep the id in your environment.ts, or paste it in directly.

import { Component, Input, OnInit, inject } from '@angular/core';
import { KNOCK } from '@knock-ai/sdk/angular';

@Component({
  selector: 'app-toolbar',
  standalone: true,
  template: `<button (click)="knock.modal.open()">Book a meeting</button>`,
})
export class ToolbarComponent implements OnInit {
  @Input({ required: true }) user!: { email: string; firstName?: string };
  readonly knock = inject(KNOCK);

  ngOnInit() {
    this.knock.identify({ email: this.user.email, firstName: this.user.firstName });
  }
}

Plain JS (npm)

import { knock } from '@knock-ai/sdk';

knock.init({ tagId: 'YOUR_WEBSITE_TAG_ID' });

document.querySelector('#demo-form')?.addEventListener('submit', (event) => {
  const email = new FormData(event.target).get('email');
  if (email) knock.identify({ email }); // website tag: captures a lead
  knock.track('demo_form_submitted');
});
document.querySelector('#book-demo')?.addEventListener('click', () => knock.modal.open());

CDN (no build step)

<!-- once, in <head> -->
<script src="https://cdn.jsdelivr.net/npm/@knock-ai/sdk@0.1/dist/snippet.js"></script>
<script>knockai.init({ tagId: 'YOUR_WEBSITE_TAG_ID' });</script>

Any script after it can call knock.identify(), knock.track() or knock.modal.open() right away. If your page already uses the name knock, use knockai instead (same object).

Knock SDK
What it is
Quick Start
Install with your AI agent
Skill Installer
No skills support? Paste this prompt
Manual Installation
Core Functionality
What it can do
Frameworks
React (Vite)
Vue
Angular
Plain JS (npm)
CDN (no build step)