Chatbot API Integration
Integrate WebChatAgent into desktop apps, terminals, and internal tools via REST API — and switch to WebSocket for real live chat.
Bring chat into your product, not just your website.
Not every environment is a browser. With our Chatbot API you can build conversational UX directly into your software — from desktop clients to CLI tools and internal portals.
What problems does the Chatbot API solve?
Common integration roadblocks — and how an API fixes them cleanly.
A website widget doesn’t fit
Desktop applications, internal tools, or terminals need a native integration — not an embedded website widget.
Inconsistent chat experiences
Without a clear API, chat becomes a special case. With dedicated endpoints you keep UX consistent across your flows and UI components.
Live chat needs real-time
When a human takes over, real-time matters: status, messages, and files must arrive instantly — that’s what WebSocket is for.
How does the API solve these problems?
Start with REST for bot chat — and seamlessly move to WebSocket for live human takeover.
REST API for any frontend
Send messages via POST to /api/chat and render the reply in your UI. Perfect for desktop, mobile, backoffice, and CLI.
WebSocket for Live Chat (human takeover)
When the mode switches to human, connect via WebSocket and send/receive messages in real time — including session guards.
Code examples
Start in minutes: cURL for quick tests, JavaScript for production integrations.
# 1) First request (no session id). Use -i to see response headers.
curl -i -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-d '{
"message": "Hello, how can you help me?",
"chatbotId": "<your-chatbot-id>"
}'
# 2) Reuse the X-Chat-Session-Id from the response header for the conversation.
curl -X POST https://webchatagent.com/api/chat \
-H "Content-Type: application/json" \
-H "X-Chat-Session-Id: <session-id-from-response>" \
-d '{
"message": "Continue the conversation.",
"chatbotId": "<your-chatbot-id>"
}'async function sendChatMessage({ baseUrl, chatbotId, message, sessionId }) {
const res = await fetch(`${baseUrl}/api/chat`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Chat-Session-Id': sessionId || ''
},
body: JSON.stringify({ message, chatbotId })
});
const nextSessionId = res.headers.get('X-Chat-Session-Id') || sessionId || '';
if (!res.ok) throw new Error(await res.text());
const data = await res.json();
// data: { reply, sources, mode, status }
// If mode === 'human' and status === 'waiting' or 'open', switch to WebSocket
if (data.mode === 'human' && (data.status === 'waiting' || data.status === 'open')) {
// Switch to WebSocket for live chat
connectToLiveChat(nextSessionId, chatbotId);
}
return { data, sessionId: nextSessionId };
}Session handling: If you don’t send X-Chat-Session-Id, the server creates a new session and returns the session id in the response header. Persist it and send it on follow-up requests.
Example response when switching to live chat: [ "reply": "...", "sources": [], "mode": "human", "status": "waiting" ] — then switch to WebSocket.
What to consider for Live Chat
Live Chat runs over WebSocket. After connecting, join with chatbotId + sessionId and send messages as client:message. Only handle events for your current session.
// Use the same base URL as your REST calls (WebChatAgent domain).
const ws = new WebSocket('wss://webchatagent.com/api/livechat');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'client:join',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
as: 'user'
}));
};
function sendLiveChatMessage(text) {
ws.send(JSON.stringify({
type: 'client:message',
chatbotId: '<your-chatbot-id>',
sessionId: '<your-session-id>',
sender: 'user',
content: text
}));
}
ws.onmessage = (event) => {
const data = JSON.parse(event.data || '{}');
// data.type === 'livechat:message'
// data.sessionId guard recommended (handle only current session)
};Use REST (/api/chat) while the conversation is in bot mode.
Check the response: If mode='human' and status='waiting' or 'open' is returned, switch to WebSocket (/api/livechat).
Implement a session guard: ignore WebSocket events without sessionId or with a different sessionId.
Typical use cases
Examples of how teams use the API to embed support and workflows directly into their software.
Desktop app support
In-app help, troubleshooting, and onboarding — without sending users to a browser.
Terminal / CLI assistant
Answers and instructions in the terminal — great for DevOps, IT, and internal tooling.
Internal portals & backoffice
Employee self-service for policies, processes, and knowledge — directly in the intranet.
Escalation to live chat
Automate with a bot — and hand over seamlessly to a human when needed (WebSocket).
Embed chat where your users already are.
Start with REST and add live chat when needed. Built for production integrations — fast, stable, and easy to reason about.
Create an account