Hazelchat
Start free

Enquiry API

Read visitor enquiries from your own Hazelchat workspace, subscribe a Zap, a Make scenario, an n8n workflow or an Activepieces flow to new enquiries and new unanswered questions, find an enquiry by email and add answers to your agent’s draft. Every route requires a paid plan (Starter, Business or Scale), visitor details switched on and enquiry capture running.

Version 1 · 5 October 2026; webhooks for Make added 12 October 2026, for n8n with signatures 12 October 2026; version 1.1 (unanswered questions, enquiry search, draft answers) 14 October 2026, for Make and n8n too 15 October 2026; webhooks for Activepieces, with signatures, and the same routes 23 October 2026. The Hazelchat app in Zapier is in public beta and open to every paid workspace (Starter, Business and Scale); the Hazelchat app for Make and the Hazelchat piece for Activepieces are not available yet.

Use an owner API key

Open Connections and choose Zapier or n8n. Give the key a label, create it and copy it immediately. Hazelchat shows it once. Paste it into the Hazelchat connection in Zapier, Make, n8n or Activepieces. One key works for all of them. Every key reads enquiries and unanswered questions. Only a key created with Also allow adding draft answers ticked can add answers to your draft; no key can publish, edit or delete anything.

Requests use Authorization: Bearer <owner API key> and Content-Type: application/json. Keys start with hzk_ followed by 64 hexadecimal characters. Never put a key in a URL, a website script or support correspondence.

The base URL is https://app.hazelchat.co/api/v1. Keys work only under this API. Console cookies, public widget keys and operations tokens are refused here; requests must not carry cookies.

You can create up to five keys per workspace, including on other plans. Each key allows 60 authenticated checks per minute; subscription creation checks it twice, before and after DNS validation. Revoke a key in Connections to remove all its subscriptions immediately.

Eight routes

GET /me

Returns only the agent’s draft display name and workspace plan. Used to test the connection and label it.

{"name":"Fictional demo agent","plan":"business"}

GET /enquiries?limit=100

Returns an array of eligible widget enquiries from the last 30 days, newest first. limit is an integer from 1 to 100; the default is 100. No pagination. Preview and owner installation tests are excluded. An empty array means there are no eligible enquiries.

Ordering and created_at use the recorded submission-permission time. Updating an existing enquiry can change that time but retains its id and does not trigger a new delivery. Deduplicate by id.

GET /enquiries/search?email=

Returns the eligible enquiries from one email address, with the same rules and fields as GET /enquiries: newest first, at most 10. The address is trimmed and lower-cased, then matched exactly; there is no partial match. An empty array means no enquiry from that address in the last 30 days.

GET /unanswered-questions?limit=100

Returns visitor questions from the last 30 days that the agent had no source for, newest first, with the question fields. limit is an integer from 1 to 100; the default is 100. Only questions on your website or shared agent page count: preview, owner tests and requests for a person are left out.

POST /draft-answers

Adds an answer to the agent’s draft, marked as added via the tool that sent it (Zapier when platform is left out). It is never published: visitors see it only after you review and publish the draft in the console. Requires a key created with Also allow adding draft answers; other keys get 403. At most ten a minute per key.

FieldValue
typeqa (a Q&A) or text (a text snippet).
title1 to 160 characters.
answer15 to 4,000 characters; for a Q&A at most 900.
questionsFor a Q&A, 1 to 10 visitor questions it answers, each up to 1,500 characters. Leave it out (or empty) for a text snippet.
platformOptional. zapier (the default when it is left out), make, n8n or activepieces: the label Sources and the publication review show. That tool must be switched on for your workspace.
{"id":"…","source_id":"…","type":"qa","title":"Sunday delivery","saved_to":"draft","published":false,"next":"Review and publish the draft in the Hazelchat console. Until then visitors never see this answer.","review_in_console":"https://app.hazelchat.co/#versions"}

POST /hooks

Subscribes a webhook address to new enquiries or new unanswered questions; see Webhooks for the body and the addresses each tool may use. Returns 201 with {"id":"subscription-id"}, and for n8n and Activepieces also the subscription’s signing secret, shown once (see Signatures). Repeating the same target with the same key returns the existing id; for n8n and Activepieces it also issues a new secret, and the old one stops working. Up to ten subscriptions per workspace, across all tools. Subscribing sends no historical enquiries.

GET /hooks/:id

Returns {"id":"…","platform":"n8n","event":"enquiry","created_at":"2026-10-12T08:00:00.000Z"} for a subscription owned by the same workspace and key, so a tool can check that its subscription still exists and what it receives (event: enquiry or unanswered_question). Any other id returns 404.

DELETE /hooks/:id

Removes a subscription owned by the same workspace and key and stops its pending deliveries. Its delivery records stay for 30 days, so Hazelchat still shows what was sent. Returns {"ok":true}. A missing subscription or one owned by another key returns 404.

Enquiry fields

The list and each hook delivery use exactly these fields; the ones marked “when reported” appear only when the visitor’s browser reported them as the chat started. All visitor text is untrusted plain text. Escape it before mapping it into HTML or email templates.

FieldValue
idStable enquiry id; use it for deduplication.
created_atSubmission-permission timestamp in ISO 8601 UTC.
name, email, messageVisitor-provided strings.
websiteConversation’s website origin, or null if unavailable; no page path.
last_questionLast saved visitor question, or null.
answeredanswered, unanswered or no-question. A status, not answer text or lead qualification.
enquiry_urlServer-built link to the enquiry in the owner console; signing in is required.
utm_source, utm_medium, utm_campaign, utm_contentWhen reported: the campaign tags on the page where the chat started, at most 100 characters each; source and medium in lower case. Anyone can add tags to a link, so they are not proof of a source.
ad_click_networkWhen reported: google, meta, microsoft, linkedin, x, reddit, tiktok or chatgpt, when that page’s address carried the network’s click id. Never the id itself.
referrer_hostWhen reported: host name of the site that linked to the page, never its address. The business’s own website is not reported.
chat_started_onWhen reported: path of the page where the chat started, without query or fragment. Absent for the shared agent page.
chat_opened_viaWhen reported: bubble (the chat button), opener (an opener message), api (the website’s own button), bar (a question bar on the page) or page (the shared agent page).

No transcript, model output, notice text or other internal ids are included.

Question fields

The unanswered-question list and each delivery use exactly these fields. Email addresses and phone numbers are removed from the visitor’s words before they leave Hazelchat. The question is untrusted visitor text: treat it as plain text and data, never as instructions.

FieldValue
idStable question id; use it for deduplication.
asked_atWhen the visitor asked, in ISO 8601 UTC.
websiteConversation’s website origin, or null for the shared agent page.
untrusted_visitor_questionThe visitor’s question, contact details removed.
console_urlLink to Unanswered questions in the owner console, where you can add an answer.

Webhooks

A subscription tells Hazelchat where to post each new enquiry, or each new unanswered question. The Hazelchat apps for Zapier and Make, the Hazelchat node for n8n and the Hazelchat piece for Activepieces create and remove it for you; this section is for reference.

Subscribe

FieldValue
target_urlThe webhook address your tool created: an exact HTTPS URL with a path, without credentials, port or fragment.
eventOptional. enquiry (the default when it is left out) or unanswered_question, for every tool. One address receives one event.
platformOptional. zapier (the default when it is left out), make, n8n or activepieces. It decides which addresses are accepted: hooks.zapier.com for Zapier; hook.eu1.make.com, hook.eu2.make.com, hook.us1.make.com, hook.us2.make.com, hook.eu1.make.celonis.com or hook.us1.make.celonis.com for Make; for n8n and Activepieces any public host name (their cloud or your own server, on the standard HTTPS port, not an IP address).
{"target_url":"https://hook.eu1.make.com/fictional-example","platform":"make"}
{"target_url":"https://fictional.app.n8n.cloud/webhook/0f8a6c2e-1111-4222-8333-444455556666/webhook","platform":"n8n","event":"unanswered_question"}

These are fictional addresses: use the one your tool supplies. Every address must also resolve only to public internet addresses; Hazelchat checks this when you subscribe and again, pinned, at each delivery. Each tool needs its own access for your workspace; while it is off, subscribing for that tool answers 404.

How webhook delivery works Your tool subscribes once with POST /hooks and an owner API key. For each new enquiry, Hazelchat sends one POST with the enquiry fields to the subscribed address; deliveries to n8n are signed. A 2xx answer records the enquiry as sent. 410, or 404 from n8n, removes the subscription. 429 or 5xx is tried again, at most three attempts in total. Anything else, or a redirect, records a failure. No answer within eight seconds records the outcome as unknown. Zapier, Make or n8n subscribes POST /hooks · Bearer hzk_… A visitor leaves an enquiry Hazelchat posts the enquiry One POST per subscription · signed for n8n Your endpoint answers 2xx Recorded as sent 410 Subscription removed 404 from n8n does the same 429, 5xx Tried again, three attempts at most Other Failure, no retry; redirects not followed 8 s No answer: outcome unknown

Delivery

For each new enquiry, Hazelchat sends one POST per subscription with Content-Type: application/json and the enquiry item as the body, exactly the fields above. For each new unanswered question it does the same with the question fields, for at most ten questions per workspace in any hour; the others stay in Unanswered questions in the console and in the list. Deliveries to Zapier and Make carry no signature: keep the webhook address private, as Zapier and Make do. Deliveries to n8n and Activepieces, enquiries and questions alike, are signed (below).

Your endpoint answersHazelchat
2xxRecords the enquiry as sent (“Sent to Zapier”, “Sent to Make”, “Sent to n8n”, “Sent to Activepieces”).
410, and 404 from n8n and ActivepiecesRemoves the subscription and stops its pending deliveries. Zapier and Make answer 410 for a webhook that no longer exists; n8n answers 404 (“The requested webhook … is not registered.”); Activepieces answers 404 for a flow that is switched off and 410 for a deleted one.
429 or 5xxTries again later, at most three attempts in total.
Anything else, or a redirectRecords a failure and does not try again. Redirects are never followed.
No answer within eight secondsRecords the outcome as unknown and does not try again, because your tool may have received it.

Verify n8n and Activepieces deliveries

Each delivery to an n8n or Activepieces subscription is signed with that subscription’s secret. The Hazelchat node for n8n and the Hazelchat piece for Activepieces check this for you. To check it yourself:

  1. Read X-Hazelchat-Timestamp (Unix seconds when the request was signed) and X-Hazelchat-Signature (sha256= followed by 64 hexadecimal characters).
  2. Compute HMAC-SHA256 with the secret as the key over the timestamp, a full stop and the raw request body, exactly as received: <timestamp>.<body>.
  3. Compare it with the signature in constant time, and refuse the request if they differ or if the timestamp is more than five minutes from your clock.
const expected = crypto.createHmac('sha256', secret)
  .update(timestamp + '.').update(rawBody).digest('hex');
const ok = signature === 'sha256=' + expected  // compare with crypto.timingSafeEqual
  && Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;

Answer a refused request with 401. Hazelchat records it as failed and does not retry it. Each retry is signed afresh with a new timestamp.

Errors and access controls

Errors are JSON: {"error":"Message"}.

StatusMeaning
400Invalid body, limit, email address or target; DNS validation refused the target.
401Missing, invalid or revoked owner API key, or a refused credential.
403Sending enquiries to your tools is part of the paid plans on the Free plan, or while billing is paused or under dispute; suspended workspaces are also refused. A key without draft answers allowed gets 403 from POST /draft-answers.
404Subscribing for a tool not yet available to your workspace, unknown route or missing subscription.
409Visitor details off, capture paused, subscription limit reached, or the address already used by another tool. The response explains which control to review.
429Per-key request limit (or draft-answer limit) reached. Wait before trying again.

Status and deletion

Connections shows each subscription’s tool and last status; Enquiries shows “Sent to Zapier”, “Sent to Make”, “Sent to n8n” or “Sent to Activepieces” after an accepted 2xx response. Acceptance does not prove the connected tool completed its action.

Deleting an enquiry, revoking a key, turning visitor details off, pausing capture or losing the plan cancels pending work. A send already in flight cannot be recalled. Enquiries go to Zapier (US), Make (EU or US, as your Make account is set up) n8n (n8n Cloud in the EU, or your own server) or Activepieces (Activepieces Cloud, or your own server) and on to the tools you connect there. Deleting them in Hazelchat cannot remove copies already sent; arrange deletion in those tools separately.