Deploy the Chat Widget

This guide walks through deploying the Liya Chat widget on a web page from scratch. The widget loads as a floating chat button and opens a full conversational interface backed by your knowledge base.

Prerequisites

• A Liya Engine account with Liya Chat enabled
• At least one document uploaded to your chat knowledge base
• A JWT token (log in via the dashboard API or use the dashboard directly)

Step 1 — Upload your knowledge base

Your widget will only give useful answers if you've uploaded content first.

In the dashboard, go to Knowledge and upload your help articles, FAQs, or product documentation. Or via API:

# Upload a PDF help article
curl -X POST https://api.liyaengine.ai/dashboard/knowledge/upload \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -F "[email protected]" \
  -F "domain=chat"
 
# Ingest a live URL
curl -X POST https://api.liyaengine.ai/dashboard/knowledge/ingest-url \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://docs.yourproduct.com", "domain": "chat" }'

Supported formats: PDF, DOCX, TXT, JSON, plain text.

Step 2 — Create an embed token

Embed tokens (liya_pub_*) are public-safe credentials scoped to your website origin. They are distinct from your API key and cannot access account settings or non-chat endpoints.

curl -X POST https://api.liyaengine.ai/dashboard/deploy/tokens \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Marketing site",
    "allowed_origins": ["https://yourwebsite.com"],
    "allowed_intents": ["answer_question", "general_chat"],
    "rate_limit_rpm": 60
  }'

allowed_origins — required. Must be full origin URLs including protocol (https://). Trailing slashes are stripped automatically. Requests from any other origin will be rejected.

allowed_intents — valid values: answer_question, general_chat, summarize, clarify, escalate. Defaults to ["answer_question", "general_chat"].

rate_limit_rpm — requests per minute per token. Default: 60. Max: determined by your plan.

The response includes the full token once:

{
  "data": {
    "token": "liya_pub_a1b2c3d4...",
    "token_preview": "liya_pub_a1b2...",
    "allowed_origins": ["https://yourwebsite.com"],
    "allowed_intents": ["answer_question", "general_chat"]
  }
}

Copy the full token — it is not stored and cannot be retrieved again.

Step 3 — Add the script tag

Paste this into your HTML, just before </body>:

<script
  src="https://liyaengine.ai/widget.js"
  data-token="liya_pub_your_token_here"
  data-domain="chat"
  async
></script>

The widget mounts automatically when the script loads. No additional JavaScript, no build step.

Step 4 — Customise the widget

Optional attributes to control appearance and copy:

<script
  src="https://liyaengine.ai/widget.js"
  data-token="liya_pub_your_token_here"
  data-domain="chat"
  data-title="Help & Support"
  data-placeholder="Ask anything about our product..."
  data-position="bottom-right"
  data-theme="dark"
  async
></script>

Content Security Policy (CSP)

If your site uses a Content-Security-Policy header, add these directives:

script-src 'self' https://liyaengine.ai;
connect-src 'self' https://api.liyaengine.ai;
frame-src 'self' https://liyaengine.ai;

The widget does not use eval() or inline scripts beyond what the async loader injects.

CORS

The allowed_origins list on your embed token is enforced server-side. The API will return 403 ORIGIN_NOT_ALLOWED for requests originating from any domain not in that list.

To add a new origin (e.g. a staging environment):

# Create a separate token for staging
curl -X POST https://api.liyaengine.ai/dashboard/deploy/tokens \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Staging",
    "allowed_origins": ["https://staging.yourwebsite.com"],
    "allowed_intents": ["answer_question", "general_chat"]
  }'

Token management

View and revoke tokens from the dashboard under Deploy → Embed Tokens, or via API:

# List all tokens
GET /dashboard/deploy/tokens
 
# Revoke a token
DELETE /dashboard/deploy/tokens/{id}

Revoking a token is immediate — the widget on any page using that token stops working within seconds. Create a replacement token before revoking if you need zero-downtime rotation.

Limits: Maximum 10 active tokens per tenant.

Verifying the widget works

1. Open your page in a browser and look for the chat bubble in the bottom corner
2. Type a question that your uploaded documents should answer
3. Confirm the response includes source citations

If the widget does not appear, check:

• The script tag data-token value matches your embed token exactly
• The page origin matches an entry in allowed_origins
• Liya Chat is enabled on your account (enable_liya_chat: true in your tenant config)

Next steps

• Liya Chat — full API reference for custom integrations
• Building a RAG Pipeline — improve answer quality with more sources
• Sessions and Memory — understand how conversation context is maintained
• Configuration / Persona — customise the assistant's name and tone