Embedded Widget vs Headless API
Understanding the differences between the two integration approaches.
EK Hub offers two ways to integrate AI chat into your application:
Comparison
| Feature | Embedded Widget | Headless API |
|---|---|---|
| UI provided | Yes (pre-built) | No (bring your own) |
| Auth mechanism | API key → JWT (20 min) | API key per request |
| Domain validation | Yes (origin check) | No (server-to-server) |
| CORS handling | Built-in | Not needed |
| HeyGen avatar | Supported | Not supported |
| Response buttons | Supported | Not supported |
| Follow-up suggestions | Supported | Supported |
| Response format | HTML | Markdown (default) or HTML |
| User identity | Anonymous (auto UUID) | Optional externalUserId |
| Setup effort | Minimal (copy-paste embed code) | More (build your own UI) |
| Customisation | Limited to widget config | Full control |
When to Use the Embedded Widget
- You want a quick, drop-in chat solution
- You don't need deep customisation
- You want HeyGen avatar support
- You're embedding in a website and want zero backend work
When to Use the Headless API
- You want full control over the chat UI design
- You're building a mobile app, desktop app, or custom web interface
- You need to integrate chat into an existing application or internal tool
- You want to build automated workflows or chatbots
- You need to track users with your own user IDs
Can I Use Both?
Yes! The embedded widget and headless API are completely independent. They share the same agents and knowledge base but use separate session management. You can use the widget on your website and the API for your mobile app simultaneously.