{"id":23828694,"url":"https://github.com/papercups-io/chat-widget","last_synced_at":"2025-04-04T14:10:10.284Z","repository":{"id":46259513,"uuid":"279915322","full_name":"papercups-io/chat-widget","owner":"papercups-io","description":"Papercups chat widget","archived":false,"fork":false,"pushed_at":"2021-11-03T18:18:18.000Z","size":1818,"stargazers_count":257,"open_issues_count":25,"forks_count":94,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-28T13:09:29.869Z","etag":null,"topics":["chat","chat-widget","react"],"latest_commit_sha":null,"homepage":"https://app.papercups.io/demo","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/papercups-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-15T16:07:27.000Z","updated_at":"2025-03-17T08:52:02.000Z","dependencies_parsed_at":"2022-08-25T23:01:05.065Z","dependency_job_id":null,"html_url":"https://github.com/papercups-io/chat-widget","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papercups-io%2Fchat-widget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papercups-io%2Fchat-widget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papercups-io%2Fchat-widget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papercups-io%2Fchat-widget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papercups-io","download_url":"https://codeload.github.com/papercups-io/chat-widget/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247190255,"owners_count":20898702,"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","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":["chat","chat-widget","react"],"created_at":"2025-01-02T13:32:57.808Z","updated_at":"2025-04-04T14:10:10.260Z","avatar_url":"https://github.com/papercups-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @papercups-io/chat-widget\n\n\u003e Papercups chat widget\n\n[![NPM](https://img.shields.io/npm/v/@papercups-io/chat-widget.svg)](https://www.npmjs.com/package/@papercups-io/chat-widget)\n[![Downloads](https://img.shields.io/npm/dm/@papercups-io/chat-widget.svg)](https://www.npmjs.com/package/@papercups-io/chat-widget)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\n## Demo\n\nAvailable at https://app.papercups.io/demo\n\n![demo](https://user-images.githubusercontent.com/5264279/88118921-e4a37900-cb8c-11ea-825f-86deb8edc518.gif)\n\n## Install\n\n```bash\nnpm install --save @papercups-io/chat-widget\n```\n\n## Usage\n\nFirst, sign up at https://app.papercups.io/register to get your account token. Your account token is what you will use to pass in as the `accountId` prop below.\n\n### Using in HTML\n\nPaste the code below between your `\u003chead\u003e` and `\u003c/head\u003e` tags:\n\n```html\n\u003cscript\u003e\n  window.Papercups = {\n    config: {\n      // Pass in your Papercups account token here after signing up\n      token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx',\n      // Specify a Papercups inbox\n      inbox: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx',\n      title: 'Welcome to Papercups!',\n      subtitle: 'Ask us anything in the chat window below 😊',\n      newMessagePlaceholder: 'Start typing...',\n      primaryColor: '#13c2c2',\n      // Optionally pass in a default greeting\n      greeting: 'Hi there! How can I help you?',\n      // Optionally pass in metadata to identify the customer\n      customer: {\n        name: 'Test User',\n        email: 'test@test.com',\n        external_id: '123',\n        metadata: {version: 1, plan: 'premium'}, // Custom fields go here\n      },\n      // Optionally specify the base URL\n      baseUrl: 'https://app.papercups.io',\n      // Add this if you want to require the customer to enter\n      // their email before being able to send you a message\n      requireEmailUpfront: true,\n      // Add this if you want to indicate when you/your agents\n      // are online or offline to your customers\n      showAgentAvailability: true,\n    },\n  };\n\u003c/script\u003e\n\u003cscript\n  type=\"text/javascript\"\n  async\n  defer\n  src=\"https://app.papercups.io/widget.js\"\n\u003e\u003c/script\u003e\n```\n\n### Using in React\n\nPlace the code below in any pages on which you would like to render the widget. If you'd like to render it in all pages by default, place it in the root component of your app.\n\n```tsx\nimport React from 'react';\n\nimport {ChatWidget} from '@papercups-io/chat-widget';\n\n// You can also import the following in v1.1.0 and above:\n// import {ChatWidget, ChatWindow, Papercups} from '@papercups-io/chat-widget';\n//\n// The `ChatWindow` component allows you to embed the chat however you want,\n// and the `Papercups` object provides access to functions that can programmatically\n// open/close the chat widget, e.g.:\n//\n// `Papercups.open()` // =\u003e opens the chat widget\n// `Papercups.close()` // =\u003e closes the chat widget\n// `Papercups.toggle()` // =\u003e toggles (opens or closes) the chat widget\n\nconst ExamplePage = () =\u003e {\n  return (\n    \u003c\u003e\n      {/*\n        Put \u003cChatWidget /\u003e at the bottom of whatever pages you would\n        like to render the widget on, or in your root/router component\n        if you would like it to render on every page\n      */}\n      \u003cChatWidget\n        // Pass in your Papercups account token here after signing up\n        token='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'\n        // Specify a Papercups inbox\n        inbox='xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'\n        title='Welcome to Papercups!'\n        subtitle='Ask us anything in the chat window below 😊'\n        newMessagePlaceholder='Start typing...'\n        primaryColor='#13c2c2'\n        // Optionally pass in a default greeting\n        greeting='Hi there! How can I help you?'\n        // Optionally pass in metadata to identify the customer\n        customer={{\n          name: 'Test User',\n          email: 'test@test.com',\n          external_id: '123',\n          metadata: {version: 1, plan: 'premium'}, // Custom fields go here\n        }}\n        // Optionally specify the base URL\n        baseUrl='https://app.papercups.io'\n        // Add this if you want to require the customer to enter\n        // their email before being able to send you a message\n        requireEmailUpfront\n        // Add this if you want to indicate when you/your agents\n        // are online or offline to your customers\n        showAgentAvailability\n      /\u003e\n    \u003c/\u003e\n  );\n};\n```\n\n## Options\n\nThese are the props you can pass into your `\u003cChatWidget /\u003e` React component, or the fields you can specify in your `Papercups.config`:\n\n| Prop                              | Type                                | Value                                                                                                                      | Default                          |\n| :-------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |\n| **`token`**                       | `string`                            | Your Papercups account token                                                                                               | N/A                              |\n| **`inbox`**                       | `string`                            | The Papercups inbox you would like messages to flow into (defaults to your primary inbox)                                  | N/A                              |\n| **`accountId`** (deprecated)      | `string`                            | Your Papercups account token (deprecated: use `token` field instead)                                                       | N/A                              |\n| **`title`**                       | `string`                            | The title in the header of your chat widget                                                                                | Welcome!                         |\n| **`subtitle`**                    | `string`                            | The subtitle in the header of your chat widget                                                                             | How can we help you?             |\n| **`newMessagePlaceholder`**       | `string`                            | The placeholder text in the new message input                                                                              | Start typing...                  |\n| **`emailInputPlaceholder`**       | `string`                            | The placeholder text in the optional email input                                                                           | Enter your email                 |\n| **`newMessagesNotificationText`** | `string`                            | The notification text when new messages arrive and the chat window is closed                                               | View new messages                |\n| **`primaryColor`**                | `string`                            | The theme color of your chat widget                                                                                        | `1890ff`                         |\n| **`greeting`**                    | `string`                            | An optional initial message to greet your customers with                                                                   | N/A                              |\n| **`awayMessage`**                 | `string`                            | Replaces the `greeting` message if outside working hours                                                                   | N/A                              |\n| **`showAgentAvailability`**       | `boolean`                           | If you want to show whether you (or your agents) are online or not                                                         | `false`                          |\n| **`agentAvailableText`**          | `string`                            | The text shown when you (or your agents) are online                                                                        | We're online right now!          |\n| **`agentUnavailableText`**        | `string`                            | The text shown when you (and your agents) are offline                                                                      | We're away at the moment.        |\n| **`customer`**                    | `object`                            | Identifying information for the customer, including `name`, `email`, `external_id`, and `metadata` (for any custom fields) | N/A                              |\n| **`baseUrl`**                     | `string`                            | The base URL of your API if you're self-hosting Papercups                                                                  | https://app.papercups.io         |\n| **`iframeUrlOverride`**           | `string`                            | An override of the iframe URL we use to render the chat, if you chose to self-host that as well                            | https://chat-widget.papercups.io |\n| **`requireEmailUpfront`**         | `boolean`                           | If you want to require unidentified customers to provide their email before they can message you                           | `false`                          |\n| **`isOpenByDefault`**             | `boolean`                           | If you want the chat widget to open as soon as it loads                                                                    | `false`                          |\n| **`persistOpenState`**            | `boolean`                           | Persists the open state of the chat across pages                                                                           | `false`                          |\n| **`hideToggleButton`**            | `boolean`                           | Hides the toggle button in case you want to open/close programmatically                                                    | `false`                          |\n| **`hideOutsideWorkingHours`**     | `boolean`                           | Hides the chat widget outside of working hours set in Papercups                                                            | `false`                          |\n| **`popUpInitialMessage`**         | `boolean \\| number`                 | Pops up the initial greeting after `number` milliseconds (or immediately if `true`)                                        | `false`                          |\n| **`customIconUrl`**               | `string`                            | A link to a custom icon image URL                                                                                          | N/A                              |\n| **`iconVariant`**                 | `'outlined' \\| 'filled'`            | The style of the default icon                                                                                              | `outlined`                       |\n| **`position`**                    | `'right' \\| 'left'`                 | The position of the chat on the page                                                                                       | `right`                          |\n| **`styles`**                      | `object`                            | Inline style overrides for `chatContainer`, `toggleContainer`, and `toggleButton`                                          | `{}`                             |\n| **`onChatLoaded`**                | `({open, close, identify}) =\u003e void` | Callback fired when chat is loaded, returning some utility functions                                                       | N/A                              |\n| **`onChatOpened`**                | `() =\u003e void`                        | Callback fired when chat is opened                                                                                         | N/A                              |\n| **`onChatClosed`**                | `() =\u003e void`                        | Callback fired when chat is closed                                                                                         | N/A                              |\n| **`onMessageSent`**               | `(message: Message) =\u003e void`        | Callback fired when message is sent                                                                                        | N/A                              |\n| **`onMessageReceived`**           | `(message: Message) =\u003e void`        | Callback fired when message is received                                                                                    | N/A                              |\n\n## Development\n\nTo build the project, run `npm start` in the root directory. (If you're running it for the first time, you'll have to run `npm install` first.)\n\n```bash\nnpm install\nnpm start\n```\n\nTo test it out, use the `/example` directory:\n\n```bash\ncd example\nnpm install\nnpm start\n```\n\nThis will start a development server on [http://localhost:3000](http://localhost:3000) by default, and open up the example app in your browser.\n\n### Important notes\n\nBy default, the example widget points at development servers for the [Papercups API](https://github.com/papercups-io/papercups) (which runs at http://localhost:4000) and the [Papercups chat window](https://github.com/papercups-io/chat-window) (which runs at http://localhost:8080). These values are set with the [`baseUrl`](https://github.com/papercups-io/chat-widget/blob/master/example/src/App.tsx#L66) and [`iframeUrlOverride`](https://github.com/papercups-io/chat-widget/blob/master/example/src/App.tsx#L67) props respectively.\n\nIf you want to develop against your account in production, you can update these values to the following:\n\n- `baseUrl: http://app.papercups.io`\n- `iframeUrlOverride: https://chat-widget.papercups.io`\n\n_(Note that you can also simply remove these props, since the values above are the defaults.)_\n\nYou'll also want to update your account token to point to your own account. If you haven't already, create a free account at https://app.papercups.io/register to get started.\n\nOnce you have your account token, update the [`accountId`](https://github.com/papercups-io/chat-widget/blob/master/example/src/App.tsx#L46) prop to point at yours.\n\n## Questions?\n\nIf you're having any trouble getting started or just want to say hi, join us on [Slack](https://join.slack.com/t/papercups-io/shared_invite/zt-h0c3fxmd-hZi1Zp8~D61S6GD16aMqmg)! :wave:\n\n### Submitting a PR\n\nWe welcome any contributions! Please create an issue before submitting a pull request.\n\nWhen creating a pull request, be sure to include a screenshot! 🎨\n\n## License\n\nMIT © Papercups\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapercups-io%2Fchat-widget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapercups-io%2Fchat-widget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapercups-io%2Fchat-widget/lists"}