Widget Endpoints

Public API endpoints used by the embedded widget. Authenticated via site key, not JWT.

Overview

These endpoints are called by the widget JavaScript running on your customer's browser. They use the public site key for authentication instead of a JWT, since the widget operates in an unauthenticated (visitor) context.

The site key is passed via the x-site-key header on every request. This identifies the workspace and allows the backend to resolve the tenant.

Authentication Header

x-site-key: zt_pub_abc123def456

💡Widget endpoints are rate-limited to 60 requests per minute per site key. This is stricter than the general API to prevent abuse from public-facing scripts.

Endpoints

Get Widget Config

GET/widget/config

Fetch the widget configuration for rendering — colors, greeting, position, branding.

Auth: Site key (x-site-key header)

Response 200

{
  "workspaceName": "Acme Inc",
  "greeting": "Hey! How can we help you today?",
  "position": "bottom-right",
  "primaryColor": "#6366f1",
  "showBranding": true,
  "requireEmail": false,
  "offlineMode": "ticket",
  "logo": "https://cdn.zapticket.app/logos/ws_abc123.png"
}

This endpoint is called once when the widget initializes. The response is cached on the client for the duration of the page session.

Get Availability

GET/widget/availability

Check whether any agents are currently online for live chat.

Auth: Site key (x-site-key header)

Response 200

{
  "available": true,
  "onlineAgentCount": 3,
  "estimatedWaitTime": null
}

Response 200 (offline)

{
  "available": false,
  "onlineAgentCount": 0,
  "estimatedWaitTime": null
}

When available is false and the widget is configured with offlineMode: "ticket", the widget shows a "Leave a message" form instead of the live chat interface.

Verify Identity

POST/widget/verify-identity

Verify a signed identity payload for authenticated visitors (HMAC validation).

Auth: Site key (x-site-key header)

Request Body

{
  "userId": "user_12345",
  "email": "[email protected]",
  "name": "Alice Customer",
  "hash": "a1b2c3d4e5f6..."
}

The hash is an HMAC-SHA256 signature of userId using the workspace's HMAC secret key. This ensures the identity hasn't been tampered with.

Response 200

{
  "verified": true,
  "visitorToken": "vis_abc123xyz",
  "identity": {
    "userId": "user_12345",
    "email": "[email protected]",
    "name": "Alice Customer"
  }
}

Response 401 (invalid hash)

{
  "error": "Identity verification failed: invalid signature"
}

🚨The HMAC secret must never be exposed in client-side code. Generate the hash on your server and pass it to the widget initialization on page load.

Create Offline Ticket

POST/widget/offline-ticket

Submit a support request when no agents are online. Creates a ticket in the workspace.

Auth: Site key (x-site-key header)

Request Body

{
  "name": "Alice Customer",
  "email": "[email protected]",
  "subject": "Can't reset my password",
  "message": "I've tried the reset flow 3 times but never receive the email. I've checked spam."
}

Response 201

{
  "ticketId": "tkt_offline123",
  "reference": "ZT-1045",
  "message": "Your message has been received. We'll get back to you at [email protected]."
}

All fields are required. The ticket is created with priority: "medium" and status: "open". Agents see it in their ticket queue when they come online.