API Reference - knowtific/helppuff GitHub Wiki

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:

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:

/** 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.

Status Code When
400 bad_request The body or a parameter is invalid; message says which.
401 unauthorized No key, or a key that is unknown, revoked or expired.
403 forbidden The key lacks this route's scope, belongs to another site, or is used from an address it does not allow.
404 not_found No such record (or it belongs to another site).
429 rate_limited Over 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.

⚠️ **GitHub.com Fallback** ⚠️