Developer Integration Guide
Developer Overview
WebChatAgent gives you three ways to put a chatbot in front of your users. Pick one based on how much control you need over the interface.
| Integration | What you get | Best for |
|---|---|---|
| Widget Embed | A ready-made chat UI from one script tag | Websites and web apps |
| REST API | Send a message, get a reply (request/response) | Custom UIs, mobile apps, server scripts |
| WebSocket API | Real-time message stream with typing and presence | Live chat dashboards, agent tools |
| JavaScript SDK | Typed npm package for the REST and WebSocket API | Custom chat UIs in JavaScript or TypeScript |
All three talk to the same chatbot, share the same knowledge base, and count against the same message quota. You can mix them — for example, embed the widget on your site and build an internal agent dashboard on the WebSocket API.
Widget Embed (fastest)
Add the chatbot to any website with a single script tag and a custom HTML element (<web-chat-agent chatbot-id="...">). No framework, no build step. All colors, texts, and tools are configured in the dashboard and applied automatically. This is the right choice for 90% of websites.
- Widget Embed Guide — Script tag, custom element, all HTML attributes, custom CSS, inline mode, and SPA usage
REST API
When you need your own chat interface — a mobile app, a custom web component, or a backend automation — call the chat endpoint directly. You send a message plus your chatbotId and receive an AI-generated reply with its sources. A session ID returned in a response header keeps multi-turn conversations coherent.
- REST API Reference — Endpoints, domain auth, request/response fields, error codes, and code examples in cURL, JavaScript, Python, and PHP
JavaScript SDK
Building a custom chat UI in JavaScript or TypeScript? The webchatagent npm package wraps the REST and WebSocket API: streaming answers, file upload, feedback, lead forms and live chat with your team, with full TypeScript types and no dependencies.
- JavaScript SDK: install, first message, streaming, human handover. Package on npm, source on GitHub
WebSocket API
For live chat, where messages must arrive instantly and you want typing indicators, presence, and auto-translation. The same socket powers visitor widgets and the agent dashboard. Use it to build a custom agent console or to drive live chat from your own backend.
- WebSocket API Reference — Connection, roles, the events you send and receive, and a working client example
Which should I use?
| Use case | Recommended |
|---|---|
| Add a chatbot to a website | Widget Embed |
| Render the chat inside your own page layout | Inline chat (widget embed) |
| Custom chat UI in JavaScript or TypeScript | JavaScript SDK |
| Custom chat UI or mobile app | REST API |
| Server-to-server automation (no UI) | REST API |
| Real-time live chat dashboard for human agents | WebSocket API |
See Use Cases for concrete scenarios these integrations enable.