papercups-io / papercups

Open-source live customer chat

⚠️ Maintenance Mode

Papercups is in maintenance mode. This means there won't be any major new features in the near future. We will still accept pull requests and conduct major bug fixes. Read more here

Papercups

Papercups is an open source live customer support tool web app written in Elixir. We offer a hosted version at app.papercups.io.

You can check out how our chat widget looks and play around with customizing it on our demo page. The chat widget component is also open sourced at github.com/papercups-io/chat-widget.

Watch how easy it is to get set up with our Slack integration 🚀 :

One click Heroku deployment

The fastest way to get started is one click deploy on Heroku with:

Philosophy

We wanted to make a self-hosted customer support tool like Zendesk and Intercom for companies that have privacy and security concerns about having customer data going to third party services.

Features

• Reply from email - use Papercups to answer support tickets via email
• Reply from SMS - forward Twilio conversations and respond to SMS requests from Papercups
• Custom chat widget - a customizable chat widget you can embed on your website to talk to your customers
• React support - embed the chat widget as a React component, or a simple HTML snippet
• React Native support - embed the chat widget in your React Native app
• Flutter support - embed the chat widget in your Flutter app (courtesy of @aguilaair ❤️)
• Slack integration - connect with Slack, so you can view and reply to messages directly from a Slack channel
• Mattermost integration - connect with Mattermost, so you can view and reply to messages directly from Mattermost
• Markdown and emoji support - use markdown and emoji to add character to your messages!
• Invite your team - send invite links to your teammates to join your account
• Conversation management - close, assign, and prioritize conversations
• Built on Elixir - optimized for responsiveness, fault-tolerance, and support for realtime updates

Demo

We set up a simple page that demonstrates how Papercups works.

Try sending us a message to see what the chat experience is like!

Blog

Check out our blog for more updates and learnings

Documentation

Check out our docs at docs.papercups.io

Contributing

We ❤️ contributions big or small. See CONTRIBUTING.md for a guide on how to get started.

Thanks to all of our contributors!

License

MIT © Papercups

papercups's Issues

Fix how we save IP addresses of customers

Since we currently get very little info on the anonymous customers that interact with the chat widget, we save their IP addresses (so we can eventually do a location lookup)

At the moment, we use conn.remote_ip (https://github.com/papercups-io/papercups/blob/master/lib/chat_api_web/controllers/customer_controller.ex#L17), but this ~seems to only return private IP addresses.

Investigate this as a possible solution? https://www.cogini.com/blog/getting-the-client-public-ip-address-in-phoenix/

When responding from slack show 🙂 instead of :slight_smily_face

When you send emoji from slack it shows up as string instead of emoji

Set up factories for our tests to DRY them up

See https://hexdocs.pm/ecto/test-factories.html

Currently a bunch of our tests have the same boilerplate code... let's try to DRY it up with factories!

Fix Slack messaging if user reconnects to a different channel

If a user starts a conversation in one Slack channel, and then reconnects their account to a different Slack channel, the following messages in that conversation thread get messed up.

We need to either:

1. Keep sending messages to the old thread
2. Start a new thread in the new channel

Option 1 makes it easier to see the history of a thread, but Option 2 still seems better (I wouldn't want to have to keep going back and forth to old channels, but maybe this is inevitable either way...)

Reduce delay when closing a message

Need to figure out the best UX for this -- didn't want the message disappearing to feel too jarring, but don't want it to feel slow either... maybe just a quick animation?

Show notifications of closed conversations

There are no notifications for closed conversations in the dashboard. Only an email is sent. Closed conversation notifications should still be displayed.

Alternatively, closed conversations should no longer be displayed in the client and a new conversation should be started.

Invitation is broken

Company name is required

[Low priority] Prevent users from signing up with an expired invitation

The user_invitation table has an expires_at field which should be taken into account when signing up. If the invite has expired, throw an error and let the user know.

Set working hours

Users want the ability to set working hours and automatically prompt for Email address when they are away.

Media library

Chat widget

Demo:

Sped up:

Conversations

Demo:

Screenshot:

Slack

Demo:

Getting started

Screenshot:

Integrations

Screenshot:

Playground

Ability to Disable Registration

Hello,

I couldn't find a way to disable registration after creating the initial account (also tried to look through the source/docs).
Is there a way to prevent anyone from creating a new org on my deployment?

If it hasn't been build/spec'd yet, here's a potential direction:

As an Admin
I want to restrict outside registration
So that my instance of papercups is secure

Options:

• environment variable like REGISTRATION_DISABLED=true that would default to false if not set (might be the quickest V1)
• switch in UI

Other considerations:

• how does an admin know once they set it the deployment that other instances have not been registered?

Like the direction & plan to use this 🤓

Set up integration with Microsoft Teams

Action items

• Download Microsoft Teams (so you can test things out): https://www.microsoft.com/en-us/microsoft-365/microsoft-teams/download-app
• Figure out how to get an auth token
  • Top level overview: https://docs.microsoft.com/en-us/graph/auth/
  • Auth basics: https://docs.microsoft.com/en-us/graph/auth/auth-concepts
• Figure out how to send a message to a channel programmatically
  • MS Teams API docs: https://docs.microsoft.com/en-us/graph/api/resources/teams-api-overview?view=graph-rest-1.0
  • Maybe check out "creating a chatMessage" API: https://docs.microsoft.com/en-us/graph/api/channel-post-message?view=graph-rest-1.0&tabs=http

Old notes (can ignore)

Some folks have requested this integration, so let's do some investigation into how difficult it would be. (It sounds like it shouldn't be too difficult.)

Maybe see our Slack integration for some inspiration? https://github.com/papercups-io/papercups/blob/master/lib/chat_api/slack.ex

It's not obvious that invite URLs are one-time use only

We should either make this more clear, or just allow invite URLs to be used as many times as people like until they expire

Prompt to collect email at the beginning of the conversation

Conversations should reopen if someone messages after you close the conversation

When a person messages a closed message it should reopen the closed message. Right now it doesn't reopen and the message disappears.

Online status disappears after revisiting the page

Refresh the page on the widget the online status disappears and online status doesn't reshow up

papercup image on ducker hub

I was trying to run the project using docker-compose but there is a problem Papercups image does not exist in the docker hub and it will fail to run.

https://github.com/papercups-io/papercups/blob/master/docker-compose.yml#L5

I believe that we need to build and push the latest image, based on repo tags to the docker hub using Github Actions or any other CI service.

Fix duplicate conversations created

(This might be an issue in https://github.com/papercups-io/chat-widget)

Sometimes when we receive messages in the dashboard, we get duplicate conversations created with the same message (or empty messages)

Fix icon for "Logout"

We currently have a "settings" icon for the "Logout" button in the dashboard:

Here's the line it's on: https://github.com/papercups-io/papercups/blob/master/assets/src/components/Dashboard.tsx#L143

Find a more appropriate icon here: https://ant.design/components/icon/

And then import in here https://github.com/papercups-io/papercups/blob/master/assets/src/components/icons.tsx before replacing the existing icon

Telegram support

Integrate with Telegram, be able to reply through telegram

Add transactions during account creation

During account creation we first create the account then the user. If the user creation fails then you will have an account thats created without a user attached.

Repro:
Register for account
Enter mismatch passwords or empty fields

There would be a new account created in the table but no users associated.

[Low priority] Consider removing `create_or_update`s

Instead of doing a create_or_update for our user profile, user settings, widget settings, it might make more sense to just create these initial records when a user signs up for the first time and just do updates in the future.

See this thread: #74 (comment)

If customer email is available, send message to them via email if they are offline

Right now if a customer goes offline and we respond, they won't see the message unless they come back to the page and open the widget -- would be nicer if they could get answers to their questions/comments via email if possible.

Redeploy shouldn’t trigger everyone to relogin

Currently for the hosted version every deploy triggers a re login

Create user "Profile" tab under the "Accounts" section in the nav

We'll keep this page simple for now... just a profile page with:

• an input for the user's name
• an input for the user's profile image url (we'll support image upload in a future ticket)

Let's create a new table user_profiles to store this data, with a name string field and a profile_image_url string field, along with a user_id reference to the users table.

Implement these API endpoints:

• GET /api/profile - fetch the current user's profile
• PUT /api/profile - update the current user's profile

Support real time message time

It would be nice if the message time in the chat were real-time, you can archive that using a library like timeago.js, they support real-time render.

Cmd + enter to send message

Having to press the send button every time is tedious. We should support cmd + enter and ctrl enter for windows equivalent shortcuts. We shouldn't have enter by default since longer messages you might want multiple lines and you don't want to accidentally send

Figure out how to map Slack users to Papercups users

...so that when we respond from Slack, it knows who to show in the chat widget.

I'm hoping there's a "clever" way we can just match based on email, but if not we may need to set up a little UI to do it manually :/

(currently we just fall back to showing the sender as whoever the user was that set up the Papercups account)

Profile picture not showing up

Profile picture shows up in the demo page but doesn't show up when you install it separately on a different app

Webex Teams integration

I would like to see (and contribute to) an integration with Webex Teams. Similar to Slack, i think this could be a great connectivity option for many organizations.

[Preview] Setting up Slack

Setting up Slack

If you plan on self-hosting Papercups, you'll need to set up your own Slack app if you want to handle messaging through Slack.

Creating the app

• Go to https://api.slack.com/apps
• Click “Create New App”
• Name it whatever you’d like, and pick the Slack workspace you’d like to test it against

Subscribing to Slack events

• Go to “Event Subscriptions”
• Toggle “Enable Events” to “On”
• Input your webhook URL in the “Request URL” input
  • It should look like https://YOUR_APP_HOST/api/slack/webhook
  • In my case, this was https://alex-papercups-staging.herokuapp.com/api/slack/webhook

• Subscribe to the message.channels bot event
• Subscribe to the message.channels user event

Setting up scopes and permissions

• Go to “OAuth & Permissions”
• Click the “Install App to Workspace” button to install your app to your test workspace if you haven’t already

• Add the redirect URL we’ll be using in the dashboard
  • It should look like https://YOUR_APP_HOST/integrations/slack
  • In my case, this was https://alex-papercups-staging.herokuapp.com/integrations/slack

• Add the bot scopes we’ll be using
  • channels:history
  • channels:manage
  • chat:write
  • chat:write.public
  • incoming-webhook

• Add the user scopes we’ll be using
  • channels:history

Enabling distribution of your app

• Set up your app for distribution
• Under “Basic Information”, go to the “Manage distribution” section and click “Distribute App”

• Indicate that hard-coded information has been removed from your code
  • (We’ve handled this for you!)

• Click on “Activate Public Distribution”

Setting up your environment variables

• In the “Basic Information” section, scroll down to “App Credentials” to get the keys you’ll be using as environment variables

• Export the following environment variables:

export PAPERCUPS_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
export REACT_APP_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
export PAPERCUPS_SLACK_CLIENT_SECRET='YOUR_CLIENT_SECRET_HERE'

• If you're using Heroku, set the environment variables on the config:

heroku config:set PAPERCUPS_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
heroku config:set REACT_APP_SLACK_CLIENT_ID='YOUR_CLIENT_ID_HERE'
heroku config:set PAPERCUPS_SLACK_CLIENT_SECRET='YOUR_CLIENT_SECRET_HERE'

Testing

• Go to the /integrations path in your dashboard
• Click on "Connect" for Slack

• Go through the OAuth flow for your app
• Select a channel to connect with

• If successful, it should take you back to this page:

• To test that it works, go to the "Getting started" tab
• Try sending a message in the widget on the right:

• Check Slack to verify you received a message
• Try sending a reply through Slack

• Verify that the reply was received

Done!

That should be it! Feel free to open an issue if you have any problems getting set up :)

the chat box should grow if the user types more than 1 line

Right now if you type in more than one line it starts scrolling

Add ability to remove users from team

Future pricing model for the hosted version?

Hi papercups!!!
came from HN, and I just LOVE your work
just wanted to say thanks for democratizing chat widgets, really means a lot for the internet community in general honestly

I just wanted to inquire about the pricing model for the hosted version, since I'm looking to migrate from Hubspot.
Is there a general ballpark on how much the hosted version will cost a month for the enterprise?
Thanks!

Draft a public roadmap of upcoming/planned features

Need to make our prioritizations a bit more clear

Google Tag Manager Issue / Broken in Chrome?

Hello,

I just did a fresh install on heroku with the deploy button.

I'm getting an error in chrome, even when I turn off ublock origin.

With uBlock on:

With uBlock off:

Investigate XMPP support

See this comment: https://elixirforum.com/t/an-open-source-alternative-to-intercom-drift-etc/33450/4

I'm not too familiar with XMPP, but wanted to kick off a discussion thread here so I don't forget about it :)

User Metadata + documentation

Hello again, writing up info from discord convo with Alex.

Use case, Jane Smith has logged into my SASS app, I'd like to be able to pass in the following to the JSON snippet/metadata if possible... guessing this is on your roadmap if this would be possible - #107:

first_name: Jane
email: [email protected]
user_id: 'ff71ef5f-91c9-4971-9619-36dccdb5e055'
subscription_level: pro
team/group/workspace_name: Acme Co
team/group/workspace_id: '4e2aa643-2b92-4f03-8fb8-f5aefe799594
registration_date: 2020-08-12T19:42:22Z

Extra bonus:

• if current_page/ url was captured when the chat started.

Notes

• first name could feed into the bot saying "Hello Jane" if she opened the widget.
• email could be used for #107
• team/group/workspace & subscription_level could be used for email filtering as part of the emailing functionality
• registration_date could be used for filtering/cohort building as well.

User Story:

As a client success rep
I want to pre-identify users I'm chatting with
So that I do not have to ask them for baseline context of who they are

Support markdown in chat messages

Maybe give this a shot? https://marked.js.org/#/README.md

This could also work: https://github.com/rexxars/react-markdown

First goal would just be:

• If I type **Hello** _world_ www.papercups.io
• I see: Hello world www.papercups.io

[Low priority] convert `users` table id to UUID type

(Instead of just an auto-incrementing integer)

Add ability to delete a conversation

For privacy reasons there should be the possibility to delete a conversation from the server.

[Edit from @reichert621]
Before we can fully support this, we'll need to fix some foreign key issues... namely, when a conversation is deleted, we should probably auto-delete all associated messages/slack threads/etc

Include `account_id` in more Ecto (SQL) `where` clauses

For API endpoints that should be secured (e.g. these: https://github.com/papercups-io/papercups/blob/master/lib/chat_api_web/router.ex#L52-L56) we need to make sure we're always limiting the data returned to the current user's account_id

The account id can be accessed on conn.assigns.current_user in each request like so:
https://github.com/papercups-io/papercups/blob/master/lib/chat_api_web/controllers/conversation_controller.ex#L11 (there are probably more idiomatic ways to do that, but this works for now 🤷‍♂️ )

Here's an example of filtering by account_id in one of the contexts: https://github.com/papercups-io/papercups/blob/master/lib/chat_api/messages.ex#L21

Docker deployment?

I have an almost-functioning Dockerfile, happy to contribute it if this is something you are interested in supporting.

Embedding email in slack with long message overflows the string

Delete user invitation links after they are used

Right now user invitations (from user_invitations table) never get deleted, but we should delete them after they are successfully used.

This is where we currently use it: https://github.com/papercups-io/papercups/blob/master/lib/chat_api_web/controllers/registration_controller.ex#L14

If the registration is successful, the user_invite record should be deleted.

Browser validation for miss match passwords

When a user enters the wrong confirm password on registration page we should tell them that it is miss matched on the browser side

Run on a non-default port

I'm trying to run papercups on a different port than 4000. I set the env var PORT the port to 8080, and started the server using mix phx.server, on the prod configuration

When the server starts, I get this error:

root@papercups-684699d878-57j66:/usr/src/app# export PORT=8080
root@papercups-684699d878-57j66:/usr/src/app# mix phx.server
[info] Running ChatApiWeb.Endpoint with cowboy 2.8.0 at :::8080 (http)
[info] Access ChatApiWeb.Endpoint at http://localhost:8080
Something is already running on port 8080.

No matter the port I put in, it fails. If I remove the part of the code that's reading from an env var, and hardcode port 8080, it all works fine.

Any ideas?

Add support for webhooks

Support for some kind of (web)hooks, for example when a chat is initiated and perhaps email has been entered, initiate hook which might return a list of orders from that customer (visible to the agents only, of course).

Or whenever a message is sent/received, a hook could look at the message and provide additional data (a simple regexp on the message might detect order numbers (x characters long and only numbers) which could then provide the agent with a direct URL to the order in the (ecommerce) backend.

Use Phoenix Presence to indicate when a customer is online

This will require some tweaks to https://github.com/papercups-io/chat-widget to send over the customer_id when connecting to a socket. Once that's setup, we can start using Presence to detect when a customer is online, and use a little green badge or something to indicate so in the dashboard.

First chat message sent is slow

When you send a message from a new browser or incognito the first messages is much slow the normal.