Skip to main content
Embed an AI agent conversation directly into your web app. Choose the level of control that fits your needs — drop-in component, headless state manager, or a single API call.

​
Drop-in component

One HTML tag, everything handled — input, streaming, scrolling. 
<gleap-agent-conversation agentId="YOUR_AGENT_ID"></gleap-agent-conversation>
With context and a custom placeholder: 
<gleap-agent-conversation
  agentId="YOUR_AGENT_ID"
  context='{"page": "/billing", "plan": "pro"}'
  placeholder="Ask about your billing..."
></gleap-agent-conversation>

​
Attributes

AttributeTypeDefaultDescription
agentIdstringrequiredThe agent ID
conversationIdstring—Resume an existing conversation
contextstring (JSON)—Additional context passed to the agent
placeholderstring"Type a message..."Input placeholder
emptyTextstring"How can I help you today?"Empty-state text
agentColorstringprimary colorOverride accent color
darkbooleanfalseDark mode

​
Events

The component dispatches DOM events you can listen to: 
const el = document.querySelector("gleap-agent-conversation");

el.addEventListener("gleap-agent-conversation-created", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-message-sent", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-reply-received", (e) => { /* e.detail */ });
el.addEventListener("gleap-agent-error", (e) => { /* e.detail */ });
The same events also fire on Gleap.on(...) without the gleap- prefix: 
Gleap.on("agent-reply-received", (data) => { /* ... */ });
Gleap.on("agent-error", (data) => { /* ... */ });
Gleap.on("agent-conversation-created", (data) => { /* ... */ });

​
Headless with Gleap.createAgentChat()

Manage state and streaming yourself, render any UI you want. 
const chat = Gleap.createAgentChat({
  agentId: "YOUR_AGENT_ID",
  context: { page: "/billing" },
  onChange: ({ messages, isExecuting, error, conversationId }) => {
    renderMessages(messages);
    toggleSpinner(isExecuting);
  },
});

chat.sendMessage("What is my current plan?");
Options
  • agentId – the agent to talk to (defaults to "kai").
  • context – arbitrary object passed to the agent.
  • conversationId – resume an existing conversation.
  • onChange({ messages, isExecuting, error, conversationId }) – called whenever state changes.
  • onToken, onReplyReceived, onError, onConversationCreated – optional lifecycle callbacks.
Returned instance
  • sendMessage(content) – send a user message (streams the reply).
  • setContext(context) – update the context for future messages.
  • clearMessages() – clear messages and start a new conversation.
  • cancelStream() – abort the in-flight stream.
  • getState() – { messages, isExecuting, error, conversationId }.
  • destroy() – tear down listeners. Always call when unmounting.
Each message is { id, role, content, createdAt, isStreaming? }. isStreaming is true while tokens are still arriving. To clear cached conversation state across the page (e.g. on logout): 
Gleap.clearAgentConversation();

​
Raw API

One call, you handle everything else. 
const result = await Gleap.sendAgentMessage("YOUR_AGENT_ID", "Hello!", {
  conversationId: previousConversationId,
  additionalContext: { page: "/billing" },
  onToken: (data) => { /* progressive streaming */ },
});

console.log(result.response);        // full reply
console.log(result.conversationId);  // for follow-up calls
Returns a Promise that resolves to { runId, status, response, conversationId }.

​
Custom styling

The drop-in component renders inside an iframe and accepts agentColor / dark for basic theming. For full control over the UI, use the headless createAgentChat() API and render your own components.