Enquiry API
Read visitor enquiries from your own Hazelchat workspace and subscribe a Zap to new enquiries. Delivery requires Business or Scale, visitor details switched on and enquiry capture running.
Use an owner API key
When access is enabled for your workspace, open Settings, Zapier. Give the key a label, create it and copy it immediately. Hazelchat shows it once. Paste it into the Hazelchat connection in Zapier. It has one scope, enquiries:read.
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 Settings to remove all its subscriptions immediately.
Four 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. Zapier deduplicates by id; the initial-enable behavior remains a live platform-check gate.
POST /hooks
Send {"target_url":"https://hooks.zapier.com/hooks/catch/fictional/example/"}. This is a fictional URL: use the target supplied by your Zap. The server accepts only exact HTTPS URLs on hooks.zapier.com, with a path, no credentials, port or fragment, and public DNS addresses.
Returns 201 with {"id":"subscription-id"}. Repeating the same target with the same key returns the existing id. Up to ten subscriptions per workspace. Subscribing sends no historical enquiries.
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. All visitor text is untrusted plain text. Escape it before mapping it into HTML or email templates.
| Field | Value |
|---|---|
id | Stable enquiry id; use it for deduplication. |
created_at | Submission-permission timestamp in ISO 8601 UTC. |
name, email, message | Visitor-provided strings. |
website | Conversation’s website origin, or null if unavailable; no page path. |
last_question | Last saved visitor question, or null. |
answered | answered, unanswered or no-question. A status, not answer text or lead qualification. |
enquiry_url | Server-built link to the enquiry in the owner console; signing in is required. |
No transcript, model output, notice text or other internal ids are included.
Errors and access controls
Errors are JSON: {"error":"Message"}.
| Status | Meaning |
|---|---|
| 400 | Invalid body, limit or target; DNS validation refused the target. |
| 401 | Missing, invalid or revoked owner API key, or a refused credential. |
| 403 | Zapier delivery is part of Business for other plans or paused billing; suspended workspaces are also refused. |
| 404 | Feature off, workspace outside the allowlist, unknown route or missing subscription. |
| 409 | Visitor details off, capture paused or subscription limit reached. The response explains which control to review. |
| 429 | Per-key request limit reached. Wait before trying again. |
Delivery and deletion
New enquiries queue once per active subscription. The worker posts the same JSON item, pins the validated DNS address, follows no redirects and allows eight seconds overall. Only an explicit 429 or 5xx retries, with at most three attempts. A 410 response removes the subscription.
Settings shows the last subscription status; Enquiries shows “Sent to Zapier” after an accepted 2xx response. Acceptance does not prove the connected tool completed its action. A timeout or crash during a send shows an unknown outcome and does not automatically retry.
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) and on to the tools you connect there. Deleting them in Hazelchat cannot remove copies already sent; arrange deletion in those tools separately.