Widget Chat API

If you'd rather build your own interface (mobile app, custom UI) instead of the ready-made widget.js, you can call the HTTP API the widget uses directly.

Base URL: https://semagent.ai

Authentication

Every request requires the X-Tenant-Id header — its value is your tenant slug or tenant ID (panel → Widget → Setup). This API is designed to be called from the browser; it carries no secret key and reaches only widget-scoped endpoints.

POST /api/chat/widget

Sends a customer message and returns the assistant's answer. Don't send conversation_id on the first call — it's generated in the response; send the same value back on subsequent messages.

curl -X POST https://semagent.ai/api/chat/widget \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: your-slug" \
  -d '{
    "message": "When will my order arrive?",
    "session_id": "visitor-123",
    "conversation_id": null,
    "type": "rag"
  }'

const res = await fetch("https://semagent.ai/api/chat/widget", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Tenant-Id": "your-slug",
  },
  body: JSON.stringify({
    message: "When will my order arrive?",
    session_id: "visitor-123",
    conversation_id: null,
    type: "rag",
  }),
});
const data = await res.json();

import httpx

r = httpx.post(
    "https://semagent.ai/api/chat/widget",
    headers={"X-Tenant-Id": "your-slug"},
    json={
        "message": "When will my order arrive?",
        "session_id": "visitor-123",
        "type": "rag",
    },
)
data = r.json()

Request body

Response 200 OK

{
  "response": "Orders are delivered in 1-3 business days.",
  "conversation_id": "c7a1…",
  "widget_type": "rag",
  "rag_active": true,
  "ecommerce_active": false
}

GET /api/chat/welcome

Returns the tenant's welcome message — shown when the widget opens. Only the X-Tenant-Id header is required.

GET /api/chat/widget/messages/{conversation_id}

Returns a conversation's message history (to restore the chat when the page reloads).

GET /api/chat/widget-settings

Returns widget behavior settings: whether the pre-chat form is on (widget_prechat_enabled), which fields are requested (widget_prechat_fields), the client rate limit (widget_rate_limit).

POST /api/chat/widget/csat

Sends a satisfaction score at the end of a conversation:

{ "conversation_id": "c7a1…", "score": 5, "feedback": "Very helpful" }

Error codes