Embed the web widget and manage your agent with the voice agent API.

How do you embed the web widget?

Paste the script tag just before the closing </body> tag. It adds a button to the bottom-right corner of the page, and visitors who click it type a topic, allow the microphone and talk to your agent in their browser. The data-helpline attribute holds your public workspace ID, which starts with hl_, and data-channel="sales" loads the sales agent instead of support. The snippet holds no secret keys.

Copy your snippets from the dashboard, or have a coding agent call the get_installation MCP tool. The REST API doesn’t return the snippet. The data-helpline attribute in the snippet comes from an earlier name for the product and is kept so existing embeds keep working.

Calls start only from an allowed origin once customer calls are on. New workspaces start with no origins and calls off, but you can test either agent from the dashboard first. For the full setup order, from approving knowledge to switching on customer calls, follow the guide to adding a voice agent to your website.

• Add each origin exactly, with its scheme, host and any port but no path, such as https://www.example.com. List www and the bare domain separately if your site uses both.
• Use HTTPS. Plain http works only for localhost and 127.0.0.1.
• Each agent takes up to 10 origins, set separately for support and sales.
• Keep it a classic script. The widget reads document.currentScript, so it does nothing in a tag with type="module".
• Both widgets can share a page. They stack in the bottom-right corner, and a duplicate tag for the same agent is ignored.
• The widget has no JavaScript API. Its button label and colour come from each agent’s saved settings, and its position and styling are fixed.
• The call panel loads in an iframe from app.kawlnow.com with microphone access allowed. Audio streams over WebRTC between the visitor’s browser and OpenAI, which processes the conversation. No call audio is recorded, and the transcript is saved as text.
• If your site sets a Content Security Policy, allow https://app.kawlnow.com in script-src, connect-src and frame-src. The widget adds its styles in an inline style element, so a style-src that blocks inline styles leaves the widget unstyled and out of place, and a policy that requires Trusted Types stops the widget appearing.
• If your site sends a Permissions-Policy header, allow the microphone for the widget’s origin as well, as in microphone=(self "https://app.kawlnow.com"). Test on a staging page with your real headers first.

<script
  src="https://app.kawlnow.com/widget.js"
  data-helpline="YOUR_WORKSPACE_ID"
  async>
</script>

<script
  src="https://app.kawlnow.com/widget.js"
  data-helpline="YOUR_WORKSPACE_ID"
  data-channel="sales"
  async
></script>

How do workspace tokens work?

Both APIs take a workspace token in the Authorization header as Bearer YOUR_WORKSPACE_TOKEN. Create one under Developers in the dashboard or with POST /api/manage/keys. It’s shown once, so store it straight away.

• Tokens start with hl_sk_. We keep only a SHA-256 hash and the first 14 characters, which identify the token in your list.
• Each token has full management access to one workspace, including approvals, transcripts and other tokens. There are no read-only or scoped tokens.
• Revoke one under Active tokens or with DELETE /api/manage/keys/{id}, and it stops working straight away.
• Creating or revoking a token, switching customer calls or human handover on or off, or changing allowed origins emails the owner’s sign-in address. Notices are rate-limited, and approvals, new sources and other setting changes don’t send one, so check Active tokens and your settings from time to time.
• Keep tokens in server-side code or trusted tools. The widget never needs one.

curl 'https://app.kawlnow.com/api/manage/workspace' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'

Which REST endpoints does the management API have?

Call https://app.kawlnow.com with your token in the Authorization header and send JSON bodies. There’s no SDK to install, and Kawl Now doesn’t send webhooks, so check GET /api/manage/workspace for new conversations.

POST /api/manage/sources always saves a new source unapproved and ignores any approved value you send. Approve it with a separate call to PATCH /api/manage/sources/{id} with {"approved": true} once a person has read the full text. The voice agent searches only approved sources. GitHub imports and refreshes are always saved unapproved.

Human handover is an early release. Once a UK or US team phone number for an agent has been verified in the dashboard, escalationEnabled in that agent’s settings switches handover on or off, and whoever answers hears a private briefing before the caller is connected. Numbers are verified and changed only in the dashboard, and customer routing is still being tested, so keep your usual contact options on your site.

The OpenAPI 3.1 file at https://app.kawlnow.com/api/openapi describes the Kawl Now Management API, version 0.2.0, and documents all 14 operations below that accept a workspace token.

• GET /api/manage/workspace returns your workspace ID, both agents’ settings, usage, sources, the latest 100 conversations, each marked if it was a dashboard test, and your token list.
• PATCH /api/manage/settings updates the support agent and its widget, changing only the fields you send. An allowedOrigins list replaces the saved one, so include every origin you want to keep.
• PATCH /api/manage/sales-settings does the same for the sales agent.
• POST /api/manage/sources adds a document with a title, content and channel.
• GET /api/manage/sources/{id} returns a source with its full text.
• PATCH /api/manage/sources/{id} approves or unapproves a source with {"approved": true} or {"approved": false}. Read it back with GET to confirm the change.
• DELETE /api/manage/sources/{id} removes a source.
• POST /api/manage/github imports or refreshes one support document from {"repo": "owner/name", "path": "docs/setup.md"}.
• GET /api/manage/conversations/{id} returns a conversation with its transcript.
• GET /api/manage/insights returns the support agent’s automatic insights, or the sales agent’s with ?channel=sales. They group recurring questions, reported issues and themes from what callers said in up to the latest 30 completed customer calls in the last 30 days, with exact quotes. Dashboard tests aren’t included, and until a report is ready, the response’s state field says why, such as empty or queued.
• POST /api/manage/keys creates a token and returns it once.
• DELETE /api/manage/keys/{id} revokes a token, which stops working straight away.
• POST /api/manage/notifications/test queues a test email to the owner’s sign-in address, at most once a minute.
• POST /api/manage/website is switched off and returns 503.

# Add a support document, unapproved, for review.
curl -X POST 'https://app.kawlnow.com/api/manage/sources' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"channel": "support", "title": "Invite a teammate", "content": "Your checked answer goes here."}'

# Response 201: {"id": "SOURCE_ID"}

# Read the full text back so a person can check it.
curl 'https://app.kawlnow.com/api/manage/sources/SOURCE_ID' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN'

# Once it has been checked, approve it.
curl -X PATCH 'https://app.kawlnow.com/api/manage/sources/SOURCE_ID' \
  -H 'Authorization: Bearer YOUR_WORKSPACE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"approved": true}'

# Response 200: {"ok": true}

Which tools does the MCP server provide?

The MCP server is at https://app.kawlnow.com/api/mcp and uses the Streamable HTTP transport. Every JSON-RPC message is its own POST carrying your token, and the server answers each request with a single JSON object rather than an event stream. It supports protocol version 2026-07-28, which has no sessions, and the 2025-11-25 initialize handshake for older clients. Its serverInfo reports the product’s original name and version 0.1.0, which is separate from the REST API’s version.

Use a client that supports authenticated remote MCP over HTTP. The Developers tab generates the config shown here and fills in a token when you create one. Check the format your client expects: Claude Code, for example, needs "type": "http" added to this entry. Pass channel: "sales" to update_agent, add_knowledge, conversation_insights or get_installation for the sales agent. For setup steps, and a way to keep approvals with a person, follow the MCP guide.

• get_workspace reads both agents’ settings, usage, sources, recent conversations and connection status.
• update_agent takes settings and an optional channel. It changes the product name, agent name, greeting, instructions, voice, widget label and colour, allowed origins, customer-calls switch or handover switch straight away. As over REST, an allowedOrigins list replaces the saved one, and handover can be turned on only after that agent’s team phone number is verified in the dashboard.
• add_knowledge takes a title, content and an optional channel, and always saves the document unapproved.
• sync_github takes a repo and a path, and imports or refreshes one GitHub support document unapproved.
• list_knowledge lists sources with their channel and approval status.
• get_knowledge takes a source id and returns its full text for review.
• approve_knowledge takes a source id and approved set to true or false.
• list_conversations lists up to 100 recent conversations with their topic, status, length, test flag, summary and feedback, but not full transcripts.
• conversation_insights takes an optional channel and returns the same automatic insights as GET /api/manage/insights: recurring questions, reported issues and themes from up to the latest 30 completed customer calls in the last 30 days, with exact quotes.
• get_installation takes an optional channel and returns the embed snippet, allowed origins and whether customer calls are on.
• import_website is switched off and returns an error. Add website content as a sales document with add_knowledge instead.

{
  "mcpServers": {
    "kawl-now": {
      "url": "https://app.kawlnow.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WORKSPACE_TOKEN"
      }
    }
  }
}

What limits apply during the pilot?

Each workspace’s first 50 conversations are free, and the allowance doesn’t renew. Support, sales and dashboard tests share it, and a conversation counts when its voice session starts. Paid calls aren’t available yet, so no payment is collected and new calls are refused once all 50 are used.

• Browser calls end at a hard limit of 10 minutes.
• Each workspace allows 3 calls starting or in progress at once, and 12 new calls a minute.
• A workspace can hold 100 knowledge sources of up to 50,000 characters each, with titles up to 140 characters.
• GitHub imports take one .md, .mdx or .txt file per request. Public repositories need no setup. Ask us before relying on a private one.
• Product names can be 80 characters, agent names 60, greetings 500, instructions 4,000 and button labels 30. The voice setting takes marin or cedar.

What happens when a request fails?

REST errors return JSON such as {"error": "Source not found."}, usually with one of the statuses below. Over MCP, a failed tool call returns a normal result with isError set to true and a plain-language message. Protocol errors use JSON-RPC codes, such as -32020 when the MCP headers don’t match the body, and -32001 with HTTP 401 or 403 for a token or Origin problem.

When a call can’t start, visitors see why. An origin that isn’t listed shows “This domain is not allowed to use this support line.” If customer calls are off, they see “This line is not accepting calls yet.” At the call limits, they see “This line is busy. Please try again shortly.” Once all 50 free conversations are used, they’re told the free conversations have been used.

• 400: invalid JSON, or a field that fails validation.
• 401: a missing, malformed or revoked token.
• 403: a settings update that sets humanNumber, since team numbers are verified and changed only in the dashboard; one that turns on escalationEnabled before that agent’s team number is verified; or an MCP request with another website’s Origin header.
• 404: an unknown endpoint, a source or conversation that isn’t in your workspace, or a GitHub file that can’t be found.
• 409: a settings update that collided with another, so send it again, or a test email with no address to go to.
• 413: a request body over 150,000 bytes.
• 429: a second test email within a minute.
• 500: an unexpected server error, so try again.
• 502: GitHub couldn’t return the file.
• 503: website import, or a service that’s unavailable.

Common questions