{"id":30196358,"url":"https://github.com/merteraslan/chat-widget","last_synced_at":"2026-01-20T17:29:40.991Z","repository":{"id":305972613,"uuid":"1024586839","full_name":"merteraslan/chat-widget","owner":"merteraslan","description":"A modern, lightweight React chat widget that connects seamlessly to your AI backend via webhooks with support for rich interactive messages, forms, articles, and canned responses.","archived":false,"fork":false,"pushed_at":"2025-08-08T03:22:30.000Z","size":220,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-08T05:26:53.034Z","etag":null,"topics":["ai","automation","chat","chatbot","chatwoot","customer-support","javascript","low-code","n8n","npm","react","typescript","webhook","widget","zapier"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/merteraslan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-23T00:18:11.000Z","updated_at":"2025-08-08T03:21:11.000Z","dependencies_parsed_at":"2025-07-23T00:54:29.735Z","dependency_job_id":"7d8a8448-9ee3-4d16-98ff-43f12a5cc91e","html_url":"https://github.com/merteraslan/chat-widget","commit_stats":null,"previous_names":["merteraslan/chat-widget"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/merteraslan/chat-widget","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merteraslan%2Fchat-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merteraslan%2Fchat-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merteraslan%2Fchat-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merteraslan%2Fchat-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/merteraslan","download_url":"https://codeload.github.com/merteraslan/chat-widget/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/merteraslan%2Fchat-widget/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270183606,"owners_count":24541341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","chat","chatbot","chatwoot","customer-support","javascript","low-code","n8n","npm","react","typescript","webhook","widget","zapier"],"created_at":"2025-08-13T05:18:16.818Z","updated_at":"2026-01-20T17:29:40.953Z","avatar_url":"https://github.com/merteraslan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @merteraslan/chat-widget\n\n## Why this widget\n\nBuild customer conversations without getting trapped by third-party chat platforms. This React component connects directly to your own backend, giving you complete control over data, styling, and functionality. You keep ownership of every conversation while getting a production-ready chat interface in minutes.\n\n## Install\n\n```bash\nnpm i @merteraslan/chat-widget\n# or\nyarn add @merteraslan/chat-widget\n```\n\n## How requests are shaped\n\nWhen users send messages, the widget transmits a JSON payload to your configured endpoint:\n\n```json\n{\n  \"prompt\": \"What are your business hours?\",\n  \"session_id\": \"visitor-456\"\n}\n```\n\nYour server responds with either plain text wrapped in an `output` field, or structured content for interactive features. CSRF protection headers are automatically included when you provide a token.\n\n## Props\n\n| Prop | Type | Required | Description |\n|------|------|----------|-------------|\n| `color` | `string` | ❌ | Accent color applied throughout the interface using hex notation. |\n| `agentName` | `string` | ❌ | Display name that appears alongside bot responses. |\n| `webhookUrl` | `string` | ✅ | The HTTP endpoint your backend exposes. The widget POSTs a JSON payload with the user's text and the sessionId. You own the endpoint; return a plain string in the field you configure (default: output). |\n| `openByDefault` | `boolean` | ❌ | Controls initial widget visibility when the page loads. Default: `false`. |\n| `placeholder` | `string` | ❌ | Hint text displayed inside the message input field. Default: `\"Share your thoughts...\"`. |\n| `csrfToken` | `string` | ❌ | Security token transmitted via `X-CSRF-Token` header with each request. |\n| `title` | `React.ReactNode` | ❌ | Content rendered in the chat window header area. Default: `\"Assistant\"`. |\n| `sessionId` | `string` | ❌ | Unique identifier forwarded to your backend for conversation tracking. |\n| `initialMessage` | `string` | ❌ | Opening message from the bot when chat first appears. Default: `\"Hi there! What can I do for you?\"`. |\n| `className` | `string` | ❌ | Custom CSS class applied to the root widget element. |\n\n## Quick Start\n\n```tsx\nimport { ChatWidget } from '@merteraslan/chat-widget';\nimport '@merteraslan/chat-widget/dist/style.css';\n\nexport default function App() {\n  return (\n    \u003cChatWidget\n      webhookUrl=\"/api/conversations\"\n      title=\"Customer Support\"\n      initialMessage=\"Welcome! How can we assist you today?\"\n      sessionId=\"guest-789\"\n      agentName=\"Alex\"\n      color=\"#059669\"\n      placeholder=\"Describe your question...\"\n      csrfToken={window.__CSRF__}\n    /\u003e\n  );\n}\n```\n\n## Response Formats\n\n### Simple Text Response\n\n```json\n{\n  \"output\": \"Our store opens at 9 AM Monday through Friday!\"\n}\n```\n\n### Interactive Content Response\n\n```json\n{\n  \"content\": \"Pick a category:\",\n  \"content_type\": \"canned_response\",\n  \"content_attributes\": {\n    \"responses\": {\n      \"responses\": [\n        { \"id\": \"orders\", \"text\": \"Order status\" },\n        { \"id\": \"returns\", \"text\": \"Returns \u0026 refunds\" }\n      ]\n    }\n  }\n}\n```\n\n## Interactive Messages\n\nBeyond basic text exchanges, the widget renders rich interactive elements that enhance user engagement. Your backend can send structured responses that become clickable buttons, forms, article links, and product showcases.\n\n### Canned Responses / Quick Replies\n\n```json\n{\n  \"content\": \"Which department can help you?\",\n  \"content_type\": \"canned_response\",\n  \"content_attributes\": {\n    \"responses\": {\n      \"responses\": [\n        { \"id\": \"tech\", \"text\": \"Technical Issues\" },\n        { \"id\": \"sales\", \"text\": \"Sales Inquiry\" }\n      ]\n    }\n  }\n}\n```\n\n### Article Links\n\n```json\n{\n  \"content\": \"Browse these helpful guides:\",\n  \"content_type\": \"article\",\n  \"content_attributes\": {\n    \"items\": [\n      {\n        \"title\": \"Getting Started Guide\",\n        \"description\": \"Step-by-step setup instructions\",\n        \"link\": \"https://help.example.com/setup\"\n      }\n    ]\n  }\n}\n```\n\n### Interactive Forms\n\n```json\n{\n  \"content\": \"Complete this information request:\",\n  \"content_type\": \"form\",\n  \"content_attributes\": {\n    \"form\": {\n      \"title\": \"Support Ticket\",\n      \"fields\": [\n        {\n          \"id\": \"issue\",\n          \"type\": \"text\",\n          \"label\": \"Describe the problem\",\n          \"required\": true\n        },\n        {\n          \"id\": \"priority\",\n          \"type\": \"select\",\n          \"label\": \"Urgency level\",\n          \"required\": false\n        }\n      ]\n    }\n  }\n}\n```\n\n### Product/Service Cards\n\n```json\n{\n  \"content\": \"Explore these solutions:\",\n  \"content_type\": \"card\",\n  \"content_attributes\": {\n    \"cards\": {\n      \"cards\": [\n        {\n          \"title\": \"Enterprise Package\",\n          \"description\": \"Full-featured solution for large teams\",\n          \"image\": \"https://cdn.example.com/enterprise.png\",\n          \"price\": \"$99/month\",\n          \"badge\": \"RECOMMENDED\",\n          \"link\": \"https://example.com/enterprise\",\n          \"linkText\": \"Learn More\"\n        }\n      ]\n    }\n  }\n}\n```\n\n## Styling\n\nThe component includes self-contained CSS with scoped class names to avoid conflicts. Customize the appearance by targeting specific selectors with higher specificity or by wrapping the widget in a container with custom CSS.\n\nFor complete design control, the source code is intentionally compact and readable — perfect for forking and modifying to match your exact requirements.\n\n## Development\n\n```bash\nnpm install\nnpm run dev\n```\n\n### CDN usage (no build tools)\n\nOption A: Native ESM with an import map\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/@merteraslan/chat-widget@latest/dist/style.css\" /\u003e\n\n\u003cscript type=\"importmap\"\u003e\n{\n  \"imports\": {\n    \"react\": \"https://esm.sh/react@18\",\n    \"react-dom\": \"https://esm.sh/react-dom@18\",\n    \"react-dom/client\": \"https://esm.sh/react-dom@18/client\",\n    \"react/jsx-runtime\": \"https://esm.sh/react@18/jsx-runtime\"\n  }\n}\n\u003c/script\u003e\n\n\u003cscript type=\"module\"\u003e\n  import * as ReactDOMClient from 'react-dom/client';\n  // Provide ReactDOM global for the widget's mount helper\n  window.ReactDOM = ReactDOMClient;\n\n  import { mountChatWidget } from 'https://unpkg.com/@merteraslan/chat-widget@latest/dist/chat-widget.es.js';\n  mountChatWidget(document.body, { webhookUrl: '/api/chat' });\n\u003c/script\u003e\n```\n\nOption B: UMD + globals\n\n```html\n\u003clink rel=\"stylesheet\" href=\"https://unpkg.com/@merteraslan/chat-widget@latest/dist/style.css\" /\u003e\n\n\u003c!-- React globals --\u003e\n\u003cscript src=\"https://unpkg.com/react@18/umd/react.production.min.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://unpkg.com/react-dom@18/umd/react-dom.production.min.js\"\u003e\u003c/script\u003e\n\n\u003c!-- Widget UMD build exposes window.ChatWidget --\u003e\n\u003cscript src=\"https://unpkg.com/@merteraslan/chat-widget@latest/dist/chat-widget.umd.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const { mountChatWidget } = window.ChatWidget;\n  mountChatWidget(document.body, { webhookUrl: '/api/chat' });\n\u003c/script\u003e\n```\n\nMore examples in `examples/`.\n\n## License\n\nMIT - see [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerteraslan%2Fchat-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmerteraslan%2Fchat-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmerteraslan%2Fchat-widget/lists"}