IllumiChat - AI-Powered Chat Platform

The Widget API powers the embeddable IllumiChat widget. These endpoints are public-facing and use a different authentication model than the standard API, relying on assistant ID validation and domain allowlists instead of bearer tokens.

Authentication Model

Widget endpoints do not use bearer token authentication. Instead, they rely on a three-layer security model:

Assistant ID — Each request includes the assistant ID, which must have widgetEnabled: true.
Domain allowlist — The Origin or Referer header is validated against the assistant’s configured allowed domains.
Session token — After initialization, a session token is returned and must be included in subsequent requests.

Authorization: Widget <session_token>

Widget sessions can be anonymous (no user identity) or authenticated (linked to a known contact via email or external ID). Anonymous sessions are converted to authenticated sessions when a lead form is submitted.

CORS and Domain Restrictions

Widget endpoints include appropriate CORS headers to allow cross-origin requests from approved domains.

Header	Value
`Access-Control-Allow-Origin`	The requesting origin, if it matches the allowlist.
`Access-Control-Allow-Methods`	`GET, POST, OPTIONS`
`Access-Control-Allow-Headers`	`Content-Type, Authorization`
`Access-Control-Max-Age`	`86400`

Requests from domains not in the assistant’s allowlist receive a 403 Forbidden response. During development, add localhost to the allowlist in the assistant’s widget settings.

Creates a new widget session or resumes an existing one. This must be the first call made by the widget.

curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/init" \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "sessionId": null,
    "metadata": {
      "page": "/pricing",
      "referrer": "https://google.com"
    }
  }'

Parameter	Type	Required	Description
`sessionId`	string	No	Previous session ID to resume. Pass `null` to create a new session.
`metadata`	object	No	Page context: `page`, `referrer`, `userAgent`. Used for analytics.

Response 200 OK

{
  "data": {
    "sessionId": "wsess_aaa111",
    "sessionToken": "wt_eyJhbGciOiJIUzI1NiJ9...",
    "config": {
      "assistantName": "Support Bot",
      "welcomeMessage": "Hello! How can I help you today?",
      "primaryColor": "#6366F1",
      "position": "bottom-right",
      "leadFormEnabled": true,
      "leadFormFields": ["name", "email", "phone"]
    },
    "messages": []
  }
}

Store the sessionId in localStorage to resume sessions across page navigations.

Send Message (Streaming)

Sends a visitor message and streams the assistant’s response via SSE. The streaming format is identical to the standard Chat API SSE events.

curl -N -X POST "https://app.illumichat.com/api/widget/ast_abc123/chat" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "content": "What are your pricing plans?",
    "sessionId": "wsess_aaa111"
  }'

Parameter	Type	Required	Description
`content`	string	Yes	The visitor’s message text.
`sessionId`	string	Yes	The active session ID from initialization.

Get Session History

Retrieves the full message history for a widget session.

curl -X GET "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/messages" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Origin: https://www.acme.com"

Response 200 OK

{
  "data": [
    {
      "id": "msg_aaa111",
      "role": "assistant",
      "content": "Hello! How can I help you today?",
      "createdAt": "2025-09-15T10:00:00Z"
    },
    {
      "id": "msg_bbb222",
      "role": "user",
      "content": "What are your pricing plans?",
      "createdAt": "2025-09-15T10:00:15Z"
    }
  ]
}

Submit Lead Form

Captures visitor contact information. Converts an anonymous session into an authenticated session linked to a contact record.

curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/lead" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15559876543",
    "customFields": { "company": "Example Inc." }
  }'

Parameter	Type	Required	Description
`name`	string	No	Visitor’s name.
`email`	string	Conditional	Email address. Required if configured in lead form settings.
`phone`	string	No	Phone number.
`customFields`	object	No	Additional key-value pairs defined in the lead form configuration.

Response 201 Created

Lead form submissions trigger the contact.created webhook event if webhooks are configured for the workspace.

Submit Feedback

Allows visitors to rate a conversation or a specific assistant response.

curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/feedback" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -H "Origin: https://www.acme.com" \
  -d '{
    "messageId": "msg_ccc333",
    "rating": "positive",
    "comment": "Very helpful answer!"
  }'

Parameter	Type	Required	Description
`messageId`	string	No	Specific message to rate. If omitted, feedback applies to the session overall.
`rating`	string	Yes	One of `positive` or `negative`.
`comment`	string	No	Optional free-text feedback from the visitor.

Response 201 Created

End Session

Explicitly ends a widget session. The session can no longer accept new messages after this call.

curl -X POST "https://app.illumichat.com/api/widget/ast_abc123/sessions/wsess_aaa111/end" \
  -H "Authorization: Widget wt_eyJhbGciOiJIUzI1NiJ9..." \
  -H "Origin: https://www.acme.com"

Response 200 OK

{
  "data": {
    "sessionId": "wsess_aaa111",
    "status": "ended",
    "messageCount": 6,
    "duration": 342,
    "endedAt": "2025-09-15T10:05:42Z"
  }
}

Sessions also end automatically after a configurable period of inactivity (default 30 minutes). Explicitly ending a session triggers the conversation.ended webhook event immediately.

Getting Started

Endpoints

Widget

Authentication Model

CORS and Domain Restrictions

Initialize Widget Session

Send Message (Streaming)

Get Session History

Submit Lead Form

Submit Feedback

End Session

​Authentication Model

​CORS and Domain Restrictions

​Initialize Widget Session

​Send Message (Streaming)

​Get Session History

​Submit Lead Form

​Submit Feedback

​End Session

Authentication Model

CORS and Domain Restrictions

Initialize Widget Session

Send Message (Streaming)

Get Session History

Submit Lead Form

Submit Feedback

End Session