Chat Trigger

A Chat Trigger is an ingress node that exposes a visitor-facing chat UI wired into a pipeline. Visitors type, the message goes to the trigger's AI Node, and the assistant response streams back token-by-token over Server-Sent Events. Five ways to ship it: a hosted URL you share as a link, a one-line <script> embed for any site, an npm package for framework apps, the API on its own if you would rather build the interface, and an API key to create triggers from your own backend.

Overview

A Chat Trigger sits at the start of a pipeline, just like a Webhook or Scheduled Workflow. The difference is the front-end: instead of a third-party system POSTing JSON to a URL, a human types into a chat widget and the widget streams the response back.

A Chat Trigger answers through one AI Node — the one connected to it. Only that node receives what the visitor typed, and its answer is what streams back. With one connected, the canvas will not add a second: the + on the trigger and a dragged link both refuse and say why, and the API refuses to save a second connection with a 400. To do more with each message, connect it after the AI Node — what hangs off the AI Node runs with its output, as in any flow.

The same trigger can be surfaced in several places at once — a shared URL for quick testing, a <script> embed on a marketing site, a React component or Web Component inside a product app, or your own interface talking straight to the ingress — all against the same pipeline and the same configuration. The first three run the same packaged widget, so what the widget cannot do, none of them can; the fourth is the one where you control the request.

How it works

Ingress webhook

Every Chat Trigger gets a unique short chatId and two public webhooks:

• GET /api/chat-triggers/public/:chatId — returns visible config (title, theme, initial messages) for the widget to render
• POST /api/chat-triggers/in/:chatId/message — the SSE ingress for one conversation turn

When a visitor sends a message, the widget POSTs to the message webhook with { message, sessionId, fileRefs? }. HostWebhook validates CORS + auth, resolves file attachments, and hands the payload to the trigger's AI Node.

Streaming response

The response is streamed back as Server-Sent Events. Event types:

event: session   data: { "sessionId": "hws_kQ8…", "hwsSessionId": "hws_kQ8…" }
event: tool_start data: { "name": "search_db", "input": { ... } }
event: tool_end   data: { "name": "search_db", "output": "...", "success": true }
event: token     data: { "text": "Hello" }
event: token     data: { "text": ", how" }
event: token     data: { "text": " can I help?" }
event: done      data: { "response": "Hello, how can I help?", "conversationId": "..." }
event: error     data: { "message": "..." }

Token streaming is true streaming when the AI node uses a streaming provider — Anthropic and OpenAI both fire tokens the moment the LLM emits them, not at the end of the run. Tool events fire in real time so the widget can show a “running” indicator while the LLM reasons through a tool call.

The session event carries the same id under two keys — sessionId and hwsSessionId. They are always equal. hwsSessionId is the current name; sessionId is kept so widget bundles already pinned in customer package.json files keep finding the field they read. The same pair holds on the request side: the message body accepts hwsSessionId or sessionId, with the new name winning when both arrive.

Session lifecycle

Each conversation is keyed by a sessionId. Where that id comes from depends on who is signing, and the two cases are not symmetric:

• Public triggers, and signed triggers your own backend signs — the client picks the id. The widget generates one per visitor and persists it in localStorage so returning visitors continue the same conversation, and your signing webhook can hand back a different one to tie the chat to a logged-in user.
• The hosted page (/chat/:chatId) — the server picks the id, not the browser. /hosted-auth is an anonymous endpoint, so any id a caller could name would be an id it could name for someone else. See Hosted URL auto-signs.

Either way, the server uses the resolved id to group messages into a single conversation record and to scope HMAC signatures (see Authentication).

Configuration

Everything here is set from the trigger's page in the dashboard — the Where column says which tab and section, so you are never hunting for a field you read about.

Integration Methods

Pick the method that fits where you're shipping. Every method talks to the same backend and honors the same trigger config — you can use several at once for the same chatId.

1. Hosted URL (shared link)

Every trigger has a ready-to-use hosted page at https://www.hostwebhook.com/chat/:chatId. Copy the link from the Share tab and paste it anywhere — Slack, email, a QR code, a Notion doc. Zero code, zero embed, zero backend work.

Use it for: lightweight deployment, quick demos, internal tools, embedding inside an iframe where full control over the host page isn't worth the integration effort.

2. Script Embed (widget.js)

Drop a single <script> tag into any HTML page. The loader creates a floating chat button (FAB) in the corner and a panel that opens on click. The UI lives in a Shadow DOM — host CSS can't leak in and the widget's styles don't leak out.

<script src="https://www.hostwebhook.com/widget.js"
  data-chat-id="abc123"
  data-position="right"
  data-primary="#7c3aed"
  data-label="Chat with us"
  defer></script>

For signed triggers, add data-auth-endpoint:

<script src="https://www.hostwebhook.com/widget.js"
  data-chat-id="abc123"
  data-auth-endpoint="/api/chat-auth"
  data-primary="#7c3aed"
  defer></script>

Once the loader runs, window.HwChat gives you programmatic control:

window.HwChat.open();            // expand the panel
window.HwChat.close();           // collapse it
window.HwChat.toggle();          // flip state

// Swap in a custom auth provider at runtime (alt. to data-auth-endpoint):
window.HwChat.setAuthProvider(async ({ sessionId }) => {
  const r = await fetch('/my/sig', { method: 'POST', body: JSON.stringify({ sessionId }) });
  return r.json(); // { sig, ts }
});

3. npm package (React or Web Component)

For framework apps (React, Next.js, Vue, Svelte, Astro) that already have a build step. Install the package from npm — every widget update propagates on your next npm install, no dashboard redeploy needed.

npm install @hostwebhook/chat-widget

React / Next.js — use the typed component:

import { HwChat } from '@hostwebhook/chat-widget/react';

<HwChat chatId="abc123" />

import { HwChat } from '@hostwebhook/chat-widget/react';

// authEndpoint is the one to reach for: the widget calls it with your
// cookies and adopts a sessionId you return. See the props table.
<HwChat chatId="abc123" authEndpoint="/api/chat-auth" />

Use authProvider instead only when fetching the signature needs logic a URL can't express — an in-memory token, a different transport. It cannot reassign the session:

<HwChat
  chatId="abc123"
  authProvider={async ({ sessionId }) => {
    const r = await fetch('/api/chat-auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sessionId }),
    });
    if (!r.ok) throw new Error(`Auth webhook ${r.status}`);
    return r.json(); // { sig, ts } — a sessionId here is ignored
  }}
/>

Vue / Svelte / Angular / plain bundled HTML — import once as a side effect and use the Web Component tag:

<script type="module">
  import '@hostwebhook/chat-widget';
</script>
<hw-chat chat-id="abc123"></hw-chat>

Component props:

4. Direct API (your own interface)

No widget at all: you build the request and render the conversation yourself. This is the method for a custom UI, a mobile app, or a backend-to-backend integration — and the only one where sessionIdStrategy can be header or query, because you are the one constructing the call.

GET  /api/chat-triggers/public/:chatId              # config the widget renders from
POST /api/chat-triggers/in/:chatId/message         # one turn, replies as SSE
GET  /api/chat-triggers/in/:chatId/messages?session=…   # earlier conversation

# attachments — on a signed trigger browser-only, see the callout below
POST /api/chat-triggers/in/:chatId/upload-url      # signed: listed Origin + HMAC
POST /api/chat-triggers/in/:chatId/confirm-upload
GET  /api/chat-triggers/in/:chatId/file-status/:fileId?sessionId=…

CORS is already set up for it. The ingress answers with five allowed request headers — Content-Type, Authorization, X-Session-Id, X-Hws-Session-Id and X-Preview-Token — and an empty allowedOrigins advertises any origin back. Note that the OPTIONS preflight is answered by the API's global CORS layer, not by the chat route: the route's header list only rides on the real response. If the trigger is signed, you compute the HMAC yourself — see Signed mode. Full request and response shapes in the API Reference.

5. Management API (create triggers from code)

Not a way to chat — a way to provision. With an API key (hwk_…) you can create and configure chat triggers without opening the dashboard. The case this exists for is multi-tenant: one chatbot per customer of yours, created by your backend, which then drops the returned chatId into whichever of the four methods above that customer gets.

POST   /api/chat-triggers                          # create; returns the chatId
GET    /api/chat-triggers/:id/auth-secret          # the signing secret
POST   /api/chat-triggers/:id/regenerate-secret    # rotate it
GET    /api/chat-triggers/:id/conversations        # read what people asked
POST   /api/chat-triggers/:id/test                 # one real turn through the agent

Plus the usual list, read, update and delete on /api/chat-triggers. Examples in the API Reference.

Authentication

Every Chat Trigger has an authMode. Which mode you pick determines whether anonymous visitors on the public internet can use the chat, and how the three embed surfaces differ.

Public mode

Anyone with the chat URL, embed script, or component can send messages. The ingress accepts requests without a signature. Good for marketing widgets, public demos, open support chats.

The brake that matters here is yours, not ours: rateLimitMessagesPerMinute (default 60, range 1–600) counted in a Redis sliding window, keyed by whatever rateLimitScope says — session (the default) or ip. Over it the ingress answers 429 Too many messages with a Retry-After header. On top of that sits a fixed 20 requests/min/IP throttle on the message route, which is a platform backstop against bots and not the number you tune. Set the per-trigger limit low on a public chat: every message is an LLM call.

Signed mode

Every ingress call must include a short-lived HMAC signature bound to the caller's sessionId. Random internet traffic without a signature gets a 401 Invalid or missing signature. Use signed mode for authenticated embeds (logged-in users, paid tools, anything where you want to gate access at the edge).

The signature is sent as an Authorization header:

Authorization: Bearer <sig>:<ts>

where sig = HMAC-SHA256(secret, `${sessionId}:${ts}`) in hex
      ts  = Unix timestamp in seconds
      TTL = 5 minutes (older timestamps rejected as replay)

Hosted URL auto-signs

When you open https://www.hostwebhook.com/chat/:chatId for a signed trigger, the hosted page calls a special webhook on our backend — POST /api/chat-triggers/in/:chatId/hosted-auth — which signs on behalf of the page using the secret already stored in the trigger. No secret ships to the browser and none is yours to handle — but there is one thing to configure, and the page will not come up without it: allowedOrigins has to be non-empty and has to name https://www.hostwebhook.com, the origin this page calls from. The endpoint is throttled to 20 calls/min/IP.

The way it stays stateless and still survives a token refresh is that the id carries its own proof. It has the shape hws_<random>.<mac>, where the trailing MAC is derived from the trigger's own secret. Present an id back and the server re-signs it only if it recognises that MAC — in other words, only if it issued the id itself. Anything else, including someone else's session, is dropped and a fresh id is minted. You get no error saying which happened, on purpose: an error there would be the oracle all over again.

Two more things the endpoint enforces, both easy to trip over:

• It checks the Origin header and rejects with 403. The origin must be on allowedOrigins. (On a public trigger an empty list means any origin is accepted, but an Origin must at least be present; on a signed one an empty list never gets this far — see the callout below.) A bare curl sends no Origin and is refused. Be clear about what that buys: outside a browser an Origin is one command-line argument away, so this is friction against lazy abuse, not a boundary. The cost boundary is the per-IP limit. The owner testing from the dashboard panel is the one exemption: a valid X-Preview-Token is checked against this trigger and stands in for the origin test, exactly as it stands in for the HMAC on message and upload-url. The shared /chat/… link carries no such token, so for the link the hosted origin has to be on the list for real.
• The widget has to be new enough to adopt what it is given. Bundles older than 0.8.0 ignore the session id in the response and carry on using their own, which no longer validates.

None of this touches the other path, the signing webhook on your own backend (below), which is still what an embed on your own site is meant to use: there the secret is yours and you decide who is who, which is what signed means.

Backend signing webhook

For script embeds and the React component on your own site, you must host a tiny webhook that signs requests with the shared secret. The widget POSTs { sessionId } and expects { sig, ts } in response.

Two things about that call are what make it useful for gating access, and neither is obvious:

• It goes out with credentials: "include", so your own cookies reach your own route. That is where you decide whether this visitor is allowed to chat at all — no session, no signature, no chat.
• You may return a sessionId alongside { sig, ts }. The widget adopts it, persists it to localStorage and uses it from then on. Returning user_42 is how you tie the conversation to a person instead of a browser — without touching the session strategy.

import { NextResponse } from "next/server";
import crypto from "crypto";

export const runtime = "nodejs";

export async function POST(req: Request) {
  const secret = process.env.HW_CHAT_SECRET;
  if (!secret) return NextResponse.json({ error: "secret not configured" }, { status: 500 });

  const { sessionId } = await req.json();
  if (typeof sessionId !== "string" || !sessionId) {
    return NextResponse.json({ error: "sessionId required" }, { status: 400 });
  }

  const ts = Math.floor(Date.now() / 1000);
  const sig = crypto.createHmac("sha256", secret).update(`${sessionId}:${ts}`).digest("hex");

  return NextResponse.json({ sig, ts });
}

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json());

app.post("/api/chat-auth", (req, res) => {
  const secret = process.env.HW_CHAT_SECRET;
  if (!secret) return res.status(500).json({ error: "secret not configured" });

  const sessionId = String(req.body?.sessionId ?? "").trim();
  if (!sessionId) return res.status(400).json({ error: "sessionId required" });

  const ts = Math.floor(Date.now() / 1000);
  const sig = crypto.createHmac("sha256", secret).update(`${sessionId}:${ts}`).digest("hex");

  res.json({ sig, ts });
});

import os, hmac, hashlib, time
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.post("/api/chat-auth")
def chat_auth():
    secret = os.environ.get("HW_CHAT_SECRET")
    if not secret:
        return jsonify({"error": "secret not configured"}), 500

    session_id = (request.get_json() or {}).get("sessionId", "").strip()
    if not session_id:
        return jsonify({"error": "sessionId required"}), 400

    ts = int(time.time())
    mac = hmac.new(secret.encode(), f"{session_id}:{ts}".encode(), hashlib.sha256)
    return jsonify({"sig": mac.hexdigest(), "ts": ts})

<?php
header('Content-Type: application/json');

$secret = getenv('HW_CHAT_SECRET');
if (!$secret) { http_response_code(500); exit(json_encode(['error' => 'secret not configured'])); }

$body = json_decode(file_get_contents('php://input'), true);
$sessionId = trim($body['sessionId'] ?? '');
if (!$sessionId) { http_response_code(400); exit(json_encode(['error' => 'sessionId required'])); }

$ts = time();
$sig = hash_hmac('sha256', "$sessionId:$ts", $secret);
echo json_encode(['sig' => $sig, 'ts' => $ts]);

Which surface needs what

Why a 401 happened

A rejected signature answers 401 with three fields. error is always the same string — Invalid or missing signature — because clients read it verbatim. message is prose for a human squinting at the response. The one to branch on is code:

Session Strategies

The sessionIdStrategy field controls where the server reads the session ID from. HMAC signatures bind to this ID — pick the strategy that matches where your session state lives.

auto (default)

The widget generates a random session ID on first load and persists it in the visitor's localStorage. The server reads whatever comes in the request body. Zero setup — fine for anonymous chat, public widgets, and most signed use cases where you don't have a stronger identity anyway. On the hosted page the id the widget keeps is the one the server minted, not one it invented.

One asymmetry worth knowing: a GET cannot carry a body, so on the history endpoint auto falls back to reading ?hwsSession= or ?session= from the query string. That fallback is for auto and for bodiless requests only — a POST still resolves from the body and nothing else, and an explicit header or query choice always wins.

header

The server reads X-Hws-Session-Id, falling back to X-Session-Id, from the request headers — and nowhere else. Use this when your own client already has an authenticated session (cookie, JWT) and you want the conversation scoped to that identity. Your backend sets the header when calling the ingress, or you wire it through a proxy. CORS allows both names: they are in the global preflight list alongside Content-Type, Authorization and X-Preview-Token.

Nothing in any of those responses names the strategy you just changed — the code field is the whole clue, and half the routes do not even carry one. Before you flip this setting, confirm on the wire that your client sends one of the two headers on the message routes and keeps putting sessionId in the body of the attachment ones.

query

The server reads ?hwsSession=..., falling back to ?session=..., from the query string of the API request — not from the page's own URL. So it is the client calling POST /api/chat-triggers/in/:chatId/message?session=… that decides the id. Useful when you render from something that can't set headers.

Memory and Conversations

What a visitor says is kept in two places that do different jobs: the AI Node's memory, which is what lets the chat remember earlier messages, and the conversation, the transcript you read in the dashboard.

Memory — what makes the chat remember

Each turn, the AI Node gets one message: {{payload.message}}, what the visitor just typed. Earlier messages reach the model only through the node's Memory. With it on, the node recalls the previous exchanges of the same session — keyed by the visitor's session id, so every visitor has a memory of their own with nothing to configure. With it off, every message arrives on its own and the chat does not remember earlier messages: tell it your name, ask for it on the next message, and it will not know.

That is why the AI Node that comes with a Chat Trigger is born with Memory on, using the built-in backend that HostWebhook manages. If you turn it off, or connect an AI Node that has it off, the Chat Trigger's panel warns you that the chat won't remember earlier messages. Backends and their settings are in AI Node › Memory.

Reading and deleting conversations

Every session's transcript is kept as a conversation, one per chat and session id, whether or not the AI Node has Memory on. How long depends on your plan — a number of days after its last message, or until you delete it; the page tells you which. The Chat Trigger's Share & Activity tab shows the recent ones under Visitor sessions; Manage sessions → there takes you to the same chat in Settings → Chat Sessions, which is where you read and delete them.

• The list — every Chat Trigger you can see, with its sessions, messages and last activity. Search by chat name or ID; Manage → opens one chat.
• One chat — its sessions, newest first, 25 to a page: the first thing the visitor wrote, the session id, how many messages, when it started and when the last message came. View opens the whole transcript.
• Deleting — one session (from its row, or from the open transcript), every session idle for more than 7, 30 or 90 days, or all of them. It asks first, and it can't be undone.

The same from code, with an API key — canvas:read to read, canvas:write to delete. See Chat sessions in the API Reference.

Attachments

When attachmentsEnabled is on, the widget shows a paperclip button. Visitors drag or pick files; each file uploads directly to our R2 bucket via a presigned URL (no bytes through the browser's local memory twice).

Attachments work in signed mode too. The widget sends the same Authorization: Bearer <sig>:<ts> on the attachment calls that it sends on /message, so the signature upload-url demands on a signed trigger is already there — on the hosted page, the script embed and the npm package alike. Widget bundles up to 0.10.0 did not send it, and on a signed trigger their uploads fail with 401 signature_missing.

Allowed file types

The whitelist is deliberately narrow — only formats the AI + File Transform nodes can actually consume:

• Images: image/jpeg, image/png, image/webp, image/gif
• Documents: application/pdf, text/csv, text/plain

Max 5 attachments per message. Per-file size cap depends on your plan (Free 10 MB, Starter 25 MB, Pro 50 MB, Enterprise 500 MB). Rejected uploads fail visibly in the widget so visitors know why.

Upload flow

The widget does three round-trips per file:

1. POST /api/chat-triggers/in/:chatId/upload-url — widget sends { fileName, mimeType, sessionId, size } (plus the signature, on a signed trigger), we return a short-lived R2 presigned PUT URL + a file ID.
2. PUT <presigned URL> — browser uploads bytes directly to R2. We never see the bytes.
3. POST /api/chat-triggers/in/:chatId/confirm-upload — widget sends { fileId, sessionId }. Flips the file status to scanning and enqueues the scan worker. The widget then polls /file-status/:fileId?sessionId=… every few hundred ms until status is clean — only then is the Send button enabled.

Every attachment call carries the sessionId that uploaded the file, and the API refuses any that names a different one. A chat ID is shared by every visitor of the widget, so on its own it says which chat a file belongs to — not whose it is. Binding to the session is what keeps one visitor from reading, or deleting, another visitor's upload. Widget 0.7.0 and up sends it; older builds can no longer confirm attachments.

In the downstream pipeline, each attachment arrives as a _file reference on the payload — the AI node can read it via vision, or the File Transform node can extract text/CSV. After the conversation turn finishes, files are auto-deleted from R2; a 24h GC cron catches anything that slips through.

Usage Caps

Separate from the per-minute rate limit, a trigger can carry six persistent caps: three metrics — messages, LLM tokens, LLM spend — each in a per-visitor daily version and a whole-trigger monthly one. They live in counter documents rather than a rolling window, so they survive restarts and reset on a UTC boundary. Leave one null and it does not apply.

A cap is checked twice per turn. First against what has already been spent, before anything downstream runs. Then again once the AI node is known, with an estimate of this turn reserved up front: its input, and the node's maximum output. The estimate is deliberately pessimistic, and input and output are priced separately because their rates typically run about 1:5.

A turn that does not fit is shortened, not refused. When what is left of a token or spend cap does not cover that maximum output, the turn still runs, with the AI Node's output limited to what is left — for that turn only; the node's own setting does not change. For a spend cap, what is left is turned into tokens at the model's price. Only when what is left cannot pay for even a small minimum of output is the turn refused. So a visitor sitting at 999/1000 still cannot fire off one 50,000-token turn, and a small per-visitor cap does not refuse the very first message of a session just because the node's maximum output — 8,192 tokens when its Max Tokens field is left empty — is bigger than the cap. A shortened answer streams and ends with done like any other; it may just stop where the budget ran out.

Spend caps, and where they stop working

The two spend caps are counted in whole micro-dollars (1e-6 USD), and the unit is in the field name because a bare 50000 in a document does not say whether it is five cents or fifty thousand dollars. Integers rather than floating-point dollars, for three reasons that all bite in practice: the counter is incremented with Mongo $inc, and a double accumulates rounding error across thousands of turns while an integer does not; cents are too coarse, since a cheap model's turn costs about $0.0002, which in cents is 0 — a cap against a counter that always adds zero never fires; and the pricing helper already rounds to six decimals, so micro-dollars is the unit it was working in anyway. The dashboard converts from dollars for you, once.

A related wrinkle even when everything is priced: the reservation uses the model stored on the node, while the charge recorded afterwards uses the model actually called. Both are the credential's model — the node always takes it from its credential — so they match; they are still answers to two different questions, “what could this cost” and “what did it cost”. And a node with tools makes several LLM calls in one turn while the reservation covers one, so the exposure is bounded to a turn's extra iterations rather than to an arbitrarily large turn.

Cap alerts

With capAlertsEnabled on and capAlertEmail filled in, crossing 75%, 90% or 100% of a cap emails you once per threshold per period. The 75 and 90 are amber warnings with what is left and when it runs out at today's rate; the 100 is the red one, which no longer warns of anything but reports a cut-off. It also fires when a turn is rejected for not fitting under the cap — the case where the counter would otherwise sit still forever and never cross anything.

What the visitor reads

Both gates show the visitor the same sentence, but they deliver it very differently, because by the time the second one fires the response has already started.

• The first gate answers 429. Nothing has been sent yet, so it is a plain JSON body: reason, limit and current for machines, and the human-readable text in both error and message — the same string in both, so there is no better version hiding in the field you did not check.
• The reservation gate, when it does refuse, cannot answer anything. It runs inside the turn, after the ingress has already flushed 200 text/event-stream and emitted the session frame. The status line is spent. So the rejection arrives as an SSE error frame — { "message": "…" }, carrying that same sentence — and the stream then ends with no done frame. There is no 429 to check and no reason, limit or current anywhere in it; those numbers go to the server log only.

That text never includes current or limit. A stranger has no use for “900 of 1000”, and with spend caps it would be telling them what the owner spends on their chat. By default they get a generic line that names when access returns — the absolute UTC time and the relative “in 6 hours” together, since each covers the other's gap — or, when the reset time is not known, a plain try-again-later that does not promise a tomorrow nobody can vouch for.

Set capMessageEnabled and write your own in capMessage to replace it. Note what the field is and is not:

• Plain text, one sentence. Max 500 characters. Runs of whitespace, newlines included, collapse to a single space — the widget shows this in an error box where line breaks do not render anyway.
• Links are defused on save. [label](https://…) keeps the label and loses the target, and a bare URL loses its scheme so it reads fine but stops being clickable. The widget renders this string through its markdown path, and a chat owner should not be able to put a clickable link to somebody else's domain on a stranger's screen.
• Empty with the switch on is not an error. The settings page saves as you type, so the field passes through "" every time you clear it. At runtime that reads as “not configured” and the generic text comes back.

Plan Limits

There's no limit on how many Chat Triggers a plan can have. Each one has two kinds of limits: per-request (rate limiting, always enforced) and monthly (plan-capped). The per-IP throttles below are platform backstops that apply to every trigger and are not configurable — they sit underneath the per-trigger rateLimitMessagesPerMinute, which is the one you set, and underneath the usage caps, which are the ones that bound cost.

API Reference

Get public config

curl https://api.hostwebhook.com/api/chat-triggers/public/abc123

Returns only the fields visible to the widget (no secrets, no connected nodes). The response shape:

{
  "chatId": "abc123",
  "title": "Chat with us",
  "subtitle": "We reply in seconds",
  "placeholder": "Type your message…",
  "initialMessages": [{ "role": "assistant", "content": "Hi!" }],
  "theme": { "primaryColor": "#7c3aed", "mode": "dark" },
  "authMode": "public",
  "sessionIdStrategy": "auto",
  "attachments": { "enabled": false, "maxFileSize": 10000000, "maxPerMessage": 5, "allowedMimeTypes": [...] }
}

Send a message (SSE)

curl -N -X POST https://api.hostwebhook.com/api/chat-triggers/in/abc123/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <sig>:<ts>" \
  -d '{ "message": "Hello", "sessionId": "sess_abc" }'

Response is text/event-stream. See Streaming response for the event types.

Hosted auto-sign

# First call of a session: send no id and let the server mint one.
curl -X POST https://api.hostwebhook.com/api/chat-triggers/in/abc123/hosted-auth \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.hostwebhook.com" \
  -d '{}'

# => {
#      "sig": "…",
#      "ts": 1712345678,
#      "hwsSessionId": "hws_….…",   # the minted id — copy it verbatim
#      "sessionId":    "hws_….…"    # same value, older key
#    }

# Refreshing the token five minutes later: hand back the id you were given,
# or the conversation splits in two.
curl -X POST https://api.hostwebhook.com/api/chat-triggers/in/abc123/hosted-auth \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.hostwebhook.com" \
  -d "{\"hwsSessionId\": \"$HWS_SESSION_ID\"}"

Two things the shape above is telling you. First, the session comes back under both hwsSessionId and sessionId — the same value twice, the older key kept for widget bundles already in the wild. Second, the id you sent is a request, not an instruction: it is kept only if the server minted it, and otherwise a fresh one is returned with no explanation of which happened. Always use the id from the response.

The Origin header above is not decoration. Without one the endpoint answers 403, and it must be on allowedOrigins — which on a signed trigger is never empty, because an empty one is refused first. Beyond that: 400 if the trigger is public and needs no signature, and 404 for an unknown or paused chat. What the route does not check is whether you are the hosted page: there is no test for the /chat/… URL, only for the origin you claim. The origins on the list are exactly who can mint a signature — with one exemption, a valid X-Preview-Token, which stands in for the origin test here just as it does on upload-url. It does not stand in for the list being configured. See Hosted URL auto-signs.

Trigger CRUD (authenticated)

curl -X POST https://api.hostwebhook.com/api/chat-triggers \
  -H "Authorization: Bearer hwk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<your-workspace-id>",
    "name": "Product support",
    "title": "How can we help?",
    "subtitle": "Usually replies in minutes",
    "placeholder": "Type your question…",
    "authMode": "signed",
    "allowedOrigins": ["https://your-site.com", "https://www.hostwebhook.com"],
    "attachmentsEnabled": true,
    "theme": { "primaryColor": "#0f3beb", "mode": "dark" }
  }'

allowedOrigins is not optional in that body: authMode: "signed" with an empty or absent list is a 400, carrying the same { error, code, message } shape and the same allowed_origins_required code as the 403 from hosted-auth, so a client can branch on it identically at either door. The same check runs on PATCH, against the state the patch would produce — the dashboard saves one field at a time, so “switch to signed” and “clear the origins” arrive as separate requests and each looks innocent alone. It runs only when the body touches authMode or allowedOrigins: patching the title of a trigger already in that state is not blocked, because blocking it would take away the place you fix it from.

curl https://api.hostwebhook.com/api/chat-triggers/:id/auth-secret \
  -H "Authorization: Bearer hwk_..."

A GET, and the reveal is audited. Note that :id here is the trigger's internal id, not the public chatId from the widget — everything under /api/chat-triggers/:id is keyed that way, while the public ingress under /in/:chatId is keyed by the short public id. Every trigger document this API serialises has the secret replaced with ***masked***, so it never rides along on a list, a read or an update. Two routes return the raw value: this one and POST :id/regenerate-secret just below, which answers with the freshly generated secret. Both build that response by hand instead of from the document, which is why the mask does not apply. Both require the canvas:write scope, both are audited, and both refuse with 403 on a trigger that is not in signed mode.

curl -X POST https://api.hostwebhook.com/api/chat-triggers/:id/regenerate-secret \
  -H "Authorization: Bearer hwk_..."

Chat sessions (authenticated)

What Settings → Chat Sessions does, as routes. Reading needs canvas:read; deleting needs canvas:write and is audited.

GET    /api/chat-sessions                                # every chat you can see, with counts
GET    /api/chat-sessions/:id?limit=25&offset=0          # one chat's sessions, newest first (limit up to 100)
GET    /api/chat-sessions/:id/:conversationId            # one session's full transcript
DELETE /api/chat-sessions/:id/:conversationId            # delete one session
DELETE /api/chat-sessions/:id?olderThanDays=30           # delete sessions idle for more than 30 days
DELETE /api/chat-sessions/:id                            # delete every session of the chat

:id is the trigger's internal id, as everywhere under /api/chat-triggers/:id. :conversationId is the conversation's own id from the session list — not the visitor's sessionId, which comes alongside it. olderThanDays must be a whole number, 1 or more, or the call is a 400. An id that is not one of your organization's chats is a 404, so the answer does not confirm that it exists; a chat of yours in a workspace you have not been given access to is a 403.

curl -X DELETE https://api.hostwebhook.com/api/chat-sessions/:id/:conversationId \
  -H "Authorization: Bearer hwk_..."

# => {
#      "id": "…", "name": "Product support",
#      "deletedConversations": 1,
#      "deletedMemoryRecords": 6,
#      "memoryNotCleared": []
#    }

Both deletes answer with the same shape: how many conversations and memory records went, and in memoryNotCleared each AI Node whose memory could not be cleared, as { aiNodeId, reason }. An empty array means the memory went too. Run history and AI Node traces are not touched — see what deleting removes.