Conversation starters

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.

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

foldspace.agent('API-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

const agent = foldspace.agent('API-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

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:

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

Response:

{
  "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"
}