Programmatic API

window.Ilana.init()

Initialize the widget manually instead of using data attributes:

const widget = window.Ilana.init({
  botId: 'your-bot-id',
  token: 'your-embed-token',
  runtimeUrl: 'https://api.getilana.ai', // optional
  position: 'bottom-right',               // optional
  theme: { primaryColor: '#0ea5e9' },     // optional
});

Returns an IlanaWidget instance (singleton — calling init() again returns the same instance).

WidgetConfig

Property	Type	Required	Default	Description
`botId`	`string`	Yes	—	Agent ID
`token`	`string`	Yes	—	Embed token
`runtimeUrl`	`string`	No	`https://api.getilana.ai`	Runtime API URL
`position`	`WidgetPosition`	No	`'bottom-right'`	Widget screen position
`theme`	`WidgetTheme`	No	`{}`	Theme overrides

IlanaWidget Methods

open()

Open the chat panel.

widget.open();

close()

Close the chat panel.

widget.close();

toggle()

Toggle the chat panel open or closed.

widget.toggle();

sendMessage(content)

Send a message programmatically, as if the user typed it:

await widget.sendMessage('What are your pricing plans?');

getState()

Get the current widget state:

const state = widget.getState();
console.log(state.isOpen);          // boolean
console.log(state.messages.length); // number

Returns a WidgetState object:

Property	Type	Description
`isOpen`	`boolean`	Whether the chat panel is open
`isLoading`	`boolean`	Whether a response is being generated
`conversationId`	`string \| null`	Current conversation ID
`messages`	`WidgetMessage[]`	All messages in the conversation
`error`	`string \| null`	Current error message, if any

Each WidgetMessage has:

Property	Type	Description
`id`	`string`	Message UUID
`role`	`'user' \| 'assistant'`	Who sent the message
`content`	`string`	Message text
`timestamp`	`Date`	When the message was sent

clearConversation()

Clear all messages and reset the conversation:

widget.clearConversation();

destroy()

Remove the widget from the DOM entirely:

widget.destroy();

Example: Custom Trigger

Use the programmatic API to open the widget from a custom button:

<button id="help-btn">Need help?</button>

<script src="https://cdn.getilana.ai/embed.js"></script>
<script>
  const widget = window.Ilana.init({
    botId: 'your-bot-id',
    token: 'your-embed-token',
  });

  document.getElementById('help-btn').addEventListener('click', () => {
    widget.open();
    widget.sendMessage('I need help getting started');
  });
</script>

Programmatic API

On this page