Overview

Three surfaces work together: the browser widget, public read-only config, and the chat completion API.

• Widget — /chatbot-widget.js on your site; authenticates with your project API key.
• Config — GET /api/chatbot/config — returns enabled flag, welcome text, theme (colors, layout), quick links metadata (used by the widget after load).
• Chat — POST /api/chatbot/chat — sends the user message + optional history and context (e.g. page URL/title) for grounded replies.
• Project settings — Edited in-app under Project → Chatbot; stored on the project as chatbotAgent (also exposed via authenticated GET/PATCH /api/projects/:id/chatbot for the dashboard).

Prerequisites

1. PRZIO project — Create or open a project; copy the project ID.
2. API key — Generate a project API key (same key family as other PRZIO APIs). The widget and chat endpoint require X-API-Key or Authorization: Bearer ….
3. AI provider — The host must have OPENAI_API_KEY and/or OPENROUTER_API_KEY configured (environment or admin/project AI settings). Without this, chat returns 503.
4. Enable the chatbot — In project chatbot settings, turn the agent on. If disabled, POST /api/chatbot/chat returns 403.

Embed the widget

Add the script near the end of your HTML (e.g. before </body>). Replace the placeholder host with your PRZIO app URL (e.g. https://app.przio.com).

<script
  src="https://app.przio.com/chatbot-widget.js"
  data-base-url="https://app.przio.com"
  data-project-id="YOUR_PROJECT_ID"
  data-api-key="YOUR_API_KEY"
  async
></script>

Alternative: PrzioChatbotConfig

Set global config before the script runs if you prefer not to use data attributes:

window.PrzioChatbotConfig = {
  baseUrl: 'https://app.przio.com',
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_API_KEY'
};

Open programmatically

After load, the widget exposes a small API:

if (window.PrzioChatbot && window.PrzioChatbot.open) {
  window.PrzioChatbot.open();
}

Runtime APIs

Base URL = your data-base-url (no trailing slash). All requests support CORS for browser use.

GET /api/chatbot/config

Auth: header X-API-Key or Authorization: Bearer <api-key>.

Returns JSON used by the widget: whether the bot is enabled, welcome message, theme (primary color, bubble mode, avatars, header text, panel min/max height, custom CSS fields), and quick-link settings when configured.

POST /api/chatbot/chat

Auth: same as config.

Body (JSON):

• message (string, required) — user’s latest message.
• messages (array, optional) — prior turns for context; items with role and content (recent history is truncated server-side).
• context (object, optional) — e.g. { "url": "https://yoursite.com/pricing", "title": "Pricing" } for page-aware answers.

The server builds a system prompt from your project’s description, chatbotAgent fields (context, business info, knowledge doc, important URLs, suggested Q&A), and optional system prompt override. It appends page context when provided.

Dashboard settings (chatbotAgent)

Configure these in Project → Chatbot. They feed the AI system prompt and the widget appearance.

Domain allowlist

If allowedDomains is non-empty, the chat API validates context.url (when provided). The visitor’s page hostname must match an allowed host (localhost variants are treated as allowed for development).

If the URL is missing, invalid, or not on the list, the API responds with 403 and a message to add the site in Chatbot settings.

Common HTTP responses

Integration checklist

• Project created; chatbot enabled in dashboard.
• API key generated; snippet uses correct data-base-url, data-project-id, data-api-key.
• AI keys configured for the PRZIO deployment.
• Allowed domains configured for production (or cleared for staging).
• Widget loads; messages return assistant replies (test on a path that matches domain rules).