Add Get help to your site, with one line.

Get help is a small button in the corner of your site. Your customer opens it, signs in, and writes to your team. Each conversation is private: a customer only ever sees their own.

You answer from your Community Hub’s Support inbox. When a customer is away, your reply reaches them by email, sent in your Studio’s name.

1. Open your Community Hub, then Support.
2. Press the </> icon and copy the line it shows.
3. Paste the line into your site’s HTML, just before </body>. It works on any site served over https.

Want to see it before you paste anything? In the same </> window, press Try it. It opens a page on your own Studio address with the bubble working, so you can send yourself a message and answer it from Support.

Your customer presses Help, signs in with an email code or with Google, and starts writing. Next time they are already signed in. They see their own conversation and nothing else of your Community Hub.

Help is never sold: a customer gets their own conversation even if your Community Hub is paid. Joining the Community Hub itself stays as you set it.

• Mark a conversation Open or Resolved.
• Assign it to someone on your team.
• Leave an internal note that only your team sees.
• Block someone who is abusing it. They can no longer write to you or open a new conversation.
• Make it public: turn a good question and its answer into a post in one of your Q&A channels, so the next person finds it. The customer is told by email.

This part is for your developer. If your product has its own login, your customers should not sign in a second time to ask for help. Your server vouches for the person who is signed in, and the bubble opens straight into their conversation.

It takes three steps: make a secret, sign a short token on your server, and hand that token to the bubble in the page.

In the </> window, open Sign in your users and press Make a secret. It is shown once: copy it into your server’s environment as SOLOBASE_SUPPORT_SECRET.

For the person who is signed in, sign a JSON Web Token with HS256 and your secret, and give it to your page from an endpoint only signed-in people can call. The token holds:

• sub: your own id for this person, up to 128 characters, with no spaces. It is how we know them next time.
• email and name: optional. Your team sees them, and replies are emailed to that address.
• iat and exp: when it was signed and when it expires, at most 10 minutes apart. Five minutes is plenty.
• jti: optional. If you send one, each token works once.

import jwt from 'jsonwebtoken';

// Only for a signed-in person.
app.get('/api/support-token', requireLogin, (req, res) => {
  const token = jwt.sign(
    { sub: String(req.user.id), email: req.user.email, name: req.user.name },
    process.env.SOLOBASE_SUPPORT_SECRET,
    { algorithm: 'HS256', expiresIn: '5m' }
  );
  res.json({ token });
});

import os, time, jwt

def support_token(user):
    now = int(time.time())
    return jwt.encode(
        {"sub": str(user.id), "email": user.email, "name": user.name,
         "iat": now, "exp": now + 300},
        os.environ["SOLOBASE_SUPPORT_SECRET"],
        algorithm="HS256",
    )

require "jwt"

now = Time.now.to_i
token = JWT.encode(
  { sub: user.id.to_s, email: user.email, name: user.name,
    iat: now, exp: now + 300 },
  ENV.fetch("SOLOBASE_SUPPORT_SECRET"),
  "HS256"
)

use Firebase\JWT\JWT;

$now = time();
$token = JWT::encode([
    'sub' => (string) $user->id,
    'email' => $user->email,
    'name' => $user->name,
    'iat' => $now,
    'exp' => $now + 300,
], getenv('SOLOBASE_SUPPORT_SECRET'), 'HS256');

In the page, below the Get help line, fetch the token from your endpoint and pass it on. When the person logs out, shut the bubble down, so the next person on that computer starts fresh.

<script>
  fetch('/api/support-token', { credentials: 'include' })
    .then((response) => (response.ok ? response.json() : null))
    .then((data) => {
      if (data) SolobaseBubble('identify', data.token);
    });
</script>

SolobaseBubble('shutdown');

• The secret never leaves your server. The token in the page lasts minutes and opens one conversation only.
• Rotate gives you a new secret and keeps the old one working for 24 hours, so you can update your server without a gap.
• Turn off stops every token at once. Use it if the secret leaks, then make a new one.
• The people you sign in belong to your Community Hub only. They are never matched to a SoloBase account by their email, so a token can only ever open their conversation with you.
• Replies are emailed only for that person’s own conversation, in your Studio’s name, with an unsubscribe link and a daily limit.

When a token is refused, the bubble falls back to its own sign-in, so your customer can still reach you. The usual causes:

• The token has expired. It lives at most 10 minutes from when it was signed, so fetch a fresh one each time the page loads, and check that your server’s clock is right.
• The token is signed with the wrong secret, often the old one after a rotate has run its 24 hours. Update SOLOBASE_SUPPORT_SECRET and restart your server.
• Sign in your users is not set up, or was turned off. Make a secret in the </> window.
• The same token was used twice while it carried a jti. Sign a new one each time.
• The browser says SolobaseBubble is not defined. The call ran before the Get help line: move it below that line.
• The person was blocked by your team. The bubble tells them, and they cannot write in.

Write to support@solobase.org and we will help you set it up.