> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illumichat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Assistants

> Create and configure AI assistants with custom instructions, knowledge base connections, and SMS capabilities.

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.

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

**Response** `200 OK`

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
curl -X DELETE "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `204 No Content`

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

***

## 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.

<Note>
  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.
</Note>

### List Assistant Projects

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/projects" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

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

### Connect Project

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
curl -X GET "https://app.illumichat.com/api/workspaces/ws_abc123/assistants/ast_abc123/sms" \
  -H "Authorization: Bearer <your-api-key>"
```

**Response** `200 OK`

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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`

```json theme={null}
{
  "data": {
    "valid": true,
    "phoneNumberCapabilities": { "sms": true, "mms": true, "voice": true }
  }
}
```

### Get SMS Analytics

```bash theme={null}
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`

```json theme={null}
{
  "data": {
    "totalMessages": 1247,
    "inbound": 634,
    "outbound": 613,
    "uniqueContacts": 89,
    "activeSessions": 12,
    "period": "30d"
  }
}
```

<Tip>
  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.
</Tip>