IllumiChat - AI-Powered Chat Platform

Assistants are the core conversational entities in IllumiChat. Each assistant has its own system prompt and its own knowledge base for retrieval-augmented generation (RAG). All assistants use the same AI model.

These endpoints require a signed-in browser session, not an API key. There is currently no API-key accessible Assistants API — a workspace API key (Authorization: Bearer ...) is only accepted on the /api/v1/* endpoints (contacts, messages, tickets). See API Overview for the two surfaces.

Assistant Configuration

Field	Type	Default	Description
`name`	string	—	Display name shown to users.
`instructions`	string	`""`	System prompt that defines the assistant’s behavior and persona.
`visibility`	string	`"workspace"`	Access level: `private` or `workspace`. (`public` is accepted for backward compatibility but is legacy — use `workspace`.)
`temperature`	number	`0.7`	Sampling temperature between `0` and `2`. Lower values produce more focused responses.
`maxTokens`	integer	`4096`	Maximum number of tokens in the assistant’s response.
`welcomeMessage`	string	`null`	Initial message displayed when a conversation starts.

Visibility Levels

visibility governs access to the assistant in the internal Chat workspace only — it has no effect on the embeddable widget. Widget access is controlled by the widget’s own isEnabled flag (part of the assistant’s widget configuration, not the assistant object — see the Widget endpoints), independent of visibility.

Visibility	Who Can Access
`workspace`	Active members of the workspace.
`private`	Only the creator, workspace admins, and users with explicit access grants.
`public` (legacy)	Accepted for backward compatibility (legacy link-share access). Do not use for new assistants — use `workspace`.

List Assistants

Returns assistants accessible to the authenticated user within a workspace. workspaceId is required.

curl -X GET "https://app.illumichat.com/api/assistants?workspaceId=ws_abc123&limit=10" \
  -H "Cookie: <your-session-cookie>"

Response 200 OK

{
  "data": [
    {
      "id": "ast_abc123",
      "name": "Support Bot",
      "model": "auto",
      "visibility": "workspace",
      "createdAt": "2025-07-01T09:00:00Z"
    }
  ],
  "total": 5,
  "limit": 10,
  "offset": 0
}

Create Assistant

Creates a new assistant in the workspace. Requires owner or admin role.

curl -X POST "https://app.illumichat.com/api/assistants" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "instructions": "You are a helpful customer support assistant for Acme Corp.",
    "visibility": "workspace",
    "temperature": 0.5,
    "maxTokens": 2048,
    "welcomeMessage": "Hello! How can I help you today?"
  }'

Response 201 Created with the full assistant object.

Get Assistant

Retrieves a single assistant by ID.

curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>"

Response 200 OK with the full assistant object including instructions, temperature, maxTokens, visibility, welcomeMessage, and timestamps.

Update Assistant

Updates an assistant’s configuration. Requires owner or admin role. All fields are optional; only provided fields are updated.

curl -X PATCH "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a technical support specialist. Always ask clarifying questions.",
    "temperature": 0.3
  }'

Response 200 OK with the updated assistant object.

Delete Assistant

Permanently deletes an assistant and all its conversations. Requires owner or admin role.

curl -X DELETE "https://app.illumichat.com/api/assistants/ast_abc123" \
  -H "Cookie: <your-session-cookie>"

Response 204 No Content

Deleting an assistant permanently removes all associated conversations, widget sessions, and SMS configurations. This action cannot be undone.

Knowledge (RAG)

Each assistant owns its own knowledge base, and it is managed in the app rather than over the public API — there is no endpoint for connecting a separate document collection. When a customer sends a message, the assistant searches its own static sources for relevant context and includes it in the prompt.

Static sources (files, websites, text, Q&A) are chunked, embedded, and stored in a vector database (Pinecone) under a namespace dedicated to that assistant’s knowledge base. Realtime sources (Shopify, WooCommerce, spreadsheets) are read live at question time and are never indexed. See Knowledge Base.

SMS Configuration

Assistants can be configured to send and receive SMS messages via Twilio. Each assistant has its own Twilio credentials using a bring-your-own-key (BYOK) model.

Get SMS Config

Requires admin role or above.

curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>"

Response 200 OK

{
  "data": {
    "isEnabled": true,
    "twilioPhoneNumber": "+15551234567",
    "twilioAccountSid": "AC...",
    "webhookUrl": "https://app.illumichat.com/api/sms/webhook/ast_abc123",
    "maxMessageLength": 1600,
    "createdAt": "2025-08-15T10:00:00Z"
  }
}

Create or Update SMS Config

Use POST to create the configuration and PATCH to update an existing one. On PATCH every field is optional; only the fields you send are changed.

curl -X PATCH "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "isEnabled": true,
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "twilioPhoneNumber": "+15551234567",
    "maxMessageLength": 1600
  }'

Parameter	Type	Required on `POST`	Description
`twilioAccountSid`	string	Yes	Your Twilio Account SID. Must start with `AC` followed by 32 characters.
`twilioAuthToken`	string	Yes	Your Twilio Auth Token (min 32 characters). Stored encrypted.
`twilioPhoneNumber`	string	Yes	Twilio phone number in E.164 format, e.g. `+15551234567`.
`isEnabled`	boolean	No	Whether SMS is active for this assistant. Default `true`.
`maxMessageLength`	integer	No	Characters per outbound message, `50`—`1600`. Default `1600`.
`enableContactMatching`	boolean	No	Match inbound senders to existing CRM contacts. Default `true`.
`autoCreateContacts`	boolean	No	Create a contact for an unrecognized sender. Default `true`.

Delete SMS Config

curl -X DELETE "https://app.illumichat.com/api/assistants/ast_abc123/sms" \
  -H "Cookie: <your-session-cookie>"

Response 204 No Content

Test SMS Credentials

Validates the provided Twilio credentials without saving them.

curl -X POST "https://app.illumichat.com/api/assistants/ast_abc123/sms/test" \
  -H "Cookie: <your-session-cookie>" \
  -H "Content-Type: application/json" \
  -d '{
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "twilioPhoneNumber": "+15551234567"
  }'

Response 200 OK

{
  "data": {
    "valid": true,
    "phoneNumberCapabilities": { "sms": true, "mms": true, "voice": true }
  }
}

List SMS Sessions

Returns the assistant’s SMS conversations, most recent first.

curl -X GET "https://app.illumichat.com/api/assistants/ast_abc123/sms/sessions?limit=10&offset=0" \
  -H "Cookie: <your-session-cookie>"

There is no per-assistant SMS analytics endpoint. For message volume broken down by channel, use GET /api/analytics/channels.

After configuring SMS, set the Twilio webhook URL to the value returned in the webhookUrl field of the SMS config response. This URL handles inbound messages from your customers.

Getting Started

Endpoints

Assistants

Assistant Configuration

Visibility Levels

List Assistants

Create Assistant

Get Assistant

Update Assistant

Delete Assistant

Knowledge (RAG)

SMS Configuration

Get SMS Config

Create or Update SMS Config

Delete SMS Config

Test SMS Credentials

List SMS Sessions

​Assistant Configuration

​Visibility Levels

​List Assistants

​Create Assistant

​Get Assistant

​Update Assistant

​Delete Assistant

​Knowledge (RAG)

​SMS Configuration

​Get SMS Config

​Create or Update SMS Config

​Delete SMS Config

​Test SMS Credentials

​List SMS Sessions

Assistant Configuration

Visibility Levels

List Assistants

Create Assistant

Get Assistant

Update Assistant

Delete Assistant

Knowledge (RAG)

SMS Configuration

Get SMS Config

Create or Update SMS Config

Delete SMS Config

Test SMS Credentials

List SMS Sessions