BTCforPlebs/nostr-chat-widget
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
nostr-chat-widget/config_docs.md

7.9 KiB
Raw Permalink Blame History

Configuration Guide

This guide walks you through configuring the Nostr Chat Widget for your website.

Table of Contents

Basic Setup

Step 1: Include Dependencies

Add these to your HTML <head>:

<!-- Tailwind CSS for styling -->
<script src="https://cdn.tailwindcss.com"></script>

<!-- Import map for nostr-tools -->
<script type="importmap">
{
  "imports": {
    "nostr-tools": "https://esm.sh/nostr-tools@1.17.0"
  }
}
</script>

Step 2: Add the Widget

Before your closing </body> tag:

<!-- Chat widget script -->
<script type="module" src="path/to/chat.js"></script>

<!-- Chat widget container -->
<div id="chat-widget-root"></div>

Step 3: Configure Your Public Key

Open chat.js and locate the CONFIG object:

const CONFIG = {
  relays: [
    'wss://relay.damus.io',
    'wss://relay.primal.net',
    'wss://nos.lol',
    'wss://relay.btcforplebs.com',
    'wss://relay.logemedia.com'
  ],
  csPubkey: 'YOUR_PUBLIC_KEY_HERE' // Replace with your hex public key
};

Getting Your Nostr Keys

Option 1: Using an Existing Nostr Client

If you already use Nostr:

  1. Open your Nostr client (Damus, Amethyst, Snort, etc.)
  2. Go to Settings → Keys/Security
  3. Copy your public key (NOT your private key)
  4. If it starts with npub1, convert it to hex format (see below)

Option 2: Generate New Keys

For a fresh customer support identity:

  1. Install a Nostr client:

  2. Create a new account

  3. IMPORTANT: Securely save your private key (nsec)

  4. Copy your public key for the config

Converting npub to Hex

If your public key starts with npub1:

Online Tool:

Using JavaScript:

import { nip19 } from 'nostr-tools';
const hex = nip19.decode('npub1...').data;
console.log(hex);

Relay Configuration

Default Relays

The widget connects to multiple relays for reliability:

relays: [
  'wss://relay.damus.io',      // General purpose, reliable
  'wss://relay.primal.net',    // Popular, good uptime
  'wss://nos.lol',             // Community favorite
  'wss://relay.btcforplebs.com', // Bitcoin-focused
  'wss://relay.logemedia.com'  // Custom relay
]

Choosing Relays

Good relays have:

  • High uptime (99%+)
  • Good geographic distribution
  • Support for kind 4 events (DMs)
  • Read/write permissions

Popular Relay Lists:

Running Your Own Relay

For maximum control, run your own Nostr relay:

Quick Setup:

# Using nostr-rs-relay (Rust)
docker run -d -p 8080:8080 scsibug/nostr-rs-relay

# Using strfry (C++)
# See: https://github.com/hoytech/strfry

Then add to your config:

relays: [
  'wss://your-relay.example.com',
  // ... plus backup public relays
]

Customization

Colors

The widget uses Tailwind classes. Change colors by replacing:

Primary gradient (orange):

// Find in chat.js:
from-[#fdad01] to-[#ff8c00]

// Replace with your brand colors:
from-[#4F46E5] to-[#7C3AED]  // Purple
from-[#10B981] to-[#059669]  // Green
from-[#EF4444] to-[#DC2626]  // Red

Connection indicator:

// Green dot when connected:
bg-green-400

// Change to match your theme:
bg-blue-400
bg-purple-400

Position

Change the widget position in chat.js:

// Bottom-right (default)
className="fixed bottom-4 right-4 sm:bottom-6 sm:right-6"

// Bottom-left
className="fixed bottom-4 left-4 sm:bottom-6 sm:left-6"

// Top-right
className="fixed top-4 right-4 sm:top-6 sm:right-6"

Branding

Team Name:

// Find in chat.js render function:
<div class="text-xs font-semibold text-[#fdad01] mb-1">Loge Media Team</div>

// Replace with:
<div class="text-xs font-semibold text-[#fdad01] mb-1">Your Team Name</div>

Header Title:

<h3 class="font-bold text-base sm:text-lg">Instant Chat</h3>

// Change to:
<h3 class="font-bold text-base sm:text-lg">Need Help?</h3>

Receiving Messages

Setting Up Your Client

  1. Import Your Private Key

    • Open your Nostr client
    • Go to Settings → Import Key
    • Paste your private key (nsec or hex)
    • NEVER share your private key

  2. Enable DM Notifications

    • Settings → Notifications
    • Enable "Direct Messages"
    • Enable push notifications (mobile)

  3. Monitor for Messages

    • New chat sessions will appear as DMs
    • Each session has a unique temporary public key
    • Reply directly - users see responses instantly

Recommended Clients

Desktop/Web:

Mobile:

Multi-device Tips:

  • Use the same private key across devices
  • Messages sync automatically via relays
  • Consider a dedicated device/account for support

Advanced Configuration

Session Duration

Change the 24-hour session expiry:

// In getSessionKey() function:
if (Date.now() - session.created < 24 * 60 * 60 * 1000) {
  // Change to 48 hours:
  if (Date.now() - session.created < 48 * 60 * 60 * 1000) {
  // Change to 12 hours:
  if (Date.now() - session.created < 12 * 60 * 60 * 1000) {

Multiple Support Accounts

Support multiple team members:

const CONFIG = {
  relays: [...],
  csPubkeys: [
    'team-member-1-hex-pubkey',
    'team-member-2-hex-pubkey',
    'team-member-3-hex-pubkey'
  ]
};

// Then update subscribeToReplies():
authors: CONFIG.csPubkeys

Custom Welcome Message

Add an automatic welcome message:

// In init() function, after subscribeToReplies():
setTimeout(() => {
  addMessage('cs', 'Hi! How can we help you today?');
}, 500);

Troubleshooting

Widget Not Appearing

  • Check browser console for errors
  • Verify Tailwind CSS is loaded
  • Ensure import map is correct
  • Check #chat-widget-root div exists

Messages Not Sending

  • Verify relay connections in console
  • Check public key is in hex format
  • Ensure relays support kind 4 (DMs)
  • Try different relays

Not Receiving Replies

  • Confirm correct private key in client
  • Check relay overlap (client and widget)
  • Verify DM notifications enabled
  • Check client is connected to relays

Mobile Issues

  • Clear browser cache
  • Check responsive CSS is applied
  • Test on actual device, not just emulator
  • Verify safe-area-inset for notched devices

Security Best Practices

  1. Never expose private keys

    • Only use public keys in client code
    • Store private keys securely (password manager)
    • Never commit keys to version control

  2. Use HTTPS

    • Serve widget over secure connection
    • Some relays require wss:// (secure websockets)

  3. Rate limiting

    • Consider implementing rate limits
    • Monitor for spam/abuse
    • Block abusive session keys if needed

  4. Session management

    • Sessions expire automatically
    • No persistent user tracking
    • Messages stored only in localStorage

Support

Need help? Issues? Contributions?

Reference in New Issue View Git Blame Copy Permalink