HelpPuff

Appearance

API reference ​

Every endpoint of the HelpPuff API, one page per area. Each has a curl command and a TypeScript fetch call you can paste, the parameters and body fields, an example response with its type, and the errors. For keys, scopes, conventions and a quickstart, see The API. The same description, as OpenAPI 3.1 (for Postman, Insomnia or a client generator), is at /api/v1/openapi.json on your Worker.

Setup ​

The examples read two environment variables:

bash
export HELPPUFF_URL="https://knowtific-helppuff-<site>.<you>.workers.dev"   # your Worker
export HELPPUFF_API_KEY="hp_live_…"                                         # from Settings → API keys

The TypeScript examples use fetch (Node 18+, Deno, Bun, Workers) and these shared types:

ts
/** A message, as the widget's protocol defines it (see the Protocol page). */
type Message =
  | { id: string; ts: number; role: 'agent' | 'user' | 'system'; type: 'text'; text: string }
  | { id: string; ts: number; role: 'agent'; type: 'options'; text?: string; options: { label: string; value: string }[]; multi?: boolean }
  | { id: string; ts: number; role: 'agent'; type: 'card'; title: string; body?: string; image?: { src: string; alt: string }; actions?: unknown[] }
  | { id: string; ts: number; role: 'agent'; type: 'carousel'; cards: unknown[] }
  | { id: string; ts: number; role: 'agent'; type: 'links'; title?: string; links: { label: string; url: string; description?: string }[] }
  | { id: string; ts: number; role: 'agent'; type: 'form'; title?: string; fields: unknown[]; submitLabel?: string }
  | { id: string; ts: number; role: 'agent' | 'system'; type: 'notice'; text: string; tone?: 'info' | 'warning' | 'error' };

/** Every error has this shape, with the HTTP status. */
type ApiError = {
  error: {
    code: 'bad_request' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'rate_limited' | 'quota_exceeded' | 'connector_error' | 'internal';
    /** Safe to show to a person. */
    message: string;
    /** Seconds to wait, on 429. */
    retryAfter?: number;
  };
};

Errors every endpoint can return ​

Errors are JSON in the ApiError shape above. message is safe to show to a person.

StatusCodeWhen
400bad_requestThe body or a parameter is invalid; message says which.
401unauthorizedNo key, or a key that is unknown, revoked or expired.
403forbiddenThe key lacks this route's scope, belongs to another site, or is used from an address it does not allow.
404not_foundNo such record (or it belongs to another site).
429rate_limitedOver the key's requests a minute. Wait retryAfter seconds (also in Retry-After).

Areas ​

Account ​

Who the key is, and the API description itself.

Chat ​

Talk to the assistant as a visitor, from your own server: start a conversation, send messages (JSON or streamed), close it.

Conversations ​

Read, summarise and delete conversations, from the widget and the API alike.

Live chat ​

A person on the team answers instead of the assistant: reply, take, give, close and hand back a live chat, and see who is available.

Labels and notes ​

Labels a site defines and puts on conversations (the AI can too), and the team's private notes on conversations and contacts.

Leads ​

The people who gave contact details: your CRM's contacts, with custom attributes and site-defined tags. Keyed by email per site.

Jobs ​

Requests, quotes, projects or tickets on the site's pipeline: create them from your own forms and systems, move them through the stages, read their history.

Appointments ​

Booking in the chat (Settings → Bookings: date picker): what is in force, the free times, appointments on jobs (from the chat, the dashboard, your systems or the synced calendar), and the sync. On only with the date picker; the assistant never books.

Integrations ​

Keys for other services (Composio, Cal.com, Calendly), sealed and live at once, and Composio's connected calendar accounts.

Callbacks ​

Visitors who asked to be called back, as tasks.

Knowledge ​

What the assistant knows: the website it learned, uploaded files, hand-written knowledge and business details.

Prompt ​

The business-specific instructions, versioned, and the agent file: the prompt, tools and behaviour settings as one file to export and import.

Tools ​

Your own APIs, called before, during and after a chat ({{name}} in the prompt), and extract tools that save values from the finished conversation. What they return or save is kept on the conversation (data) and sent to webhooks.

Settings ​

The assistant, widget, lead form, limits and IP lists, as one object.

Webhooks ​

Endpoints that receive events as signed JSON, or as a request in their own format; and the email service that sends the team's email notifications.

Analytics ​

Totals, usage and the running version.

Team ​

Who can sign in to the dashboard.

API keys ​

Keys for this API.

Audit ​

What changed, when, and who (or which key) changed it.

MIT licensed. Runs in your own Cloudflare account.

HelpPuff by Knowtific