# Paymob Chatbot SDK Alpha Embed the Paymob AI assistant into any website with a single script tag. The SDK renders a floating chat button in the bottom-right corner of your page and opens a fully-featured AI chat popup powered by Paymob. --- ## Table of Contents - [Installation](#installation) - [Quick Start](#quick-start) - [Configuration Options](#configuration-options) - [The auth Object](#the-auth-object) - [API Reference](#api-reference) - [Usage Examples](#usage-examples) - [Browser Support](#browser-support) --- ## Installation ### CDN (recommended) Add the script tag before the closing `` tag of your HTML page: ```html ``` ### npm ```bash npm install paymob-chatbot-alpha ``` ```js import { Chatbot } from 'paymob-chatbot-alpha'; ``` --- ## Quick Start ```html My Store ``` A floating chat button will appear in the bottom-right corner. Clicking it opens the Paymob AI assistant. The chatbot will display a loading screen until the auth handshake completes automatically. --- ## Configuration Options | Option | Type | Required | Default | Description | |---|---|---|---|---| | `auth` | `object` | ✅ Yes | — | Authentication object. Must contain exactly `token`, `platform`, `region`, and `user_type` — all strings. See [The auth Object](#the-auth-object) for details. | | `showToggle` | `boolean` | No | `true` | Show or hide the floating chat button. Set to `false` to control the popup entirely via `open()` / `close()`. | --- ## The auth Object The `auth` parameter is **required** and must be a plain object containing exactly these four string keys: | Key | Type | Description | |---|---|---| | `token` | `string` | Your merchant authentication token issued by Paymob. | | `platform` | `string` | The platform the SDK is running on. Allowed values: `"merchant-dashboard"`, `"merchant-app"`, `"sales-app"`. | | `region` | `string` | The merchant's region. Allowed values: `"egypt"`, `"uae"`, `"oman"`, `"ksa"`, `"glb"`. | | `user_type` | `string` | The type of user initiating the session. Allowed values: `"merchant"`, `"sales"`. | ```js auth: { token: 'your_auth_token', platform: 'merchant-dashboard', region: 'egypt', // 'egypt' | 'uae' | 'oman' | 'ksa' | 'glb' user_type: 'merchant', } ``` **All four keys are required.** If any key is missing, has the wrong type, is an empty string, or if the object contains extra keys, the SDK will **not render** and will log a descriptive error to the browser console instead. ### Validation errors The SDK validates the `auth` object at construction time. Open your browser's developer console to see the exact issue: ``` [PaymobChatbot] auth.token is required but missing. [PaymobChatbot] auth.platform must be a string, got number. [PaymobChatbot] auth.region must not be an empty string. [PaymobChatbot] auth contains unexpected key "userId". Allowed keys: token, platform, region, user_type. ``` --- ## API Reference ### `new PaymobChatbot(options)` Creates and mounts the chat widget on the page. The widget is appended to `` automatically. ```js const chat = new window.PaymobChatbot({ auth: { token: 'your_auth_token', platform: 'merchant-dashboard', region: 'egypt', user_type: 'merchant', }, }); ``` --- ### `chat.open()` Opens the chat popup programmatically. ```js chat.open(); ``` --- ### `chat.close()` Closes the chat popup programmatically. ```js chat.close(); ``` --- ### `chat.destroy()` Completely removes the widget (button + popup) from the DOM and cleans up all injected styles. Useful for single-page applications when navigating away. ```js chat.destroy(); ``` --- ## Usage Examples ### Default — floating button + popup ```js const chat = new window.PaymobChatbot({ auth: { token: 'your_auth_token', platform: 'merchant-dashboard', region: 'egypt', user_type: 'merchant', }, }); ``` --- ### Hide the toggle button — programmatic control only Use this when you want to trigger the chat from your own button or UI element. ```html ``` --- ### Open the chat automatically on page load ```js const chat = new window.PaymobChatbot({ auth: { token: 'your_auth_token', platform: 'merchant-dashboard', region: 'egypt', user_type: 'merchant', }, }); // Open after a short delay setTimeout(() => { chat.open(); }, 3000); ``` --- ### React / Next.js integration ```jsx import { useEffect, useRef } from 'react'; import { Chatbot } from 'paymob-chatbot-alpha'; export function ChatWidget({ authToken }) { const chatRef = useRef(null); useEffect(() => { chatRef.current = new Chatbot({ auth: { token: authToken, platform: 'merchant-dashboard', region: 'egypt', user_type: 'merchant', }, }); // Cleanup on unmount return () => { chatRef.current?.destroy(); }; }, []); return null; } ``` --- ### Vue.js integration ```js import { Chatbot } from 'paymob-chatbot-alpha'; export default { props: ['authToken'], mounted() { this.chat = new Chatbot({ auth: { token: this.authToken, platform: 'merchant-dashboard', region: 'egypt', user_type: 'merchant', }, }); }, beforeUnmount() { this.chat?.destroy(); }, }; ``` --- ## Browser Support | Browser | Minimum Version | |---|---| | Chrome | 80+ | | Firefox | 75+ | | Safari | 13+ | | Edge | 80+ | --- ## License MIT © [Paymob](https://paymob.com)