Skip to main content

Headless Chat & Voice SDK

The Knock Knock widget can run headless — with no Knock Knock UI at all. Your own interface drives AI chat and AI voice calls through a small JavaScript SDK, while Knock Knock handles the AI, sessions, and infrastructure behind the scenes.

This is for developers who want a completely custom look and feel: a chat panel that matches your design system, a voice assistant embedded in your product, or an AI experience that doesn't look like a widget at all.

What the SDK Can Do​

  • Initialize — set up the SDK on your page with KnockKnockSDK.init
  • AI chat — send chat messages from your UI and receive the AI's replies and typing events
  • AI voice calls — start, end, and mute AI voice calls, with live transcripts and audio levels you can render however you like
  • Choose the voice agent per call — start a call with one of your SDK Voice Agents, or pass per-call instructions and a greeting from your page

The old requestCall method for outbound phone calls has been removed from the SDK.

SDK Voice Agents​

SDK Voice Agents let one page offer several AI voice personas — a patient-services agent, a billing agent, a campaign advisor — each with its own greeting, instructions, and voice. Your developer starts a call with one by its key, for example KnockKnockSDK.voice.start({ agent: 'patient-services' }), which makes it easy to build a carousel or a set of "talk to…" buttons.

Manage them under Settings → AI Agents → SDK Voice Agents. Each agent has:

  • Name, Key (what your developer passes to the SDK), and an optional Category
  • AI Engine — AI Model, Agent Language, Agent Voice, speech settings, background sound, and memory. Anything left at Default follows your Widget Voice Agent's AI Engine settings.
  • Greeting — spoken word for word as the opening line; leave it empty to use your company greeting
  • Instructions — the agent's role, persona, and rules, merged into your Call Agent prompt for that call. Your tool, safety, and language rules still apply.
  • Enabled — disabled agents are hidden from the SDK and can't be called

Instructions and voice settings stay on Knock Knock's servers — the page only ever sees each agent's key, name, category, and greeting. Saved changes reach an agent when its next call starts.

SDK Voice Agents are enabled by the Knock Knock team, along with how many you can create — contact support. Until then, voice.start() with no agent still works and uses your Widget Voice Agent, and pages that pass their own instructions and greeting keep working too.

Scope​

The headless SDK covers AI chat and AI voice only. Video calls and human-agent escalation are not available in headless mode — if you need those, use the standard widget instead.

Prerequisites​

  • AI chat and/or AI voice enabled on your account

Developer Documentation​

The widget Install tab's Headless SDK section is your starting point. It includes:

  • Copyable quick-start snippets for chat and voice
  • A shareable Full developer documentation link — a public docs page with the complete API reference and a live demo, personalized with your company id, so your developer can open it without logging in
  • A troubleshooting table covering the most common setup issues, such as the widget not appearing
note

This page is a high-level overview. For method signatures, events, and integration examples, always refer to the SDK docs page linked from the Install tab — it stays in sync with the latest SDK version.

note

For agency white-label accounts, the embed snippet and the developer docs link automatically use your white-label API origin — nothing to configure.