# Conversation starters

Configure the KNOWLEDGE and ACTION prompts shown on the agent entry screen, and override them at runtime with the programmatic API.

Conversation starters are the predefined prompts shown on the agent entry screen. Configure them statically with `setConfiguration`, or override them at runtime with the programmatic API.

To translate starters for different locales, see [Localization](/customize/localization/).

## conversationStarters

The set of starter prompts shown to the user. This is an object with two arrays, `KNOWLEDGE` and `ACTION`, each representing a distinct type of starter:

- **KNOWLEDGE**: informational or contextual questions based on existing knowledge.
- **ACTION**: task-oriented starters that trigger specific actions.

Each item in either array must follow the format `{ title: "" }`.

Type: `object`\
Default value: `{ "KNOWLEDGE": [], "ACTION": [] }`

## defaultConversationStarter

Which starter group is shown by default when the chat loads.

Type: `string`\
Default value: `"KNOWLEDGE"`\
Accepted values: `"KNOWLEDGE" | "ACTION"`

## startNewConversationOnStarterClick

Whether clicking a starter begins a new conversation instead of continuing the current one.

Type: `boolean`\
Default value: `false`

## Example

```javascript
foldspace.agent('YOUR-AGENT-KEY').setConfiguration({
  conversationStartersSettings: {
    defaultConversationStarter: "KNOWLEDGE",
    startNewConversationOnStarterClick: true,
    conversationStarters: {
      KNOWLEDGE: [
        { title: "What is your return policy?" },
        { title: "How do I track my order?" },
        { title: "Show me product specifications" }
      ],
      ACTION: [
        { title: "Schedule a demo" },
        { title: "Check my order status" },
        { title: "Contact support" }
      ]
    }
  }
});
```

## Programmatic API

### `setConversationStarters(starters, defaultStarterType?)`

Overrides the conversation starters shown on the entry screen at runtime. If called before the agent is ready, the call is queued and replayed once the agent initializes.

**Parameters:**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `starters` | `Record<"KNOWLEDGE" \| "ACTION", { title: string }[]>` | Yes | A record with `KNOWLEDGE` and `ACTION` arrays. Pass `null` to restore the original remote configuration starters. |
| `defaultStarterType` | `"KNOWLEDGE" \| "ACTION"` | No | Switch which starter tab is shown by default. If omitted or `null`, the original remote default is restored. |

**Returns:** the agent instance, enabling method chaining.

**Example: override starters**

```javascript
const agent = foldspace.agent('YOUR-AGENT-KEY');

agent.setConversationStarters(
  {
    KNOWLEDGE: [
      { title: "What is your return policy?" },
      { title: "How do I track my order?" }
    ],
    ACTION: [
      { title: "Schedule a demo" },
      { title: "Contact support" }
    ]
  },
  "ACTION"
);
```

**Example: restore original starters from remote config**

```javascript
agent.setConversationStarters(null);
```

### `getConversationStarters()`

Returns the current conversation starters and the default starter type. If starters were overridden via `setConversationStarters`, the overridden values are returned. Otherwise, it reflects the remote configuration.

**Parameters:** none.

**Returns:** `{ starters, defaultStarterType } | null`

Returns `null` if the agent is not yet initialized.

| Field | Type | Description |
| --- | --- | --- |
| `starters` | `Record<"KNOWLEDGE" \| "ACTION", { title: string }[]>` | The starters grouped by type. Each group is guaranteed to contain at least one entry. |
| `defaultStarterType` | `"KNOWLEDGE" \| "ACTION"` | Which starter tab is currently the default. |

**Example:**

```javascript
const result = agent.getConversationStarters();
console.log(result);
```

**Response:**

```json
{
  "starters": {
    "KNOWLEDGE": [
      { "title": "What is your return policy?" },
      { "title": "How do I track my order?" }
    ],
    "ACTION": [
      { "title": "Schedule a demo" },
      { "title": "Contact support" }
    ]
  },
  "defaultStarterType": "ACTION"
}
```