API Reference

REST API for the HelpStack dashboard, widget, and webhooks.

Quick facts#

Expect a 404 on /api itself, and 401 on authenticated endpoints. There is no route at the bare https://helpstack.eu/api — it returns 404 by design, because the API is a set of sub-paths (/api/conversations, /api/channels, …), not a browsable root. Opening a real endpoint like /api/conversations in a browser returns 401 (no session cookie), which confirms it exists and is auth-protected. Neither response is a bug.

Authentication model — read this first#

There is currently no public API-key or bearer-token system for third-party callers. Do not look for an "API key" — none exists. The dashboard/internal API is authenticated with the NextAuth session cookie of a logged-in user, and every request is automatically scoped to that user's organization by middleware (withOrganization / withAdmin / withAgent). These endpoints are consumed by the HelpStack dashboard UI.

To call dashboard endpoints from outside the browser you must replay an authenticated session cookie. If you need machine-to-machine access, the supported public surfaces are:

• Widget endpoints — public, IP/visitor rate-limited (see Widget Embed).
• Webhook endpoints — public, verified by token + HMAC signature (see Webhooks).

Treat anything requiring a session cookie as "verify against your deployment" for programmatic use.

Response envelope#

All API routes return a standard envelope.

Success

{ "success": true, "data": { } }

Error

{
  "success": false,
  "error": {
    "message": "Human-readable message",
    "code": "OPTIONAL_CODE",
    "fields": { "fieldName": ["error 1"] }
  }
}

code and fields are optional. fields is populated for validation errors (Zod) with per-field messages.

Error codes & HTTP status#

Errors are produced by typed error classes and a central handler. High-level mapping:

Zod validation failures return 400 with code: "VALIDATION_ERROR" and a fields object. Unexpected errors return 500 with a generic message ("An unexpected error occurred"); the real detail is logged server-side only.

Endpoint catalog#

Roles: an endpoint marked ADMIN requires admin (withAdmin), AGENT requires agent-or-higher (withAgent), Session requires any authenticated org member (withOrganization).

Channels

Create channel — POST /api/channels (verified body, createChannelSchema):

{
  "type": "WEBSITE_CHAT",
  "name": "Website Chat",
  "region": "eu",
  "defaultLanguage": "en",
  "autoTranslate": true,
  "translateToLanguage": "en",
  "fallbackLanguage": "sl",
  "aiProviderId": "PROVIDER_ID",
  "credentials": {},
  "responseTemplate": {},
  "autoReply": false,
  "autoApprove": false,
  "autoEnhance": false
}

Channel-type credential shapes (credentials) are validated separately — e.g. Email requires { host, port, username, password, from, secure?, imapHost?, imapPort?, imapSecure?, imapAllowSelfSigned? }; Facebook requires { pageId, accessToken, appSecret? }; Instagram requires { accountId, accessToken }. Credentials are stored encrypted (AES-256-GCM).

Conversations

status filter values: OPEN | PENDING | CLOSED | ARCHIVED. pageSize is capped at 100 (default 20).

Send message — POST /api/conversations/[id]/messages (verified body, sendMessageSchema):

{
  "conversationId": "CONVERSATION_ID",
  "content": "Thanks for reaching out — here's how to fix that.",
  "attachments": ["storage/path/file.png"]
}

Behavior: the message is created OUTBOUND. If the channel has autoTranslate on and a customer language is known, the message is created unapproved and translated in the background (the agent approves before it is sent). Sending consumes plan tokens; if the org is out of tokens the route returns 402 with code: "INSUFFICIENT_TOKENS". Success returns the created message with HTTP 201.

Messages

FAQs

Media

Notifications

AI providers

Agent tools

See Custom Agent Tools for the full tool anatomy.

Widget (public)

See Widget Embed for payloads.

Webhooks (public)

See Webhooks for handshake and signature details.

Related#

• Widget Embed
• Webhooks
• Email Channel
• Custom Agent Tools
• Channels guide
• Glossary