@ibti-tech/chatbot 0.6.5 → 0.8.1

package/README.md

@@ -1,616 +1,136 @@
 # @ibti-tech/chatbot
 
-A modern and customizable React chatbot component developed by IBTI Soluções em TI. This package provides an intelligent conversational interface that can be easily integrated into any React application.
+React chatbot widget by IBTI. Use it in React apps or embed via a single script in any HTML/WordPress/PHP site.
 
-## 📋 Features
+## Features
 
-- 🎨 **Customizable themes**: Support for light and dark themes
-- 🌍 **Internationalization**: Support for Brazilian Portuguese (pt-BR) and English (en)
-- 💬 **Modern interface**: Responsive and intuitive design
-- ⚡ **Optimized performance**: Built with ESBuild for maximum performance
-- 🔌 **Easy integration**: Simple React component to use
-- 📱 **Responsive**: Works perfectly on desktop and mobile
-- 📍 **Flexible positioning**: Precise horizontal positioning with predefined values or custom CSS units (px, %, rem, calc, etc.)
+- Light/dark theme, pt-BR and en
+- Responsive, configurable position (top/bottom, left/right, custom CSS)
+- React component or script embed (no React required on the host page)
 
-## 📦 Installation
-
-Install the package using yarn or npm:
+## Installation
 
 ```bash
-# Using yarn
 yarn add @ibti-tech/chatbot
-
-# Using npm
+# or
 npm install @ibti-tech/chatbot
 ```
 
-## 🚀 Basic Usage
-
-### Import
-
-```jsx
-import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
-```
+**Peer dependencies:** `react` ^18.2.0, `react-dom` ^18.2.0, `lodash` ^4.17.21, `nookies` ^2.5.2
 
-### Minimal Example
+## Usage (React)
 
 ```jsx
-import React from 'react'
-import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+import { ChatbotProvider, ChatbotBar, useChatbot } from '@ibti-tech/chatbot'
 
 function App() {
   return (
     <ChatbotProvider
       locale="pt-BR"
       apiURL="https://api.example.com"
+      publicHash="YOUR_PUBLIC_HASH"
       theme="dark"
     >
       <ChatbotBar />
     </ChatbotProvider>
   )
 }
-
-export default App
-```
-
-## 📚 Available Components
-
-### `ChatbotProvider`
-
-Context component that provides chatbot configuration and state to child components.
-
-#### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `locale` | `'pt-BR' \| 'en'` | ✅ | Chatbot interface language |
-| `apiURL` | `string` | ✅ | Chatbot backend API URL |
-| `theme` | `'light' \| 'dark'` | ✅ | Chatbot visual theme |
-| `isOpen` | `boolean` | ❌ | Controls if the chatbot is initially open. Default: `false` |
-| `texts` | `ChatbotTypes.Texts` | ❌ | Custom texts to override default translations. See [Custom Texts](#custom-texts) section |
-| `children` | `ReactNode` | ❌ | Child components to be rendered |
-
-### `ChatbotBar`
-
-Main component that displays the chatbot bar with toggle button and conversation interface.
-
-#### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
-| `horizontalPosition` | `'left' \| 'right'` | ❌ | Horizontal position of the chatbot bar container. Default: `'right'` |
-| `deviceHorizontalPosition` | `'left' \| 'right' \| 'center' \| string` | ❌ | Horizontal position of the ChatbotDevice on desktop. Can be a predefined value ('left', 'right', 'center') or a custom value with any CSS unit (e.g., '20px', '10%', '2rem', 'calc(100% - 200px)'). When using a custom value, it will be applied as the 'left' property. If not provided, the device will use the parent container's positioning. Only affects desktop view. |
-| `zIndex` | `number` | ❌ | Custom z-index value. If not provided, uses theme.zIndex.modals. Useful when you need the chatbot to appear above specific elements like headers |
-| `topOffset` | `string \| number` | ❌ | Offset from the top when verticalPosition is 'top'. Can be a number (in pixels) or a string (e.g., '100px', '10rem'). Useful to position the chatbot below a fixed header |
-| `aboveHeader` | `boolean` | ❌ | Convenient prop to position the chatbot above header elements. When true, sets z-index to 9999 and allows topOffset configuration. Default: `false` |
-| `pushContentDown` | `boolean` | ❌ | When true and verticalPosition is 'top', the chatbot will push content down instead of overlaying it. The chatbot will occupy space in the document flow. When false, the chatbot will be fixed and overlay the content. Default: `false` |
-
-#### Examples
-
-**Positioning above header elements:**
-
-```jsx
-// Option 1: Using aboveHeader prop (recommended)
-<ChatbotBar 
-  verticalPosition="top"
-  aboveHeader={true}
-  topOffset={120} // Adjust based on your header height
-/>
-
-// Option 2: Using custom zIndex
-<ChatbotBar 
-  verticalPosition="top"
-  zIndex={9999}
-  topOffset="120px"
-/>
-
-// Option 3: Using CSS units for topOffset
-<ChatbotBar 
-  verticalPosition="top"
-  aboveHeader={true}
-  topOffset="8rem" // Using rem units for better scalability
-/>
-
-// Option 4: Push content down instead of overlaying (only works with verticalPosition="top")
-// When pushContentDown is true, the chatbot occupies full width and pushes header content down
-<ChatbotBar 
-  verticalPosition="top"
-  pushContentDown={true}
-/>
-
-// ✅ CORRECT - Component at the beginning
-function App() {
-  return (
-    <ChatbotProvider ...>
-      <ChatbotBar verticalPosition="top" pushContentDown={true} />
-      <header>...</header>
-      <main>...</main>
-    </ChatbotProvider>
-  )
-}
-
-// ❌ WRONG - Component at the end (will appear at bottom even with pushContentDown)
-function App() {
-  return (
-    <ChatbotProvider ...>
-      <header>...</header>
-      <main>...</main>
-      <ChatbotBar verticalPosition="top" pushContentDown={true} />
-    </ChatbotProvider>
-  )
-}
-```
-
-**Note:** The component maintains full responsiveness even with custom positioning. The `topOffset` prop accepts both numbers (pixels) and strings (any valid CSS unit). The `pushContentDown` prop only works when `verticalPosition` is `'top'` and makes the chatbot reserve space in the document flow instead of overlaying content. When `pushContentDown` is enabled, the chatbot will occupy the full width of the page (aligned with the host site's container) and push all content below it down, making it perfect for top-of-page integration.
-
-**⚠️ CRITICAL:** When using `pushContentDown={true}`, you **MUST** render the `ChatbotBar` component at the **beginning** of your DOM structure (before your header and other content) for it to appear at the top of the page. This is because `pushContentDown` uses `position: relative`, which means the component appears where it is in the DOM flow. If you render it at the end of the DOM, it will appear at the bottom of the page even with `pushContentDown={true}`.
-
-**Precise horizontal positioning on desktop:**
-
-```jsx
-// Using predefined values
-<ChatbotBar 
-  deviceHorizontalPosition="left"   // Aligns to left
-/>
-<ChatbotBar 
-  deviceHorizontalPosition="right" // Aligns to right (default behavior)
-/>
-<ChatbotBar 
-  deviceHorizontalPosition="center" // Centers the device
-/>
-
-// Using custom values with any CSS unit
-<ChatbotBar 
-  deviceHorizontalPosition="20px"  // 20 pixels from left
-/>
-<ChatbotBar 
-  deviceHorizontalPosition="10%"   // 10% from left edge
-/>
-<ChatbotBar 
-  deviceHorizontalPosition="2rem"  // 2rem from left edge
-/>
-<ChatbotBar 
-  deviceHorizontalPosition="calc(100% - 200px)" // 200px from right edge
-/>
-
-// Combining with other positioning props
-<ChatbotBar 
-  verticalPosition="bottom"
-  horizontalPosition="right"        // Bar container alignment
-  deviceHorizontalPosition="50px"  // Device positioned 50px from left
-/>
-```
-
-**Important notes about `deviceHorizontalPosition`:**
-- Only affects desktop/tablet view (mobile always uses full width)
-- Custom values are applied as the `left` CSS property
-- Predefined values (`'left'`, `'right'`, `'center'`) use margin-based alignment
-- When using custom values, the device maintains its fixed width to prevent button shrinking
-- This prop provides precise control over the ChatbotDevice position, independent of the bar container alignment
-
-### `ChatbotDevice`
-
-Alternative component that can be used to display the chatbot on different devices or layouts.
-
-#### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
-| `pushContentDown` | `boolean` | ❌ | When true and verticalPosition is 'top', the chatbot will push content down instead of overlaying it. Default: `false` |
-| `horizontalPosition` | `'left' \| 'right' \| 'center' \| string` | ❌ | Horizontal position on desktop. Can be a predefined value ('left', 'right', 'center') or a custom value with any CSS unit (e.g., '20px', '10%', '2rem', 'calc(100% - 200px)'). When using a custom value, it will be applied as the 'left' property. Default: `undefined` (uses parent container positioning). Only affects desktop view. |
-
-## 🎨 Themes
-
-The chatbot supports two themes:
-
-- **`light`**: Light theme with bright colors
-- **`dark`**: Dark theme with dark colors
-
-```jsx
-<ChatbotProvider theme="dark" ...>
-  <ChatbotBar />
-</ChatbotProvider>
-```
-
-## 🌍 Localization
-
-The chatbot supports the following languages:
-
-- **`pt-BR`**: Brazilian Portuguese
-- **`en`**: English
-
-```jsx
-<ChatbotProvider locale="pt-BR" ...>
-  <ChatbotBar />
-</ChatbotProvider>
-```
-
-### Custom Texts
-
-You can customize all texts in the chatbot interface by passing a `texts` prop to `ChatbotProvider`. This allows you to override default translations for any locale.
-
-```jsx
-<ChatbotProvider
-  locale="pt-BR"
-  apiURL="https://api.example.com"
-  theme="dark"
-  texts={{
-    'pt-BR': {
-      CHATBOT_NAME: 'Meu Assistente',
-      INPUT_PLACEHOLDER: 'Digite sua mensagem...',
-      CHATBOT_BAR: {
-        OPEN: 'Abrir chat',
-        CLOSE: 'Fechar chat',
-      },
-      CHAT_FEEDBACK: {
-        TITLE: 'Avalie esta resposta',
-        DESCRIPTION: 'Sua opinião nos ajuda a melhorar',
-        MESSAGE_FIELD: 'Mensagem (opcional)',
-        SUBMIT_BUTTON: 'Enviar',
-        CLOSE_BUTTON: 'Fechar',
-        RATE: 'Avaliar',
-      },
-      SUGGESTED_QUESTIONS: {
-        TITLE: 'Perguntas sugeridas',
-        LOADING: 'Carregando...',
-      },
-      STATUS: {
-        ONLINE: 'Online',
-        LOADING: 'Carregando',
-        WRITING: 'Digitando...',
-        UNAVAILABLE: 'Indisponível',
-        INACTIVE: 'Inativo',
-      },
-      ERRORS: {
-        UNKNOWN: 'Erro desconhecido',
-      },
-      MESSAGE_ACTIONS: {
-        COPY: 'Copiar',
-        SHARE: 'Compartilhar',
-        RESEND: 'Reenviar',
-      },
-      USER_LABEL: 'Você',
-      WRITING_MESSAGE: 'Digitando...',
-    },
-    'en': {
-      CHATBOT_NAME: 'My Assistant',
-      // ... other custom texts
-    },
-  }}
->
-  <ChatbotBar />
-</ChatbotProvider>
-```
-
-**Available text keys:**
-- `CHATBOT_NAME`: Name displayed in the chatbot header
-- `INPUT_PLACEHOLDER`: Placeholder text for the input field
-- `CHATBOT_BAR.OPEN`: Text for opening the chatbot
-- `CHATBOT_BAR.CLOSE`: Text for closing the chatbot
-- `CHAT_FEEDBACK.*`: All feedback form texts
-- `SUGGESTED_QUESTIONS.*`: Suggested questions section texts
-- `STATUS.*`: Status indicator texts
-- `ERRORS.*`: Error message texts
-- `MESSAGE_ACTIONS.*`: Message action button texts
-- `USER_LABEL`: Label for user messages
-- `WRITING_MESSAGE`: Text shown when the bot is typing
-
-## 📝 Complete Example
-
-```jsx
-import React from 'react'
-import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
-
-function MyApp() {
-  return (
-    <div className="app">
-      <h1>My Application</h1>
-      
-      {/* Other components of your application */}
-      
-      <ChatbotProvider
-        locale="pt-BR"
-        apiURL={process.env.REACT_APP_CHATBOT_API_URL || "http://localhost:6061"}
-        theme="dark"
-        isOpen={false}
-      >
-        <ChatbotBar 
-          verticalPosition="bottom"
-          horizontalPosition="right"
-          deviceHorizontalPosition="right"
-        />
-      </ChatbotProvider>
-    </div>
-  )
-}
-
-export default MyApp
-```
-
-## 🎛️ Advanced Configuration
-
-### Positioning the Chatbot
-
-You can control the position of the chatbot using the `ChatbotBar` component props:
-
-```jsx
-// Bottom right (default)
-<ChatbotBar />
-
-// Top right
-<ChatbotBar verticalPosition="top" />
-
-// Bottom left (bar container aligned left)
-<ChatbotBar horizontalPosition="left" />
-
-// Top left (bar container aligned left)
-<ChatbotBar 
-  verticalPosition="top" 
-  horizontalPosition="left" 
-/>
-
-// Precise horizontal positioning on desktop
-<ChatbotBar 
-  deviceHorizontalPosition="center"  // Centers the device
-/>
-
-<ChatbotBar 
-  deviceHorizontalPosition="50px"   // 50px from left edge
-/>
-
-<ChatbotBar 
-  deviceHorizontalPosition="calc(100% - 250px)"  // 250px from right edge
-/>
-
-// Combining bar container and device positioning
-<ChatbotBar 
-  horizontalPosition="right"         // Bar container on right
-  deviceHorizontalPosition="20px"   // Device 20px from left (within container)
-/>
-```
-
-**Understanding the positioning props:**
-- `horizontalPosition`: Controls the alignment of the bar container (`'left'` or `'right'`)
-- `deviceHorizontalPosition`: Provides precise control over the ChatbotDevice position on desktop:
-  - Predefined values: `'left'`, `'right'`, `'center'` (use margin-based alignment)
-  - Custom values: Any CSS unit string (e.g., `'20px'`, `'10%'`, `'calc(100% - 200px)'`) applied as the `left` property
-  - Only affects desktop/tablet view; mobile always uses full width
-
-### Controlling Initial State
-
-Use the `isOpen` prop to control whether the chatbot starts open or closed:
-
-```jsx
-<ChatbotProvider
-  locale="pt-BR"
-  apiURL="https://api.example.com"
-  theme="dark"
-  isOpen={true}  // Chatbot starts open
->
-  <ChatbotBar />
-</ChatbotProvider>
 ```
 
-## 🔧 Requirements
+All public types (e.g. `ChatbotTypes`, `ChatbotBarProps`) and parameters are documented with JSDoc in English in the source—your IDE will show parameter names, types, and descriptions on hover.
 
-### Peer Dependencies
+### Main props
 
-This package requires the following dependencies that must be installed in your project:
+**ChatbotProvider**
 
-- `react`: `^18.2.0`
-- `react-dom`: `^18.2.0`
-- `lodash`: `^4.17.21`
-- `nookies`: `^2.5.2`
+| Prop       | Type     | Required | Description                    |
+|-----------|----------|----------|--------------------------------|
+| `locale`  | `'pt-BR' \| 'en'` | ✅ | Interface language             |
+| `apiURL`  | `string` | ✅       | Backend API base URL           |
+| `publicHash` | `string` | ✅    | Chatbot public hash (from admin) |
+| `theme`   | `'light' \| 'dark'` | ✅ | Theme                          |
+| `isOpen`  | `boolean` | ❌      | Initial open state. Default: `false` |
+| `texts`   | `object`  | ❌      | Override labels per locale     |
 
-Make sure these dependencies are installed:
+**ChatbotBar**
 
-```bash
-yarn add react react-dom lodash nookies
-# or
-npm install react react-dom lodash nookies
-```
+| Prop                      | Type     | Default        | Description                          |
+|---------------------------|----------|----------------|--------------------------------------|
+| `verticalPosition`        | `'top' \| 'bottom'` | `'bottom'` | Vertical placement                  |
+| `horizontalPosition`     | `'left' \| 'right'` | `'right'` | Bar alignment                       |
+| `deviceHorizontalPosition`| `'left' \| 'right' \| 'center' \| string` | — | Device position on desktop (or e.g. `'20px'`, `'calc(100% - 200px)'`) |
+| `pushContentDown`         | `boolean` | `false`  | If `true` and `verticalPosition="top"`, widget pushes content down instead of overlaying |
+| `zIndex`, `topOffset`, `aboveHeader` | — | — | Optional layout/stacking           |
 
-## 📡 Backend API
+When using `pushContentDown={true}` with `verticalPosition="top"`, render `ChatbotBar` **before** your header/main content so it appears at the top.
 
-The chatbot expects the backend API to be configured and accessible at the provided URL. The API must implement the following endpoints:
+### Types (`ChatbotTypes`)
 
-### Required Endpoints
+Import: `import type { ChatbotTypes } from '@ibti-tech/chatbot'`
 
-#### 1. `GET /chat/welcome?locale={locale}`
+| Type | Description |
+|------|-------------|
+| `Theme` | `'light' \| 'dark'` |
+| `Locale` | `'pt-BR' \| 'en'` |
+| `CustomColors` | `{ primaryColor?, headerBackground?, userBalloonColor? }` (hex or rgb) |
+| `ChatMessage` | `{ id, timestamp, role, content, error? }` — one message in the thread |
+| `ChatContextItem` | `{ role, content }` — minimal shape for API context |
+| `Status` | `'writing' \| 'loading' \| 'online' \| 'unavailable'` |
+| `InitializationStatus` | `'loading' \| 'domain_not_allowed' \| 'error' \| 'ready'` |
+| `ChatbotPublicResponse` | Response of GET `/chatbots/public/:hash` (id, name, domain, etc.) |
+| `CustomTexts` / `Texts` | Override UI strings per locale (see JSDoc in `types/index.ts`) |
 
-**Purpose**: Retrieves the welcome message and checks API health/availability.
+## Embed (no React)
 
-**Query Parameters**:
-- `locale` (required): The locale code (`'pt-BR'` or `'en'`)
-
-**Response**:
-```json
-{
-  "welcomeMessage": "Hello! How can I help you today?"
-}
-```
+For static HTML, WordPress, PHP, or any site without React, load the script from the CDN:
 
-**Status Codes**:
-- `200 OK`: API is available and welcome message is returned
-- `4xx/5xx`: API is considered unavailable
-
-**Notes**:
-- This endpoint is used for health checks (via `HEAD` or `GET` requests)
-- The chatbot uses this to determine connection status
-- Should return a welcome message appropriate for the specified locale
-
----
-
-#### 2. `POST /chat/completion?locale={locale}`
-
-**Purpose**: Sends a chat message and receives a streaming response from the AI assistant.
-
-**Query Parameters**:
-- `locale` (required): The locale code (`'pt-BR'` or `'en'`)
-
-**Request Body**:
-```json
-{
-  "context": [
-    {
-      "role": "user",
-      "content": "What is artificial intelligence?"
-    },
-    {
-      "role": "assistant",
-      "content": "Artificial intelligence (AI) is..."
-    },
-    {
-      "role": "user",
-      "content": "Tell me more about machine learning"
-    }
-  ]
-}
+```html
+<script>
+  window.IBTIChatbotConfig = {
+    apiURL: 'https://api-chatbot.ibti.tech',
+    publicHash: 'YOUR_PUBLIC_HASH',
+    locale: 'pt-BR',      // optional: 'pt-BR' | 'en'
+    theme: 'light',       // optional: 'light' | 'dark'
+    position: 'bottom-right'  // optional: bottom-right | bottom-left | top-right | top-left
+  };
+</script>
+<script src="https://cdn.ibti.tech/ibti-chatbot-embed.js" async></script>
 ```
 
-**Request Body Schema**:
-- `context` (required, array): Array of chat messages representing the conversation history
-  - Each item must have:
-    - `role` (required, string): Either `"user"` or `"assistant"`
-    - `content` (required, string): The message content
-  - The array must not be empty
-  - The last message should typically be from the `"user"` role
-
-**Response**:
-- **Content-Type**: `text/event-stream`
-- **Format**: Server-Sent Events (SSE) stream
-- **Body**: Plain text chunks that are concatenated to form the complete response
+Or configure via data attributes on the script tag:
 
-**Response Headers**:
+```html
+<script
+  src="https://cdn.ibti.tech/ibti-chatbot-embed.js"
+  data-api-url="https://api-chatbot.ibti.tech"
+  data-public-hash="YOUR_PUBLIC_HASH"
+  data-locale="pt-BR"
+  data-theme="light"
+  data-position="bottom-right"
+  async
+></script>
 ```
-Content-Type: text/event-stream
-Cache-Control: no-cache
-Connection: keep-alive
-```
-
-**Status Codes**:
-- `200 OK`: Stream started successfully
-- `429 Too Many Requests`: Rate limit exceeded (should send error message via stream before closing)
-- `4xx/5xx`: Error occurred
-
-**Streaming Behavior**:
-- The response is sent as a continuous stream of text chunks
-- Each chunk is immediately displayed to the user as it arrives
-- The stream ends when the complete response is sent
-- The chatbot accumulates all chunks to form the final message
-
-**Error Handling**:
-- For `429` errors, the API should send a friendly error message via the stream before closing:
-  ```json
-  {"error": "Sorry, too many requests were made. Please try again in a few moments. 😊"}
-  ```
-- For other errors, the stream should be closed and an appropriate HTTP status code returned
-
-**Example Flow**:
-1. Frontend sends POST request with conversation context
-2. Backend starts streaming response chunks
-3. Frontend receives chunks and displays them incrementally
-4. Stream completes when response is finished
-5. Frontend saves the complete message to conversation history
-
----
-
-#### 3. `POST /chat/feedback`
-
-**Purpose**: Submits user feedback about a chatbot response (rating and optional message).
-
-**Request Body**:
-```json
-{
-  "rating_score": 5,
-  "chat_context": [
-    {
-      "role": "user",
-      "content": "What is AI?"
-    },
-    {
-      "role": "assistant",
-      "content": "Artificial intelligence is..."
-    }
-  ],
-  "locale": "pt-BR",
-  "message": "Very helpful response!"
-}
-```
-
-**Request Body Schema**:
-- `rating_score` (required, number): Rating from 1 to 5 (inclusive)
-  - Valid values: `1`, `2`, `3`, `4`, `5`
-- `chat_context` (required, array): The conversation context that was rated
-  - Same structure as in `/chat/completion` endpoint
-  - Must not be empty
-- `locale` (required, string): The locale code (`'pt-BR'` or `'en'`)
-- `message` (optional, string): Optional feedback message from the user
-
-**Response**:
-- **Status Code**: `200 OK` or `201 Created` (implementation dependent)
-- **Body**: Typically empty or a success confirmation
-
-**Status Codes**:
-- `200 OK` / `201 Created`: Feedback submitted successfully
-- `400 Bad Request`: Invalid request body (invalid rating, missing fields, etc.)
-- `4xx/5xx`: Other errors
-
-**Notes**:
-- This endpoint is called when a user rates a chatbot response
-- The feedback is typically stored for analytics and improvement purposes
-- The endpoint should handle the request asynchronously if possible to avoid blocking the UI
-
----
-
-### API Requirements Summary
-
-| Endpoint | Method | Purpose | Streaming | Required |
-|----------|--------|---------|-----------|----------|
-| `/chat/welcome` | `GET` | Health check & welcome message | ❌ | ✅ |
-| `/chat/completion` | `POST` | Send message & receive response | ✅ | ✅ |
-| `/chat/feedback` | `POST` | Submit user feedback | ❌ | ✅ |
-
-### Implementation Notes
-
-1. **CORS**: The API must allow cross-origin requests from the frontend domain
-2. **Locale Support**: All endpoints should respect the `locale` parameter and return appropriate content
-3. **Error Handling**: Provide clear error messages in the appropriate locale
-4. **Streaming**: The `/chat/completion` endpoint must support Server-Sent Events (SSE) for real-time response streaming
-5. **Rate Limiting**: Consider implementing rate limiting and return `429` status when exceeded
-6. **Content-Type**: 
-   - Use `application/json` for JSON endpoints
-   - Use `text/event-stream` for streaming endpoints
-
-### Example API Base URL
-
-```jsx
-<ChatbotProvider
-  apiURL="https://api.example.com"  // Base URL without trailing slash
-  // ...
-/>
-```
-
-The chatbot will automatically append the endpoint paths (e.g., `/chat/welcome`, `/chat/completion`, `/chat/feedback`) to this base URL.
 
-## 🐛 Issues and Support
+## Backend API
 
-If you encounter any issues or have questions:
+The API base URL (e.g. `https://api.example.com`) must expose:
 
-1. Check the [complete documentation](https://github.com/ibti-solutions/ibti-chatbot)
-2. Open an [issue on GitHub](https://github.com/ibti-solutions/ibti-chatbot/issues)
-3. Contact the IBTI team
+| Endpoint           | Method | Purpose                    | Streaming |
+|--------------------|--------|----------------------------|-----------|
+| `/chatbots/public/:hash` | GET  | Get chatbot config (domain, etc.) | No  |
+| `/chat/welcome`    | GET    | Welcome message / health   | No  |
+| `/chat/completion` | POST   | Send message, stream reply | Yes (SSE) |
+| `/chat/feedback`   | POST   | Submit rating + optional message | No  |
 
-## 📄 License
+Query params used: `locale`, `hash`, `visitorId`. The API should validate `Origin`/`Referer` against the chatbot’s configured domain. CORS must allow the frontend origin.
 
-ISC
+## Support
 
-## 👥 Author
+- [Documentation](https://github.com/ibti-solutions/ibti-chatbot)
+- [Issues](https://github.com/ibti-solutions/ibti-chatbot/issues)
 
-IBTI Soluções em TI
+Development and contribution: see [DEV_NOTES.md](./DEV_NOTES.md).
 
----
+## License
 
-For more information about development and contribution, see the [DEV_NOTES.md](./DEV_NOTES.md) file.
+ISC · IBTI Soluções em TI