Everything you need to launch your chatbot
A plain-language guide to building, customizing, and embedding your Obdal AI chatbot — from your first App to going live on your website.
What Obdal is, in plain terms
Obdal turns your own content into a 24/7 AI chatbot you can place on any website. This page walks you through the whole journey. Before the steps, it helps to know five words you will see everywhere: an App is a single chatbot; its Knowledge base is the files and FAQs it answers from; the Widget is the chat bubble visitors see; the Designer is where you style that widget; and Conversations are the chats it handles. Once those click, the rest of the docs read quickly.
App (chatbot)
One chatbot is one App. Everything else — its knowledge, its design, its conversations — belongs to that App.
Knowledge base
The files you upload and the FAQs you write. Your chatbot answers only from this content, so it stays accurate to your business.
Widget
The chat bubble your visitors click to open a conversation. It lives on your website once you paste in the embed code.
Designer
The no-code studio where you style the widget — its colors, theme, position, and welcome message — with a live preview.
Conversations
Each chat your widget handles. Conversations are how usage is measured, and your plan sets how many you get each month.
How the pieces fit together
Your content powers an App, the App drives the Widget, and the Widget lives on your site.
- App
- Knowledge
- Widget
- Your site
One account can hold several Apps, and each one is fully separate — its own knowledge, its own API key, its own widget design, and its own conversations. Nothing leaks from one chatbot to another.
From empty dashboard to live chatbot
You can have a working chatbot live in four steps. First, create an App from your dashboard. Second, add knowledge by uploading files or writing FAQs so the bot has something to answer from. Third, open the Designer and customize how the widget looks and where it sits. Fourth, publish by copying the embed code onto your site. Each step below links to its own deeper section, but this is the full happy path from empty dashboard to live chatbot.
- 1
Create an App
From your Apps dashboard, create a new App and give it a name. Naming it automatically generates its API key, so the chatbot is ready to be set up.
- 2
Add your knowledge
Upload files and write FAQs so the bot has something to answer from. Uploaded files are processed in the background and take a moment before they become searchable.
- 3
Customize the widget
Open the Designer to set the bot name, avatar, welcome message, theme, and colors. The live preview updates instantly as you change anything.
- 4
Publish to your site
Copy the embed code from the Designer's Publish tab and paste it onto your website. The Free plan is enough to go live.
Set your allowed origins, or the widget stays hidden
For non-English answers, set the language yourself
Putting the widget on your website
Publishing means pasting one snippet of code onto your website. Open your App, go to the Designer's Publish tab, and copy the embed code. Paste it just before the closing tag of any page where the widget should appear — most site builders have a place for custom HTML or footer scripts. For the widget to load, your site's address must be added to the allowed origins, or the chat will stay hidden. If your site is a single-page app, the snippet still works once it is in your main layout. Direct WordPress and Shopify integrations are on the way; for now the embed code works on every platform.
The embed snippet
Copy this from the Designer's Publish tab — your real snippet carries your own API key.
<script> window.obdalConfig = { apiKey: "your-app-api-key", baseUrl: "https://obdal.com" };</script><script async src="https://obdal.com/widget-loader.js"></script>Where to paste it
Add the snippet just before the closing </body> tag on every page where the widget should appear. It initializes itself — there is nothing else to wire up. Most site builders offer a custom HTML or footer-scripts area that is perfect for this.
Add your site to allowed origins
Single-page apps
If your site uses client-side routing, place the snippet once in your main layout. The loader initializes on page load and the widget stays available as visitors move between views.
Platform plugins
Dedicated WordPress and Shopify plugins are coming soon. Until they land, the script embed above works on every platform, including those two.
It updates itself
Styling your widget, field by field
The Designer is where your chatbot gets its look, and a live preview updates as you change anything. It has four tabs. General covers the bot name, avatar, and welcome message. Appearance is the largest tab: theme and colors, header and message styles, fonts, window size, corner radius, animations, and the chat toggle button. Position sets which corner the bubble sits in, with separate placement for mobile. Publish gives you the embed code and the allowed-origins reminder. This section is a plain-language reference to every field, so you always know what each control does before you touch it.
Every change shows up immediately in the live preview, so you can see exactly what visitors will see before you publish.
The basics your visitors notice first.
| Field | Options | What it does |
|---|---|---|
| Bot Name | Text | The name shown at the top of the chat window, such as your brand or assistant name. |
| Avatar | SVG / PNG / JPG | The image beside the bot's messages. Upload an SVG, PNG, or JPG up to 1500px on its longest side. |
| Welcome Message | Text | The first message visitors see when they open the chat. Use it to set the tone and invite a question. |
Running a chatbot in another language
Running a chatbot in another language takes two separate settings, and knowing the difference saves a lot of confusion. The widget's interface text (buttons, placeholders) ships in English and Hungarian; you choose which by setting the locale in your embed code — there is no toggle in the Designer for this. Separately, the language the bot replies in is controlled by your System Prompt, not by auto-detection: to get Hungarian answers, tell the bot to answer in Hungarian. One honest note up front: visitors cannot switch the chat language themselves, so you set the language for each embed rather than offering a picker.
Yes, the widget ships with Hungarian interface text and the bot can answer in Hungarian. It is just not a Designer toggle, which is why owners often assume it is not possible. There are two separate levers, and you set both yourself.
Lever 1 — Widget interface language
The widget's buttons and placeholders ship in English (the default) and Hungarian. You choose which by setting window.obdalConfig.locale in your embed code. Add the highlighted line below; the copied snippet does not include it, so this is a manual addition.
Set the widget locale
Add the locale line to your embed snippet — it is not there by default.
<script> window.obdalConfig = { apiKey: "your-app-api-key", baseUrl: "https://obdal.com", locale: "hu" };</script><script async src="https://obdal.com/widget-loader.js"></script>Lever 2 — The language the bot replies in
Which language the bot answers in is controlled by your System Prompt in App Settings, not by auto-detection. To get Hungarian answers, add an instruction such as "Always answer in Hungarian." The bot follows the prompt; it does not guess from the visitor's message.
A fully Hungarian chatbot
There is no end-visitor language switcher
Supported interface languages: English (en, the default) and Hungarian (hu).
Running the chatbot in another language is available on every plan. It is never a paid upgrade.
Dark, light, and your brand colors
Obdal has two completely separate themes, and mixing them up is the most common point of confusion. The dashboard theme — the Light, Dark, or System toggle at the top right of your dashboard — only changes what you see while managing your chatbot. It has no effect on the widget. The widget theme is set in the Designer's Appearance tab under Theme & Color, where you pick Light or Dark and fine-tune six colors per mode: background, text, border, the user bubble, the bot bubble, and the primary accent. Your visitors see the widget theme you choose; they cannot switch it themselves.
Two separate themes
Changing one never changes the other. The dashboard theme is for you while you work; the widget theme is what visitors see on your site.
The Light / Dark / System toggle at the top right of your dashboard. Only affects what you see while managing your chatbot.
Set in the Designer's Appearance tab. This is what your visitors actually see on your website.
Theme and color in the Appearance tab
In the Designer's Appearance tab, pick a Light or Dark widget theme, then fine-tune six colors for that mode.
Background
The main surface color of the chat window.
Text
The color of message and label text.
Border
The color of dividers and the window edge.
User bubble
The background of messages sent by your visitor.
Bot bubble
The background of messages sent by the bot.
Primary
The accent color used for buttons and highlights.
Choose your brand color from six presets or set a custom one. The primary color you pick cascades to the user-bubble color, so the widget stays on brand without extra tweaking.
Visitors cannot switch the widget theme
App and profile settings
App Settings is the control panel for how your chatbot behaves, separate from how it looks. Here you manage the API key (you can regenerate it, but doing so breaks any embeds already using the old one), set the personality and tone, write the System Prompt that shapes every answer and its language, choose a currency, and turn on Live Chat for human handoff. Your own account details — name, email, and password — live separately in Profile Settings. This section explains each field and when you would change it.
App Settings
Per-chatbot configuration for how this App behaves.
| Field | Options | What it does |
|---|---|---|
| API Key | Masked · Regenerate | Authenticates your App. Shown with only the last few characters. You can regenerate it, but every existing embed using the old key will stop working. |
| Personality / Tone | Tone dropdown | Sets the voice the bot writes in, from a Tone Style dropdown — for example friendly, formal, or concise. |
| System Prompt | Max 2000 chars | The core instructions that shape every answer, including which language the bot replies in. The single most important setting for behavior. |
| Currency | 100+ searchable | The currency the bot uses when it talks about prices. Pick from a searchable list of over a hundred. |
| Live Chat | On / Off | Turns on human handoff so a live agent can take over a conversation when a visitor needs a person. |
Regenerating the API key breaks existing embeds
Profile Settings
Your personal account details — name, email, and password — live in Profile Settings, separate from any App. Changing them does not affect your chatbots.
App Settings is about a chatbot; Profile Settings is about you. If you are hunting for a bot control under your account profile, look in App Settings instead.
FAQs and your knowledge base
FAQs give your chatbot fast, exact answers to the questions you already know visitors ask, alongside the files in your knowledge base. You can create, edit, and delete FAQs, group them into categories, pin up to five so they surface first, reorder them, and switch any of them active or inactive. FAQs are part of every paid plan, so if you are on the Free plan you will upgrade to unlock them. This section covers managing your knowledge base and getting the most out of pinned, well-categorized answers.
Create, edit, and delete
Write a question and its answer, update them any time, and remove the ones you no longer need.
Group into categories
Organize FAQs into categories so related questions stay together and are easier to manage.
Pin up to five
Pin your most important answers — up to five — so they surface first for visitors.
Reorder freely
Arrange FAQs in the order you want, putting the most useful answers near the top.
Set active or inactive
Switch any FAQ on or off without deleting it, so you can retire an answer temporarily.
FAQs are a paid-plan feature
Use FAQs for short, frequently asked questions with exact answers, and uploaded files for longer reference material. Both feed the same chat, so the bot draws on whichever fits the question best.
Handing a chat to a real person
Sometimes a visitor needs a real person, and human handoff lets one step in. Turn on Live Chat in your App Settings, and your chatbot can pass a conversation to a live agent who takes over the chat. Each plan includes a set number of agent seats — the people on your side who can answer — scaling up as you move to larger plans. This section explains how to enable handoff, what happens during a takeover, and how seats map to your plan.
Turn on Live Chat
Open App Settings and switch on Live Chat (Human Handoff). Once it is on, an agent can step into any conversation and take over from the bot. You can also set an offline message for when no agent is available.
Agent seats scale with your plan
Each plan includes a number of agent seats — the teammates who can answer live chats. The settings card shows how many seats are used against your limit, and the count grows on larger plans. See the Plans section for the exact numbers.
When no agent is available
If no agent is online, visitors see the offline message you configured — for example an email address to reach you. The conversation is never left silent.
Human handoff is a paid-plan feature
Plans and what each one unlocks
Your plan decides what your chatbots can do, and this section maps each capability to where it unlocks. The limits that scale with your plan are the ones to watch: monthly conversations, storage for your files, how many widgets you can run, whether FAQs are available, human handoff and how many agent seats you get, removing the "Powered by" branding, the AI model tier, and your support and SLA level. The figures here come straight from your live plan data, so they are always current. When you are ready to compare side by side, head to the pricing page.
| Capability | Free Free | Starter 15/mo | Growth 39/moPopular | Pro 89/mo | Business 179/mo |
|---|---|---|---|---|---|
| Monthly conversationsChats your widgets handle each month. | 50 | 500 | 1,500 | 4,000 | 10,000 |
| Knowledge storageSpace for the files in your knowledge base. | 100 MB | 1 GB | 5 GB | 20 GB | 50 GB |
| WidgetsHow many separate chatbots you can run. | 1 | 1 | 3 | 10 | Unlimited |
| FAQsCurated question-and-answer entries. | |||||
| Human handoffLet a live agent take over a chat. | |||||
| Agent seatsTeammates who can answer live chats. | 0 | 2 | 5 | 15 | Unlimited |
| Remove "Powered by" brandingHide the Obdal badge on the widget. | |||||
| AI model tierThe quality of the model behind your answers. | Fast | Fast | Advanced | Premium | Premium |
- Monthly conversations
- 50
- Knowledge storage
- 100 MB
- Widgets
- 1
- FAQs
- Human handoff
- Agent seats
- 0
- Remove "Powered by" branding
- AI model tier
- Fast
- Monthly conversations
- 500
- Knowledge storage
- 1 GB
- Widgets
- 1
- FAQs
- Human handoff
- Agent seats
- 2
- Remove "Powered by" branding
- AI model tier
- Fast
- Monthly conversations
- 1,500
- Knowledge storage
- 5 GB
- Widgets
- 3
- FAQs
- Human handoff
- Agent seats
- 5
- Remove "Powered by" branding
- AI model tier
- Advanced
- Monthly conversations
- 4,000
- Knowledge storage
- 20 GB
- Widgets
- 10
- FAQs
- Human handoff
- Agent seats
- 15
- Remove "Powered by" branding
- AI model tier
- Premium
- Monthly conversations
- 10,000
- Knowledge storage
- 50 GB
- Widgets
- Unlimited
- FAQs
- Human handoff
- Agent seats
- Unlimited
- Remove "Powered by" branding
- AI model tier
- Premium
These are available on every plan
The REST API for developers
The Developer API lets your own software do what the dashboard does: chat with the assistant, read conversations, upload knowledge files, push a product catalog that renders as product cards, and run live handoff. Every request is authenticated with two credentials that must belong to the same account: the app's API key from App Settings and the email you log in with. Keep both on your server. If you only need the widget on a website, skip this section; the embed code requires no coding.
Fixing the usual snags
Most issues come down to a handful of predictable causes, and each has a quick fix. If the widget still shows "Powered by Obdal," branding removal is a paid-plan feature — upgrade to hide it. If the bot answers in the wrong language, the fix is in your System Prompt, not a hidden language setting: tell it which language to reply in. And if the widget does not appear at all, the cause is almost always allowed origins — add your site's exact address in the Publish tab so the widget is permitted to load. This section walks through these and the other real confusions owners run into.
Why does it say "Powered by Obdal"?
Removing that badge is a paid-plan feature. It shows on the Free plan and is removable from the Starter plan upward. Upgrade and the branding disappears. See the Plans section.
See PlansWhy won't it answer in Hungarian?
The bot does not auto-detect the language. Set the reply language in your System Prompt (for example, "Always answer in Hungarian") and set the widget's interface language with the locale in your embed code. See the Multilingual chatbot section.
See Multilingual chatbotThe widget isn't appearing at all.
This is almost always allowed origins — the loader refuses to run on an unlisted domain and logs origin_not_allowed. Other blockers it logs include subscription_required, conversation_limit_reached, trial_limit_reached, owner_not_found, app_not_found, and a wrong API key. Check the Embedding section.
See EmbeddingMy dashboard is dark but the widget is light (or the reverse).
That is expected. The dashboard theme and the widget theme are independent settings, and changing one never changes the other. See the Theming section.
See ThemingI regenerated my API key and the widget broke.
The old key in your published embed no longer works. Copy the fresh snippet from the Publish tab and re-paste it everywhere the widget appears. See the App settings section.
See SettingsIt is still blocked for another reason.
Open your browser's developer console on the page with the widget. The loader logs the exact reason it did not render, which points you straight to the fix.
See EmbeddingCheck the browser console first
Three steps to your first authenticated request.
The Developer API is a server-to-server surface. Every call carries your app's API key and your account email, so keep both on your backend and never ship them in browser code.
Copy your app API key
Open App Settings and copy the API key of the app you want to talk to. Regenerating the key invalidates the old one everywhere.
Send both credentials as headers
Add X-Api-Key with the key and X-Account-Email with the email you log in with. A mismatch on either returns 401 invalid_credentials.
Call the endpoints
Start with GET /developer/app to confirm the connection, then chat, upload knowledge files, push products, or manage live handoff.
-H "X-Api-Key: $API_KEY" \
-H "X-Account-Email: $ACCOUNT_EMAIL" \
-H "Content-Type: application/json" \
-d '{
"message": "Do you ship to Canada?"
}'
const res = await fetch('https://obdal.com/api/v1/developer/chat', {
method: 'POST',
headers: {
'X-Api-Key': process.env.OBDAL_API_KEY,
'X-Account-Email': process.env.OBDAL_ACCOUNT_EMAIL,
'Content-Type': 'application/json'
},
body: JSON.stringify({ message: 'Do you ship to Canada?', session_id })
});
const { message, products } = await res.json();
Every Developer API endpoint, with its request and response.
All endpoints live under /api/v1/developer, require the two credential headers, and answer with JSON. Successful responses carry success: true; failures carry success: false, an error message and a machine-readable code.
Authentication on every request
Connection
Confirm the credentials and discover what the app accepts.
/api/v1/developer/app
Returns the app profile, plan limits and the accepted upload formats. Use it as a connection test.
Request
GET /api/v1/developer/app X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"app": { "id": 12, "name": "Support bot", "locale": "en", "human_handoff_enabled": true },
"account": { "email": "you@example.com" },
"limits": { "plan": { "name": "Growth" }, "usage": { "conversations": {...}, "storage": {...} } },
"upload": { "extensions": [".pdf", ".txt", ".md", ".docx", ".xlsx", ".csv", ".html", ".json", ".jsonl", ".xml"], "max_size_kb": 10240 }
}Chat, sessions and usage
Talk to the assistant from your own backend, read transcripts, close conversations and track token usage. Sessions started here are tagged with the api channel in your dashboard.
/api/v1/developer/chat
Sends a visitor message and returns the assistant reply. Omit session_id to start a new conversation; pass stream: true to receive server-sent events. While the session is with a live agent the message is forwarded to the agent and the response is 202 with handoff_active: true.
Request
{
"message": "Do you ship to Canada?",
"session_id": "3f7c1a9e-6d2b-4c58-9c0e-7b1f2d3e4a55",
"stream": false
}Response
{
"success": true,
"message": "Yes, we ship to Canada within 5 business days.",
"session_id": "3f7c1a9e-6d2b-4c58-9c0e-7b1f2d3e4a55",
"products": [ { "type": "product", "title": "Alpine Snowboard", "url": "https://...", "price_min": "49.99", "currency": "USD" } ],
"suggest_handoff": false
}/api/v1/developer/sessions
Lists conversations of the app, newest first, with pagination.
Request
GET /api/v1/developer/sessions?page=1&per_page=20 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"sessions": [
{ "session_id": "3f7c1a9e-...", "title": "Shipping to Canada", "last_at": "2026-09-13T10:30:00Z", "status": "active", "preview": "Yes, we ship..." }
],
"meta": { "current_page": 1, "per_page": 20, "total": 1, "has_more": false }
}/api/v1/developer/sessions/{session_id}/messages
Returns the full transcript of a session together with its status and handoff state.
Request
GET /api/v1/developer/sessions/3f7c1a9e-.../messages?limit=100 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"session": { "session_id": "3f7c1a9e-...", "channel": "api", "status": "active", "is_closed": false, "handoff_status": "none", "message_count": 2 },
"messages": [
{ "role": "user", "content": "Do you ship to Canada?", "sequence": 1, "timestamp": 1757757000000 },
{ "role": "assistant", "content": "Yes, we ship to Canada...", "sequence": 2, "timestamp": 1757757003000 }
]
}/api/v1/developer/sessions/{session_id}/close
Closes a session. Closed sessions reject new messages with 410.
Request
POST /api/v1/developer/sessions/3f7c1a9e-.../close X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "closed": true }/api/v1/developer/usage
Aggregates requests, tokens and cost, optionally filtered by session_id, start_date and end_date.
Request
GET /api/v1/developer/usage?start_date=2026-09-01&end_date=2026-09-30 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"usage": { "total_requests": 1842, "total_input_tokens": 205401, "total_output_tokens": 216529, "total_tokens": 421930, "total_cost": 12.45 },
"by_model": [ { "model": "gpt-5.6", "provider": "OpenAI", "requests": 1842, "total_tokens": 421930, "cost": 12.45 } ]
}Knowledge files
Upload the same document types the dashboard accepts. Files are chunked, embedded and indexed in the background; poll the status until it reads completed.
/api/v1/developer/files
Uploads up to 20 files per request as multipart/form-data under files[] (or a single file under file). Allowed types: pdf, txt, md, docx, xlsx, csv, html, json, jsonl, xml; 10 MB each.
Request
curl -X POST /api/v1/developer/files \ -H "X-Api-Key: $API_KEY" -H "X-Account-Email: $EMAIL" \ -F "files[]=@./faq.pdf" -F "files[]=@./returns-policy.md"
Response
{
"success": true,
"files": [
{ "id": 91, "name": "faq.pdf", "size": 48213, "mime_type": "application/pdf", "status": "pending", "stage": "queued", "progress": 0, "uploaded_at": "2026-09-13T10:31:00Z" }
]
}/api/v1/developer/files
Lists knowledge files with their processing status.
Request
GET /api/v1/developer/files X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"files": [ { "id": 91, "name": "faq.pdf", "status": "completed", "progress": 100, "chunk_count": 14, "indexed_at": "2026-09-13T10:32:10Z" } ]
}/api/v1/developer/files/{id}
Returns one file with its processing progress.
Request
GET /api/v1/developer/files/91 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "file": { "id": 91, "name": "faq.pdf", "status": "completed", "progress": 100, "error": null } }/api/v1/developer/files/{id}
Removes a file, its chunks and its vectors from the knowledge base.
Request
DELETE /api/v1/developer/files/91 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "deleted": true }Products
Push your catalog so the assistant can answer product questions and show product cards in the chat, exactly like the Shopify integration. Product ids are yours: reuse them to update or delete.
/api/v1/developer/products
Creates or updates up to 100 products in one call. Unchanged products are skipped; changed ones are re-indexed in place. Only id, title and an https url are required. Each product reports its own status (created, updated, skipped or failed), so one failing item never hides the others.
Request
{
"products": [
{
"id": "sku-100",
"title": "Alpine Snowboard",
"url": "https://shop.example.com/products/alpine-snowboard",
"description": "All-mountain board for powder and park.",
"image_url": "https://cdn.example.com/alpine.jpg",
"price": "49.99",
"currency": "USD",
"vendor": "Obdal",
"product_type": "Snowboard",
"in_stock": true,
"collections": ["Winter Gear"],
"tags": ["snow", "board"],
"attributes": { "Length": "156 cm" },
"variants": [ { "id": "v1", "title": "156 cm", "price": "49.99", "sku": "ALP-156", "available": true } ]
}
]
}Response
{
"success": true,
"summary": { "created": 1, "updated": 0, "skipped": 0, "failed": 0 },
"results": [ { "id": "sku-100", "status": "created" } ]
}/api/v1/developer/products
Lists the products you pushed, with their indexing status.
Request
GET /api/v1/developer/products?page=1&per_page=50 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"products": [ { "id": "sku-100", "title": "Alpine Snowboard", "url": "https://...", "price_min": "49.99", "status": "completed", "updated_at": "2026-09-13T10:40:00Z" } ],
"meta": { "current_page": 1, "per_page": 50, "total": 1, "has_more": false }
}/api/v1/developer/products/{id}
Returns one product by the id you assigned.
Request
GET /api/v1/developer/products/sku-100 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "product": { "id": "sku-100", "title": "Alpine Snowboard", "in_stock": true, "variants": [...], "status": "completed" } }/api/v1/developer/products/{id}
Removes a product and its vectors.
Request
DELETE /api/v1/developer/products/sku-100 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "deleted": true }Human handoff
Manage live chat from your own tooling. The account owner acts as the agent: go online, watch the queue, claim a waiting conversation, reply, and end it. Send a heartbeat at least every 60 seconds to stay online.
/api/v1/developer/handoff/settings
Shows whether live chat is enabled, the offline message, seat usage, and how many agents are online.
Request
GET /api/v1/developer/handoff/settings X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"settings": { "human_handoff_enabled": true, "handoff_offline_message": "Email help@example.com", "can_use_handoff": true, "handoff_available": true, "seats": { "limit": 3, "used": 1 }, "available_agents": 1, "my_availability": true }
}/api/v1/developer/handoff/settings
Enables or disables live chat and sets the offline message. Requires a plan that includes human handoff.
Request
{ "human_handoff_enabled": true, "handoff_offline_message": "Email help@example.com" }Response
{ "success": true, "settings": { "human_handoff_enabled": true, "handoff_offline_message": "Email help@example.com", ... } }/api/v1/developer/handoff/availability
Marks the account owner as available (or away) for live chats.
Request
{ "is_available": true }Response
{ "success": true, "is_available": true, "ttl_seconds": 60 }/api/v1/developer/handoff/heartbeat
Keeps the owner's presence alive. Presence expires 60 seconds after the last heartbeat or availability call.
Request
POST /api/v1/developer/handoff/heartbeat X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "is_available": true, "ttl_seconds": 60 }/api/v1/developer/handoff/queue
Lists conversations waiting for an agent, the ones you are handling, and recently ended ones.
Request
GET /api/v1/developer/handoff/queue X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"waiting": [ { "session_id": "3f7c1a9e-...", "preview": "I need a human", "requested_at": "2026-09-13T10:45:00Z" } ],
"mine": [],
"ended": [],
"available_agents": 1
}/api/v1/developer/handoff/sessions/{session_id}/request
Escalates a session to a live agent. Returns requested when an agent is online, or no_agents with the offline message otherwise.
Request
POST /api/v1/developer/handoff/sessions/3f7c1a9e-.../request X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "session_id": "3f7c1a9e-...", "handoff_status": "requested", "queue_timeout_seconds": 180 }/api/v1/developer/handoff/sessions/{session_id}/claim
Takes over a waiting conversation as the agent. Returns 409 not_claimable if it is no longer waiting.
Request
POST /api/v1/developer/handoff/sessions/3f7c1a9e-.../claim X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "claimed": true, "handoff_status": "active" }/api/v1/developer/handoff/sessions/{session_id}/messages
Sends an agent reply into a conversation you have claimed.
Request
{ "message": "Hi, this is Anna. How can I help?" }Response
{ "success": true, "message": { "id": 501, "role": "agent", "content": "Hi, this is Anna. How can I help?", "sequence": 7, "created_at": "2026-09-13T10:46:00Z" } }/api/v1/developer/handoff/sessions/{session_id}/messages
Polls the transcript; pass after_sequence to receive only newer messages.
Request
GET /api/v1/developer/handoff/sessions/3f7c1a9e-.../messages?after_sequence=7 X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{
"success": true,
"handoff_status": "active",
"agent": { "name": "Anna" },
"ended_reason": null,
"messages": [ { "role": "user", "content": "Where is my order?", "sequence": 8, "created_at": "2026-09-13T10:46:30Z" } ]
}/api/v1/developer/handoff/sessions/{session_id}/end
Ends the live chat and hands the conversation back to the assistant.
Request
POST /api/v1/developer/handoff/sessions/3f7c1a9e-.../end X-Api-Key: your_app_api_key X-Account-Email: you@example.com
Response
{ "success": true, "handoff_status": "ended" }Errors and rate limits
Errors are JSON with success: false, a human-readable error and a stable code. Validation failures use the standard 422 shape with a message and an errors map.
| Status | Code | Meaning |
|---|---|---|
| 401 | invalid_credentials | The API key or the account email is missing or does not match the app owner. |
| 422 | validation | A required field is missing or malformed; see the errors map. |
| 403 | subscription_required / conversation_limit_reached | The owner has no usable subscription (every endpoint), or the plan's conversation limit is reached (chat only). |
| 403 | storage_limit_exceeded | The upload would exceed the plan's storage limit. Product batches report this per item with status failed. |
| 403 | handoff_unavailable | Live chat is disabled for the app or not included in the plan. Escalate, claim and reply all re-check this. |
| 409 | not_claimable | The session is not waiting for an agent. |
| 409 | handoff_not_active | The session is not currently assigned to you. |
| 410 | session_closed | The session was closed and no longer accepts messages. |
| 404 | — | The session, file or product does not belong to this app. |
| 429 | — | Too many requests; wait for the Retry-After header. |
Widget endpoints
Ready to Build Your AI Chatbot?
Upload your documents, embed the widget, and let customers get instant answers around the clock. Start free, and upgrade when your traffic grows.