Skip to main content
Assistants are the core conversational entities in IllumiChat. Each assistant has its own system prompt, model configuration, and optional connections to knowledge base projects for retrieval-augmented generation (RAG).

​
Assistant Configuration

FieldTypeDefaultDescription
namestring—Display name shown to users.
instructionsstring""System prompt that defines the assistant’s behavior and persona.
modelstringWorkspace defaultAI model identifier (e.g., grok-2, gpt-4o). Must be in the workspace’s allowedModels.
visibilitystring"workspace"Access level: public, workspace, or private.
temperaturenumber0.7Sampling temperature between 0 and 2. Lower values produce more focused responses.
maxTokensinteger4096Maximum number of tokens in the assistant’s response.
welcomeMessagestringnullInitial message displayed when a conversation starts.
widgetEnabledbooleanfalseWhether the assistant is accessible via the embeddable widget.

​
Visibility Levels

VisibilityWho Can Access
publicAll workspace members. Accessible via widget when enabled.
workspaceOnly active members of the workspace.
privateOnly the creator, workspace admins, and users with explicit access grants.

​
List Assistants

Returns assistants accessible to the authenticated user within a workspace. Uses offset-based pagination. 
curl -X GET "https://beta.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": "grok-2",
      "visibility": "public",
      "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://beta.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.",
    "model": "grok-2",
    "visibility": "public",
    "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://beta.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, model, 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://beta.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://beta.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://beta.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://beta.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://beta.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://beta.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://beta.illumichat.com/api/sms/webhook/ast_abc123",
    "sessionTimeoutMinutes": 30,
    "createdAt": "2025-08-15T10:00:00Z"
  }
}

​
Update SMS Config

curl -X PUT "https://beta.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
  }'
ParameterTypeRequiredDescription
enabledbooleanYesWhether SMS is active for this assistant.
twilioAccountSidstringYesYour Twilio Account SID.
twilioAuthTokenstringYesYour Twilio Auth Token. Stored encrypted.
phoneNumberstringYesTwilio phone number in E.164 format.
sessionTimeoutMinutesintegerNoMinutes of inactivity before a session ends. Default 30.

​
Delete SMS Config

curl -X DELETE "https://beta.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://beta.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://beta.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms/analytics?period=30d" \
  -H "Authorization: Bearer <your-api-key>"
ParameterTypeDefaultDescription
periodstring30dTime 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.