Skip to main content

Setting up chat

Demo#

Available at https://app.papercups.io/demo

demo

Usage#

First, 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.

Using in HTML#

Paste the code below between your <head> and </head> tags:

<script>
window.Papercups = {
config: {
// Pass in your Papercups account token here after signing up
accountId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx',
title: 'Welcome to Papercups!',
subtitle: 'Ask us anything in the chat window below ๐Ÿ˜Š',
newMessagePlaceholder: 'Start typing...',
primaryColor: '#13c2c2',
// Optionally pass in a default greeting
greeting: 'Hi there! How can I help you?',
// Optionally pass in metadata to identify the customer
customer: {
name: 'Test User',
email: 'test@test.com',
external_id: '123',
metadata: {version: 1, plan: 'premium'}, // Custom fields go here
},
// Optionally specify the base URL
baseUrl: 'https://app.papercups.io',
// Add this if you want to require the customer to enter
// their email before being able to send you a message
requireEmailUpfront: true,
// Add this if you want to indicate when you/your agents
// are online or offline to your customers
showAgentAvailability: true,
},
};
</script>
<script
type="text/javascript"
async
defer
src="https://app.papercups.io/widget.js"
></script>

Using in React#

Install the @papercups-io/chat-widget node module:

npm install --save @papercups-io/chat-widget

Place 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.

import React from 'react';
import {ChatWidget} from '@papercups-io/chat-widget';
// You can also import the following in v1.1.0 and above:
// import {ChatWidget, ChatWindow, Papercups} from '@papercups-io/chat-widget';
//
// The `ChatWindow` component allows you to embed the chat however you want,
// and the `Papercups` object provides access to functions that can programmatically
// open/close the chat widget, e.g.:
//
// `Papercups.open()` // => opens the chat widget
// `Papercups.close()` // => closes the chat widget
// `Papercups.toggle()` // => toggles (opens or closes) the chat widget
const ExamplePage = () => {
return (
<>
{/*
Put <ChatWidget /> at the bottom of whatever pages you would
like to render the widget on, or in your root/router component
if you would like it to render on every page
*/}
<ChatWidget
// Pass in your Papercups account token here after signing up
accountId="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx"
title="Welcome to Papercups!"
subtitle="Ask us anything in the chat window below ๐Ÿ˜Š"
newMessagePlaceholder="Start typing..."
primaryColor="#13c2c2"
// Optionally pass in a default greeting
greeting="Hi there! How can I help you?"
// Optionally pass in metadata to identify the customer
customer={{
name: 'Test User',
email: 'test@test.com',
external_id: '123',
metadata: {version: 1, plan: 'premium'}, // Custom fields go here
}}
// Optionally specify the base URL
baseUrl="https://app.papercups.io"
// Add this if you want to require the customer to enter
// their email before being able to send you a message
requireEmailUpfront
// Add this if you want to indicate when you/your agents
// are online or offline to your customers
showAgentAvailability
/>
</>
);
};

Options#

These are the props you can pass into your <ChatWidget /> React component, or the fields you can specify in your Papercups.config:

PropTypeValueDefault
accountIdstringYour Papercups account tokenN/A
titlestringThe title in the header of your chat widgetWelcome!
subtitlestringThe subtitle in the header of your chat widgetHow can we help you?
newMessagePlaceholderstringThe placeholder text in the new message inputStart typing...
emailInputPlaceholderstringThe placeholder text in the optional email inputEnter your email
newMessagesNotificationTextstringThe notification text when new messages arrive and the chat window is closedView new messages
primaryColorstringThe theme color of your chat widget1890ff
greetingstringAn optional initial message to greet your customers withN/A
showAgentAvailabilitybooleanIf you want to show whether you (or your agents) are online or notfalse
agentAvailableTextstringThe text shown when you (or your agents) are onlineWe're online right now!
agentUnavailableTextstringThe text shown when you (and your agents) are offlineWe're away at the moment.
customerobjectIdentifying information for the customer, including name, email, external_id, and metadata (for any custom fields)N/A
baseUrlstringThe base URL of your API if you're self-hosting Papercupshttps://app.papercups.io
iframeUrlOverridestringAn override of the iframe URL we use to render the chat, if you chose to self-host that as wellhttps://chat-widget.papercups.io
requireEmailUpfrontbooleanIf you want to require unidentified customers to provide their email before they can message youfalse
defaultIsOpenbooleanIf you want the chat widget to open as soon as it loadsfalse
customIconUrlstringA link to a custom icon image URLN/A
onChatLoaded() => voidCallback fired when chat is loadedN/A
onChatOpened() => voidCallback fired when chat is openedN/A
onChatClosed() => voidCallback fired when chat is closedN/A
onMessageSent(message: Message) => voidCallback fired when message is sentN/A
onMessageReceived(message: Message) => voidCallback fired when message is receivedN/A

Development#

To 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.)

npm install
npm start

To test it out, use the /example directory:

cd example
npm install
npm start

This will start a development server on http://localhost:3000 by default, and open up the example app in your browser.

Important notes#

By default, the example widget points at development servers for the Papercups API (which runs at http://localhost:4000) and the Papercups chat window (which runs at http://localhost:8080). These values are set with the baseUrl and iframeUrlOverride props respectively.

If you want to develop against your account in production, you can update these values to the following:

  • baseUrl: http://app.papercups.io
  • iframeUrlOverride: https://chat-widget.papercups.io

(Note that you can also simply remove these props, since the values above are the defaults.)

You'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.

Once you have your account token, update the accountId prop to point at yours.

Questions?#

If you're having any trouble getting started or just want to say hi, join us on Slack! ๐Ÿ‘‹

Submitting a PR#

We welcome any contributions! Please create an issue before submitting a pull request.

When creating a pull request, be sure to include a screenshot! ๐ŸŽจ