posthog / squeak

A Q&A widget for your docs

Build a community around your product with Squeak! by PostHog.

Squeak! is a toolkit for fostering a community in-house. It helps make discussions, resources, and solutions more accessible to the right people.

Learn more at squeak.posthog.com and star us to follow along.

Want to try it without installing? There's a cloud version of Squeak! too.

Toolkit

Squeak! tools are built for React-based static sites, but many products work with existing docs, knowledge bases, or websites.

Product	Description	Progress
Q&A.js	Add threaded discussions to any page of your docs or website	Beta
Discussion Warehouse	A repository to manage shared knowledge threads from Slack, Q&A.js, and other sources	Beta
Import Slack Threads	Liberate product-related discussions from Slack and make them discoverable by search engines	Alpha
Auth 2.0	OAuth, social logins	Summer 2022
Dynamic Open Graph Images	A custom social media graphic for every webpage across your docs or website	Summer 2022
Community Profiles	Bios, badges, activity feed, leaderboards, lists/directories	Summer 2022
Knowledge Repository	Lightweight, optimized content platform for docs, articles, guides, blogs	Summer 2022
Knowledge Search	Searchable interface for Discussions, Knowledge	Fall 2022
Page Builder	MDX + Storybook mashup w/ collections, lists, menus	Fall 2022
Dynamic Pages	Personalized content for each visitor by IP, UTM codes, or CRM	Winter 2022
Marketplace	Allow community to make money from services for the platform	Spring 2023

Docs

Visit the wiki for guides on:

1. Embeddable widget (JavaScript, React)
2. Admin portal
3. Integrations
4. Self-hosting
5. API
6. Local development

Links

• Roadmap
• Feature request? Create an issue!

About

Squeak! was created by PostHog out of a need to better support our own customers and move conversations out of our Slack community. Squeak! is open source under MIT.

Prisma

We use Prisma as our ORM. Prisma works by interpreting a schema file defined in prisma/schema.prisma and using a generated client. Prisma generates a strongly-typed client based on the schema file. The client is generated at runtime and not checked into version control. See the prisma docs about this. This means that the prisma client needs to be generated as part of any deployment process. As noted in the prisma docs, the prisma generate command is run as a postinstall hook when the prisma library is installed.

On deployment, the database needs to be migrated by running: npx prisma migrate deploy. See below for useful docs on production migrations:

• https://www.prisma.io/docs/concepts/components/prisma-migrate#production-and-testing-environments
• https://www.prisma.io/docs/guides/deployment/deploy-database-changes-with-prisma-migrate
• https://www.prisma.io/docs/reference/api-reference/command-reference#migrate-deploy

Sentry

We use Sentry to capture errors, and we need to upload source maps to sentry and create a release in sentry. Currently this happens while building the docker image. Sentry automatically hooks into the yarn build process and uploads source maps and creates a release. This requires having a SENTRY_AUTH_TOKEN environment variable set to be picked up by the sentry-cli.

We handle this currently during docker builds via Github Actions. We pass in the SENTRY_AUTH_TOKEN as an build-arg to Docker from a github secret. See .github/docker-release.yml for that configuration.

Superjson

This project uses superjson to automatically handle serialization issues, primarily with BigInt, which we use for certain IDs.

squeak's Issues

Admin skinning

Two mocks:

1. ]All questions](https://www.figma.com/proto/gCWYnrV5gubXjjFRnwGJSu/Squeak?page-id=106%3A48&node-id=361%3A4776&viewport=241%2C48%2C1&scaling=min-zoom&starting-point-node-id=361%3A4776&show-proto-sidebar=1)
2. Settings

Be sure to turn on comment mode (Shift + C) to show implementation notes littered between both mocks.

Inline Q&A

Currently questions only display wherever the JS widget is injected on a page.

But what if you could ask a question at a specific point on the page? This lets a user ask a question directly where they have it, and others can benefit from the answer being more contextual too.

(Think Medium callout + Notion commenting)

Demo

→ Wireframe demo

Screenshots

1. Hover near (the edge of the content) where you want to ask a question

2. Ask your thing

3. An icon and count shows there's a question there, and hovering displays a preview of the thread

4. Click a question to see the thread inline

5. Q&A widget still contains question, but also links to the spot on the page where it was asked

h/t @mariusandra for the inspiration to "ask a question literally anywhere!"

Admin console

We should provide a method of managing (deletion etc) questions/answers from the admin UI

We should also allow for editing of questions/responses to fix typos and to remove out-of-date information that may be confusing.

• View/delete questions/responses @smallbrownbike
• Users table (with role?) @joesaunderson
• Edit user: email, name, role @joesaunderson
• Settings pages (modify API keys for services, copy/paste JS code) @joesaunderson
• Invite user link to invite your team, then make it clear you need to upgrade their role @joesaunderson

Check for new Gravatars

Looks like we're storing Gravatar URLs in the DB instead of hitting Gravatar every time, so if a user adds a Gravatar, we don't pick it up?

This would also mean they'll never update, unless we're hitting Gravatar at some point to check?

Add Open Graph image to squeak.posthog.com

Source

Option to disable authentication for asking questions

Some customers might have issues with sending user's names/emails to a 3rd party. A way around this would be to disable the user account piece (for non-moderators).

Proposed flow:

1. User posts a question (skips preview mode)
2. Posts require moderation (too easy to spam without it)
3. Moderator approves question in Slack
4. Moderator authenticates and responds to post

Gaps in setup / docs

Creating this issue to document the gaps in the setup instructions that we've not currently got covered in the setup flow, that may need to be covered in the docs, or added to the setup flow.

• Site URL - does the JS snippet/code need to know the URL of the admin stack? Can we make this automatic on the snippet page, or does it need to be an input field?
• Supabase auth config - in order for the redirects to work on the login pages (both in the admin and the snippet), an allow-list of redirect URLs needs to be set in Supabase (via the UI, this can't be set via API). The settings look something like this:

The Site URL would be set to the site where the snippet will be deployed i.e posthog.com, the Additional Redirect URLs needs to be set to allow login on the admin stack, and need to be set to <ADMIN URL>/login,<ADMIN_URL>/setup/administration

Not getting Slack alerts

I have an OAuth token...

But I'm not getting any messages in my selected Slack channel.

Is there another step I need to take?

Empty state for questions

This is the homepage of the app, and it's pretty poor if you have no questions (when you first login)

Adjust "Database setup complete" description

Even though I opted to not enter Postgres creds (and chose to manually copy/paste in the SQL command), after hitting Validate, it displays the message that is only supposed to appear if you provided creds.

... were already provided...

Show logos of docs generators Squeak! is compatible with

"Does Squeak! work with my docs platform?"

If we show some logos, it might help with compatibility questions (even though it's just a JS widget you can drop in anywhere). Even better would be if we had tutorials on where we suggest to drop in the JS.

Some services we could list:

• Docsify
• Docusaurus
• Swagger
• Postman

Static site generators often used for this:

• Gatsby
• Next.js

Even other services like:

• Zendesk

Build out API to enable headless mode

Currently after #13, we have a basic API for adding a message and a reply.

In future, we should build out the API to enable users to use Squeak in a "headless" mode.

Clarify how to configure Slack

Our setup wizard asks for Slack Bot User OAuth Token.

It's a little unclear I should be generating an App-Level Token, and if so, which scope should be chosen.

After copying in what I thought was the correct token, I get a 500 error from /api/slack/channels:

(Note: presumed token removed for privacy)

Docker image size after adding migrations

After adding the migration workflow to the docker container, the container size has bloated three-fold.

This is because we now need to include node_modules in the container to allow the migration command in the entry-point file.

I evaluated two approaches:

• npx node-pg-migrate up - 114mb
• Copying node_modules and running yarn migrate up - ~350mb

We should come back to this and make a proper decision.

Widget style updates

p0

• Update Squeak! badging to this
• Remove "Supports" from "Supports Markdown"
• Make sure the Markdown icon is linked to a Markdown reference

Highly-visible issues

• Probably shouldn't be setting a global font just for the Squeak widget - should inherit font in parent site
  
• Add subtitle above preview: Preview post before publishing (h3)
  
• Change Sign in to post to h3, don't set font size, normal font color (needs to be more visible)
• On New user form, change password label from "Email password" to "Create a password"
  
• Reply box needs subtitle (h3): Reply to question

A few styles we need to override

(Conflicts on a pilot user site)

• On .squeak-form-richtext-buttons margin and padding, set !important
• Add .squeak-form-richtext-buttons li { list-style: none !important; padding: 0 !important;}

Enhancements

• After clicking Signout link (should call it Logout), we should have a Login link appear in its place
• Auto-focus Title field after pressing New question button
• Reply box: shorter by default, auto-grow
  
• Hover state for wysiwyg buttons

Better error handling, save confirmation messages

• If there's an error in something like connecting to Slack, errors appear in console but are not displayed on the page.
• When saving settings in the admin panel, there's no confirmation to let me know settings have been saved

Style error messages

Looks like we'll need a class, as there isn't much to latch onto here:

Decide if we want to use Supabase to support the cloud hosting

Allow editing of user name / email in admin UI

[Epic] Cloud hosting (vs self hosting)

It would be awesome to support a cloud version of Squeak to dogfood the app / for people who do not want to self-host.

Tasks/questions/ideas needed to make this happen, working list (feel free to overwrite add):

• #63
• #64
• #65
• Write a Postgres function similar to get_is_admin() to get the users organisation
• Add Postgres policies to enable RLS for the tables (to prevent access to another orgs data)
• Update the api routes to require an organisationId (and work out how to make this secure)
• Update the snippet to add the concept of an organisation (adding a question, reply, signing up)
• Add a method to disable the setup flow (for cloud)
• Build a cloud setup flow
• Allow for multiple config rows

Getting a 500 on Slack! thread import

Everything should be set up correctly. (It worked once before!)

Here's the manifest

Token and channel are selected

Squeak is installed to the channel

Profile badges

There are a couple of useful badges we can display so people know who is posting:

1. Author - appears in responses anytime the OP replies to a thread
2. Moderator - anyone who’s an admin/moderator in the admin panel

OAuth integration

So you don't have to have a separate authentication system just for Squeak!

[EPIC] Support other methods of authentication

For MVP, Squeak! uses Supabase for database and authentication.

In the future, Squeak! should have its own mechanism of authentication.

Later, it would be nice for Squeak! to integrate directly with a website's existing account system so users don't have to create a separate Squeak! account. (related: #112 )

Add image(s) to question/reply

As a user, I should be able to add an image to a question/response for clarity.

• Ability to upload image and have it added to the Markdown
• Ability to paste an image from clipboard using Ctrl/Cmd + V
• Clicking an image should expand the image (MVP: open in new window. GA: lightbox?)
• Drag and drop

Build squeak.posthog.com

Copy might change slightly but the bones seem good enough.

Figma prototype

Setup wizard UI

Proposing to put the setup wizard at squeak.yoursite.com/setup.

→ Balsamiq prototype

Wizard flow (6 screens)

1. Welcome (2 mocks)
   a) MVP version
   b) Future idea with multiple services
2. Database (2 mocks)
   a) Auto mode: has env vars
   b) Manual mode: no env vars passed
3. Admin
4. Thread notifications
5. Moderator alerts
6. Install JS snippet

Wires

As seen in prototype linked above, but with alternate screens

1a. Welcome (MVP)

1b. Welcome (future concept)

When Squeak! works with multiple services

2a. Database (auto)

If we have Postgres creds

2b. Database (manual)

If Postgres creds weren't provided

3. Administration auth

4. Thread notifications

5. Moderator alerts

6. Install JS snippet

Post-setup

After this, you'd proceed to your admin dashboard, which will minimal for now (user/moderator/admin management) until we build a UI to manage questions/comments (since you can do this in Supabase for now).

Mark responses with feedback

To surface the best answers to the top, we should offer the ability to mark a response as:

• Useful
• Not helpful
• Spam

By tracking these responses, we can eventually call out a particular answer at the top of the thread, or highlight it within context of multiple responses.

“I have this question, too!”

A way to say "me too" without saying "me too"

Also shows level of significance to the community

Post truncation

Objective: Shorten threads so they don't take up so much height

• Truncate author posts if > X
• Truncate replies after a few lines
• Cut off (fade out) thread after a certain length

We'll need to think through the designs for this, but here's some inspiration for the top-level post:

Change the data model to add the concept of organisation, each self hosted instance would have one organisation, but this will enable having multiple organisations on a cloud hosted instance.

Display role of author, repliers

There are a couple of useful badges we can display so people know who is posting:

1. Author - appears in responses anytime the OP replies to a thread
2. Moderator - anyone who’s an admin/moderator in the admin panel

I don't think we need additional roles for this.

Sorting posts

Two options to start with:

• Popular (number of replies, engagement) - default
• Most recent

Dependent on:

#55
#56

Option to reply from Slack

In a pre-productized version, we used Slack as a headless CMS and the build process for the PostHog website.

For this first productized version, we cut this functionality in lieu of reply directly on a thread. Providing the option to also optionally reply in Slack was going to be too complicated since everything would need to stay in sync if you can reply directly in Slack, as well as on the widget.

Reply (and publishing) a thread directly from Slack is a great workflow, so it'd be ideal to support this in the product.

Considerations

• Allowing a moderator to reply from Slack
• Keeping messages up to date (between website widget and Slack)
• Syncing Slack accounts with Squeak! accounts (for name, avatar, etc)
• Ability to modify URL(s) where questions appear, along with titles
• Editing process

Link to question on website from admin

Would be great to link question titles to where they appear. (As an admin, I don't see a way to read the question from the admin.)

Cursor incorrectly placed after clicking link button

1. Typed anchor text
2. Selected text
3. Clicked link button

Cursor was placed at the end of the text entry.

Expected: cursor between ()

Import threads from CSV

In order to seed questions & answers that have previously been solved on other platforms (eg: community Slack, existing FAQ page, etc), we need a way to import posts from a source like a CSV file. These are the inputs needed:

All fields are optional unless denoted with *.

1. Question
   Date, title*, description, author name, author avatar
2. Response (array)
   Date, response, author name, author avatar
3. URL(s) where question should appear (array)

Handle multiple admin accounts

Currently, the first user than signs-up (during setup) becomes the admin user for the instance.

We need a way to add/invite more admin users in future.

Use enum for role

In squeak_profiles_readonly, we should create an enum to represent the roles (currently user and admin - but there may be a concept of moderator in future?)

Add organisation ID FK to profiles, profiles_readonly, messages and replies and config

Moderation mode

As an admin, I want the option to approve all posts before they go live. Proposal:

post status: published | pending

By default, all posts should be published automatically.

When moderation mode is enabled, new posts are placed in pending mode and must be approved in the admin panel or via Slack.

The above was already done!

Right now, when moderation mode is ON, here’s what happens:

• Moderator must go to admin portal, find the thread, click Edit, and toggle a checkbox to publish it
• Replies are completely unmoderated, meaning even with moderation mode ON, anyone can always post a reply (so long as a thread is open)

Moderating new content

There should probably be a moderation feed (or a subset/filter on the Posts tab) that limits to unpublished content.

• In the admin panel, add Approve and Delete buttons for each question/response*
• Add a Slack action button to Approve or Delete` a question or response without leaving Slack

Rules

• Posts and responses a moderator bypassed the moderation process
• When a moderator views a thread, they should see all posts in sequence, but replies awaiting moderation should be distinguished visually. (Use case: As an admin, I want to reply, but need to see if others have already replied ahead of me, even if they aren’t published.)

Smart publish

We recently added the ability to turn off auto-publishing. This should help prevent spam from appearing automatically on sites, but it also prevents legitimate messages from appearing instantly.

There should be a way to only prevent malicious messages from automatically publishing. If we can determine if a message is malicious, we should be able to add a new smart auto-publish setting that checks the message first, then determines if it's safe to publish.

Getting a 404 after trying to post a question (after signing in)

1. Tried to post a question at the bottom of this page
2. Typed question, then signed in
3. Immediately after signing in, I get a 404 in console and question disappears on:

https://foliohd.com/support/undefined/api/question

https://www.loom.com/share/2b203406ac0f4054813a151bc8ec7bf8

Proposal: change default state of form

We currently show a button instead of a form.

Showing a form by default might be more enticing.

(Could also make this an option, depending on how visible the user wants the form to be.)

Document how to modify widget code

It looks like CSS is getting minified in the output in /public - do we have instructions on how to edit the source and recompile?

Allow a question with no description

There's a valid use case for having a short question where you don't need to add a description

Slack action: "Push Slack thread to website"

For those who want to move out of Slack communities, abilities to push a thread from Slack via an action would be a great way to lower the barrier to entry

Allow editing of questions / replies in admin UI

Squeak! MVP

Where is the line for a productized Squeak! MVP?

I'm proposing we focus on end-user features that will all compound to create a compelling product that you wouldn't want to try to build yourself. (It's basically everything already included in above mockup.)

1. #53
2. #55
3. #56
4. #57
5. #58 (stretch)

Ways to reduce barrier to entry

In order to have a good experience, you need questions and answers on your site. There are a couple ways to do this:

1. #59
2. #60

We should consider if these are worth including.

Other considerations

We should do a security audit and consider restrictions like limiting where your script can be run (eg: limited to specific domain(s)) along with localhost.

Final thought

These are all features we'd want to build for ourselves anyway, so I don't see any of this as going out of our way to productize which could go poorly if a public launch flops.

Authorized hostnames where Squeak! can be installed

… so others can’t take your script, put it on their site, and do bad things with it.