API Reference

Chat

Send questions, receive AI answers, submit feedback, and escalate to humans.

POST/api/v1/chatBearer token

Ask a question

Submit a question and receive an AI-generated answer based on your indexed FAQ sources. Supports language selection. Consumes credits from your monthly allowance.

Request Body

questionreq

stringmax 1000 chars

The question to ask.How do I reset my password?

apiKey

string

Your API key. Can also be passed as a Bearer token in the Authorization header.wk_live_abc123

sessionId

string

Session identifier for conversation grouping. Auto-generated if omitted.user_session_42

language

string

ISO language code or "auto". Overrides the dashboard language setting.en

Responses

200Success

answerstringAI-generated answer.

sourcesarraySource titles used to generate the answer.

conversationIdstringID of the stored conversation record.

400Missing or invalid question field.

401Invalid API key.

429Monthly credit limit reached.

500Internal server error.

POST/api/v1/feedbackBearer token

Submit feedback

Record whether the AI answer was helpful. Used by the thumbs-up / thumbs-down buttons in the widget.

Request Body

conversationIdreq

string

The conversation ID returned by /api/v1/chat.conv_abc123

helpfulreq

"yes" | "no"

Whether the answer was helpful.yes

apiKey

string

Your API key. Can also be passed as a Bearer token in the Authorization header.wk_live_abc123

Responses

200Success

successbooleanAlways true on success.

400Missing or invalid fields.

401Invalid API key.

500Internal server error.

POST/api/v1/handoffBearer token

Request human handoff

Escalate a conversation to a human agent. Marks the conversation as handed off and sends an email notification to the site owner.

Request Body

conversationIdreq

string

The conversation ID to escalate.conv_abc123

apiKey

string

Your API key. Can also be passed as a Bearer token in the Authorization header.wk_live_abc123

customerEmail

string

Optional — lets the agent follow up with the customer.user@example.com

Responses

200Success

successbooleanAlways true on success.

400Missing required fields.

401Invalid API key.

500Internal server error.

Sources

Manage FAQ sources programmatically (Scale plan required).

GET/api/v1/sourcesBearer token

List FAQ sources

Returns all FAQ sources associated with your site. Requires Scale plan.

Responses

200Success

sourcesarrayArray of source objects.

401Invalid API key.

403Plan not allowed.

500Internal server error.

POST/api/v1/sourcesBearer token

Add a FAQ source

Creates a new FAQ source with status: pending. Requires Scale plan. Poll GET /api/v1/sources to check when status becomes indexed.

Request Body

urlreq

string

The URL to scrape for FAQ content.https://example.com/help

Responses

200Success

sourceobject

messagestringHuman-readable confirmation.

400Missing url field.

401Invalid API key.

403Plan not allowed.

500Internal server error.

DELETE/api/v1/sourcesBearer token

Delete a FAQ source

Permanently removes a FAQ source by ID. Requires Scale plan.

Parameters

idreq

string

The ID of the source to delete. (in query)src_xyz789

Responses

200Success

deletedbooleanAlways true on success.

400Missing id query parameter.

401Invalid API key.

403Plan not allowed.

404Source not found or belongs to a different site.

500Internal server error.

POST/api/v1/sources/rescrapeBearer token

Re-scrape a FAQ source

Triggers a fresh scrape of an existing FAQ source by ID. The source must be a URL (not a file upload). The scrape runs asynchronously — poll GET /api/v1/sources to check status. Requires Scale plan.

Request Body

sourceIdreq

string

The ID of the FAQ source to re-scrape.src_abc123

apiKey

string

Your API key. Can also be passed as a Bearer token in the Authorization header.wk_live_abc123

Responses

200Success

sourceIdstringThe source ID.

urlstringThe URL being re-scraped.

status"scraping"Always 'scraping' on success.

messagestringHuman-readable status message.

400Missing sourceId or source is a file upload.

401Invalid API key.

403Plan not allowed.

404Source not found or belongs to a different site.

500Internal server error.

Widget

Retrieve widget display configuration (colors, labels, position).

GET/api/v1/configBearer token

Get widget configuration

Returns the full display configuration for a widget — colors, labels, position, bot name, and all customisable text strings.

Parameters

apiKey

string

Your API key (alternative to Authorization header). (in query)wk_live_abc123

Responses

200Success

primaryColorstringHex color for the widget primary accent.

primaryForegroundstringForeground color on primary.

backgroundColorstringWidget background color.

foregroundColorstringWidget text color.

secondaryColorstringSecondary background color.

secondaryForegroundstringSecondary text color.

position"bottom-right" | "bottom-left"Widget position on screen.

greetingstringOpening message shown to users.

botNamestringDisplay name shown in the widget header.

showBrandingbooleanWhether HelpBot branding is shown (Scale plan can hide).

aiLanguagestringLanguage code (e.g. "en", "ar") or "auto".

inputPlaceholderstringPlaceholder text for the input field.

typingTextstringText shown while AI is generating a response.

onlineTextstringStatus indicator text.

handoffTextstringLabel for the human handoff button.

handoffSentTextstringConfirmation message after handoff request.

emailPlaceholderstringPlaceholder for the email input during handoff.

emailSendTextstringLabel for the send email button.

emailSkipTextstringLabel for the skip email button.

feedbackYesTextstringThumbs-up feedback label.

feedbackNoTextstringThumbs-down feedback label.

errorTextstringGeneric error message.

networkErrorTextstringNetwork connectivity error message.

401Invalid API key.

500Internal server error.

PATCH/api/v1/configBearer token

Update widget configuration

Update one or more widget configuration fields. Only send the fields you want to change — omitted fields keep their current values. Setting showBranding to false requires the Scale plan.

Request Body

apiKey

string

Your API key. Can also be passed as a Bearer token in the Authorization header.wk_live_abc123

primaryColor

string

Hex color for the widget primary accent.#4f46e5

primaryForeground

string

Foreground color on primary.#ffffff

backgroundColor

string

Widget background color.#ffffff

foregroundColor

string

Widget text color.#1f2937

secondaryColor

string

Secondary background color.#f3f4f6

secondaryForeground

string

Secondary text color.#1f2937

position

"bottom-right" | "bottom-left"

Widget position on screen.

greeting

string

Opening message shown to users.Hi! How can I help you today?

botName

string

Display name shown in the widget header.HelpBot

showBranding

boolean

Show HelpBot branding. Setting to false requires Scale plan.

aiLanguage

string

Language code (e.g. "en", "ar") or "auto".auto

inputPlaceholder

string

Input placeholder text.

typingText

string

Typing indicator text.

onlineText

string

Status indicator text.

handoffText

string

Handoff button label.

handoffSentText

string

Confirmation after handoff.

emailPlaceholder

string

Email input placeholder.

emailSendText

string

Email send button label.

emailSkipText

string

Email skip button label.

feedbackYesText

string

Positive feedback label.

feedbackNoText

string

Negative feedback label.

errorText

string

Generic error message.

networkErrorText

string

Network error message.

Responses

200Success

updatedarrayList of field names that were updated.

configobjectThe full updated widget configuration.

400No valid fields to update, or invalid field value.

401Invalid API key.

403Removing branding requires Scale plan.

500Internal server error.

Analytics

Usage statistics, daily activity, and unanswered question insights (Growth or Scale plan required).

GET/api/v1/analytics/overviewBearer token

Get analytics overview

Returns summary statistics for your site: total questions, satisfaction rate, handoff count, week-over-week trend, and credit usage. Requires Growth or Scale plan.

Parameters

range

string

Time range filter. Defaults to "30d". (in query)30d

Responses

200Success

rangestringThe applied time range.

totalQuestionsintegerTotal conversations in the range.

satisfactionRateintegerPercentage of feedback marked helpful (0-100).

helpfulCountintegerConversations rated helpful.

totalFeedbackintegerTotal conversations that received feedback.

handoffCountintegerConversations escalated to a human.

handoffRateintegerHandoff percentage of total questions (0-100).

weekOverWeekChangeintegerPercentage change in questions vs the previous week.

creditsobject

401Invalid API key.

403Plan not allowed (requires Growth or Scale).

500Internal server error.

GET/api/v1/analytics/activityBearer token

Get daily activity

Returns daily question counts for chart rendering. Each entry contains a date (YYYY-MM-DD) and the number of questions asked that day. Requires Growth or Scale plan.

Parameters

range

string

Time range filter. Defaults to "30d". (in query)30d

Responses

200Success

rangestringThe applied time range.

activityarrayDaily question counts, sorted ascending by date.

401Invalid API key.

403Plan not allowed (requires Growth or Scale).

500Internal server error.

GET/api/v1/conversationsBearer token

List conversations

Returns a paginated list of conversations with flexible filters. Use `filter=unanswered` to find gaps, `filter=handoff` for escalations, or combine with `search` to find specific topics. Requires Growth or Scale plan.

Parameters

range

string

Time range filter. Defaults to "30d". (in query)30d

limit

integer

Page size (1-100). Defaults to 20. (in query)20

page

integer

Page number. Defaults to 1. (in query)1

filter

string

Pre-built filter. "unanswered" returns conversations rated unhelpful or containing fallback phrases. Defaults to "all". (in query)all

search

string

Search within question text. (in query)

sessionId

string

Filter by session ID. (in query)

sort

string

Sort order. Defaults to "-createdAt" (newest first). (in query)-createdAt

Responses

200Success

conversationsarrayList of conversations.

totalDocsnumberTotal matching conversations.

pagenumberCurrent page number.

totalPagesnumberTotal number of pages.

limitnumberPage size.

401Invalid API key.

403Plan not allowed (requires Growth or Scale).

500Internal server error.

Webhooks

GET/api/v1/webhooksBearer token

List webhooks

Returns all webhooks for your site. Secrets are redacted to last 4 characters. Requires Growth or Scale plan.

Responses

200Success

webhooksarrayArray of webhook objects with redacted secrets.

401Invalid API key.

403Plan not allowed.

500Internal server error.

POST/api/v1/webhooksBearer token

Create a webhook

Registers a new webhook endpoint. The signing secret is returned once — store it securely. Max 5 webhooks per site. Requires Growth or Scale plan.

Request Body

urlreq

string

The callback URL to receive webhook POST requests.https://example.com/webhooks/helpbot

eventsreq

array

Events to subscribe to.conversation.created,conversation.unanswered

description

stringmax 200 chars

Optional description for this webhook.Sync new conversations to Slack

Responses

200Success

webhookobjectThe created webhook, including the secret (shown once).

400Invalid request body.

401Invalid API key.

403Plan not allowed or webhook limit reached.

500Internal server error.

DELETE/api/v1/webhooksBearer token

Delete a webhook

Permanently removes a webhook by ID. Requires Growth or Scale plan.

Parameters

idreq

string

The ID of the webhook to delete. (in query)wh_abc123

Responses

200Success

deletedbooleanAlways true on success.

400Missing id query parameter.

401Invalid API key.

403Plan not allowed.

404Webhook not found or belongs to a different site.

500Internal server error.

Delivery format

Every webhook delivery is an HTTP POST with a JSON body and the following headers:

Content-TypeAlways application/json.

X-HelpBot-SignatureHMAC-SHA256 hex digest prefixed with sha256=.

X-HelpBot-EventThe event type, e.g. conversation.created.

X-HelpBot-DeliveryUnique UUID for this delivery (for idempotency).

Envelope

The JSON body wraps every event in a consistent envelope:

payload.json

{
  "event": "conversation.created",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": { ... }
}

Verifying signatures

verify.ts

import crypto from "node:crypto";

const signature = req.headers["x-helpbot-signature"];
const expected = "sha256=" +
  crypto.createHmac("sha256", WEBHOOK_SECRET)
    .update(rawBody)
    .digest("hex");

if (signature !== expected) {
  return new Response("Invalid signature", { status: 401 });
}

Event payloads

The data field contains event-specific fields described below.

conversation.created

Fired when a visitor asks a question and receives an AI answer.

conversationIdstringUnique ID of the conversation.

sessionIdstringVisitor session identifier.

questionstringThe visitor's question.

answerstringThe AI-generated answer.

sourcesstring[]FAQ source URLs used to generate the answer.

conversation.unanswered

Fired alongside conversation.created when the AI could not find a relevant answer.

conversationIdstringUnique ID of the conversation.

sessionIdstringVisitor session identifier.

questionstringThe visitor's question.

answerstringThe fallback response returned to the visitor.

sourcesstring[]FAQ source URLs checked (may be empty).

conversation.feedback

Fired when a visitor rates an answer as helpful or not helpful.

conversationIdstringUnique ID of the conversation.

helpful"yes" | "no"The visitor's feedback rating.

conversation.handoff

Fired when a conversation is escalated to a human agent.

conversationIdstringUnique ID of the conversation.

questionstringThe visitor's original question.

answerstringThe AI answer given before handoff.

customerEmailstring | nullEmail provided by the visitor, if any.