IllumiChat - AI-Powered Chat Platform

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

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.
`widgetEnabled`	boolean	`false`	Whether the assistant is accessible via the embeddable widget.

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 entirely by widgetEnabled, 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. Uses offset-based pagination.

curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/assistants?limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Response 200 OK

{
  "data": [
    {
      "id": "ast_abc123",
      "name": "Support Bot",
      "model": "auto",
      "visibility": "workspace",
      "widgetEnabled": true,
      "projectCount": 2,
      "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/workspaces/ws_abc123/assistants" \
  -H "Authorization: Bearer <your-api-key>" \
  -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/workspaces/ws_abc123/assistants/ast_abc123" \
  -H "Authorization: Bearer <your-api-key>"

Response 200 OK with the full assistant object including instructions, temperature, maxTokens, visibility, welcomeMessage, widgetEnabled, projectCount, 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/workspaces/ws_abc123/assistants/ast_abc123" \
  -H "Authorization: Bearer <your-api-key>" \
  -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/workspaces/ws_abc123/assistants/ast_abc123" \
  -H "Authorization: Bearer <your-api-key>"

Response 204 No Content

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

Project Connections (RAG)

Assistants can be connected to projects to enable retrieval-augmented generation. When a user sends a message, the assistant searches connected projects for relevant context and includes it in the prompt.

Projects contain documents that are chunked, embedded, and stored in a vector database (Pinecone). Connecting a project to an assistant gives it access to that knowledge base during conversations.

List Assistant Projects

curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/projects" \
  -H "Authorization: Bearer <your-api-key>"

Response 200 OK

{
  "data": [
    {
      "id": "proj_aaa111",
      "name": "Product Documentation",
      "documentCount": 45,
      "connectedAt": "2025-08-01T12:00:00Z"
    }
  ]
}

Connect Project

curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/projects" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "projectId": "proj_aaa111" }'

Response 201 Created

Disconnect Project

curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/projects/proj_aaa111" \
  -H "Authorization: Bearer <your-api-key>"

Response 204 No Content

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/workspaces/ws_abc123/assistants/ast_abc123/sms" \
  -H "Authorization: Bearer <your-api-key>"

Response 200 OK

{
  "data": {
    "enabled": true,
    "phoneNumber": "+15551234567",
    "twilioAccountSid": "AC...",
    "webhookUrl": "https://app.illumichat.com/api/sms/webhook/ast_abc123",
    "sessionTimeoutMinutes": 30,
    "createdAt": "2025-08-15T10:00:00Z"
  }
}

Update SMS Config

curl -X PUT "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "phoneNumber": "+15551234567",
    "sessionTimeoutMinutes": 30
  }'

Parameter	Type	Required	Description
`enabled`	boolean	Yes	Whether SMS is active for this assistant.
`twilioAccountSid`	string	Yes	Your Twilio Account SID.
`twilioAuthToken`	string	Yes	Your Twilio Auth Token. Stored encrypted.
`phoneNumber`	string	Yes	Twilio phone number in E.164 format.
`sessionTimeoutMinutes`	integer	No	Minutes of inactivity before a session ends. Default `30`.

Delete SMS Config

curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms" \
  -H "Authorization: Bearer <your-api-key>"

Response 204 No Content

Test SMS Credentials

Validates the provided Twilio credentials without saving them.

curl -X POST "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms/test" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "twilioAccountSid": "AC...",
    "twilioAuthToken": "your_auth_token",
    "phoneNumber": "+15551234567"
  }'

Response 200 OK

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

Get SMS Analytics

curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms/analytics?period=30d" \
  -H "Authorization: Bearer <your-api-key>"

Parameter	Type	Default	Description
`period`	string	`30d`	Time period: `7d`, `30d`, or `90d`.

Response 200 OK

{
  "data": {
    "totalMessages": 1247,
    "inbound": 634,
    "outbound": 613,
    "uniqueContacts": 89,
    "activeSessions": 12,
    "period": "30d"
  }
}

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

Project Connections (RAG)

List Assistant Projects

Connect Project

Disconnect Project

SMS Configuration

Get SMS Config

Update SMS Config

Delete SMS Config

Test SMS Credentials

Get SMS Analytics

​Assistant Configuration

​Visibility Levels

​List Assistants

​Create Assistant

​Get Assistant

​Update Assistant

​Delete Assistant

​Project Connections (RAG)

​List Assistant Projects

​Connect Project

​Disconnect Project

​SMS Configuration

​Get SMS Config

​Update SMS Config

​Delete SMS Config

​Test SMS Credentials

​Get SMS Analytics

Assistant Configuration

Visibility Levels

List Assistants

Create Assistant

Get Assistant

Update Assistant

Delete Assistant

Project Connections (RAG)

List Assistant Projects

Connect Project

Disconnect Project

SMS Configuration

Get SMS Config

Update SMS Config

Delete SMS Config

Test SMS Credentials

Get SMS Analytics