akachat 🚀

A lightweight, self-hosted, 100% free live 1-on-1 concierge chat widget for Next.js, powered by Supabase Realtime and routed directly to your Slack channel.

Perfect for startups, independent developers, and portfolios seeking a beautiful, zero-cost, private alternative to expensive corporate chat services (like Intercom, Zendesk, or Crisp).

Features

• 💎 Vibrant Cyber-Glow Aesthetics: Interactive, gorgeous, glassmorphic UI built with standard Tailwind classes and fluid Framer Motion animations.
• ⚡ Instant Live Transition: Stays in a clean success/waiting screen until you reply from Slack, then instantly morphs into a live back-and-forth chat!
• 🔔 Push-to-Slack Alerts: Every inquiry is instantly pushed to your Slack channel as a new conversation/message.
• 🔐 Guarded Build Safety: Zero-crash build-time compilation module safety, allowing server routes to build cleanly even if build environments lack database secrets.

🛠️ Installation & Setup

Install the package in your Next.js application:

npm install akachat

Ensure you have the required peer dependencies installed:

npm install @supabase/supabase-js framer-motion

🟢 Easy Installation (Entry-Level / Junior Developers)

Get instant, 100% free contact form submissions sent directly to your team channel in Slack. No database needed!

1️⃣ Generate Slack Bot API Keys

1. Create a workspace on Slack if you don't have one.
2. Go to api.slack.com/apps, click Create New App -> select From scratch, name it, link it to your workspace, and click Create App.
3. Under OAuth & Permissions, under Scopes -> Bot Token Scopes, add the `chat:write` bot token scope. Next, find the OAuth Tokens for Your Workspace section, click Install to Workspace (first click the install button followed by the name of the workspace, and then authorize the permission by clicking Allow).
4. Copy the generated Bot User OAuth Token (starts with `xoxb-`) and save it.
5. In your Slack app, under the Channels section, create a new channel and name it. Right-click the channel name, click on Copy, and select Copy Link. Extract and copy the Channel ID from this link (starts with `C`, e.g., in `https://soulair-63972.slack.com/archives/C0BAT1CRZ1D` it is only `C0BAT1CRZ1D`).
6. Add these credentials to your .env.local file:

   SLACK_BOT_TOKEN=xoxb-11331287160275-11380419821046-R79wRhowRdgLnx6ewbsMDxc8
   SLACK_CHANNEL_ID=C0BAT1CRZ1D

7. Important: In your Slack channel, type /invite @YourBotName to allow the bot to post messages.

2️⃣ Select Integration Option

📍 Option A: Pre-built Live Chat Widget (Zero-JS Setup)

Simply import and drop the widget into any Next.js Page or Component. It features visual styling and fits right in!

'use client';

import LiveChatWidget from 'akachat';

export default function ContactPage() {
  return (
    <div style={{ maxWidth: '600px', margin: '2rem auto' }}>
      <LiveChatWidget 
        companyName="Your Company"
        accentColor="#4f46e5"
        welcomeTitle="Send us a Message"
      />
    </div>
  );
}

📍 Option B: Traditional HTML POST Form (No JS / Direct)

Already have a form? Just point its action directly to our API endpoint.

<!-- ⚠️ REQUIRED: The form action MUST point to /api/chat and method MUST be POST -->
<form action="/api/chat" method="POST">
  <!-- ⚠️ REQUIRED: Redirects back to your website page (change value to your target route) -->
  <input type="hidden" name="redirect" value="/" />
  
  <!-- 💡 CUSTOMIZABLE: Design and inputs are of your choice, name attributes are what the API parses -->
  <input type="text" name="name" placeholder="Your Name" required />
  <input type="email" name="email" placeholder="Your Email" required />
  <textarea name="message" placeholder="Write your message..." required></textarea>
  
  <!-- ⚠️ REQUIRED: Submit button -->
  <button type="submit">Submit Inquiry</button>
</form>

And that's it! Any submissions will land directly in your Slack channel. 🎉

🔵 Advanced Interactive Live Chat (Senior / Full-Featured Setup)

Turn your standard contact page into an interactive, real-time live chat widget. When you reply in Slack, your customer sees it instantly!

1️⃣ Setup Supabase Database & Realtime

We use Supabase Realtime to stream messages between the client browser and Slack.

1. Create a free project on Supabase.
2. Open your SQL Editor in Supabase and execute the following query:

   -- Create messages table
   create table messages (
     id uuid default gen_random_uuid() primary key,
     session_id text not null,
     sender text not null, -- 'user' or 'admin'
     text text not null,
     created_at timestamp with time zone default timezone('utc'::text, now()) not null
   );
   
   -- Enable Realtime Replication
   alter publication supabase_realtime add table messages;

3. Retrieve your keys from Settings ➡️ API and add them to your .env.local:

   NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

2️⃣ Connect Custom Forms with the React Hook

Use our custom React Hook to bind your existing HTML form. It intercepts the submit event, handles the AJAX request under the hood, and automatically switches the UI to the Live Chat Box without full page reloads!

'use client';

import LiveChatWidget, { useLiveChat } from 'akachat';

export default function InteractiveContact() {
  // ⚠️ REQUIRED: You must extract isActive and handleFormSubmit from the hook
  const { isActive, handleFormSubmit } = useLiveChat();

  return (
    <div className="contact-box"> {/* 💡 CUSTOMIZABLE: Container div/styling is of your choice */}
      {/* ⚠️ REQUIRED: Conditionally show widget when active, else show custom form */}
      {isActive ? (
        // The widget will render here, starting in wait mode until you reply!
        <LiveChatWidget showOnlyWhenActive={true} companyName="Your Company" />
      ) : (
        // Your custom form goes here:
        // ⚠️ REQUIRED: The form must use onSubmit={handleFormSubmit}
        <form onSubmit={handleFormSubmit}>
          {/* 💡 CUSTOMIZABLE: All inputs inside the form (design, placeholders, layout) are of your choice */}
          <input type="text" name="name" placeholder="Name" required />
          <input type="email" name="email" placeholder="Email" required />
          <textarea name="message" placeholder="Message..." required></textarea>
          
          <button type="submit">Send Inquiry</button>
        </form>
      )} {/* ⚠️ REQUIRED: Closing conditional tags is important to maintain layout */}
    </div>
  );
}

3️⃣ Activate Slack Webhook (Events API) 🔔

Because back-and-forth chatting requires Slack to notify your Next.js application of your replies:

1. Add the channels:history bot token scope under OAuth & Permissions in the Slack App Console and reinstall the app.
2. In the Slack App Console, click on Event Subscriptions in the left sidebar.
3. Toggle "Enable Events" to On.
4. In the Request URL text box, enter your webhook URL: https://<YOUR_DOMAIN>/api/webhook/slack
5. Under Subscribe to bot events, add the message.channels event.
6. Save Changes.
7. Secure your Webhook (Highly Recommended): In the Slack App Console, go to Basic Information, copy the Signing Secret under App Credentials, and add it to your .env.local:

   SLACK_SIGNING_SECRET=your_signing_secret_here

   This cryptographically secures your webhook route and prevents unauthorized requests from posting messages to your database.

💡 For Local Testing: Use a tunnel service like ngrok or Localtunnel to get a public URL (e.g., https://xxxx.ngrok-free.app/api/webhook/slack) to register with Slack!

🎨 Customization Guide

You can customize the styling, text, and colors of <LiveChatWidget /> to integrate it seamlessly with your design system.

Widget Configuration Properties

| Property | Default Value | Description | | :--- | :--- | :--- | | companyName | 'Company Name' | Displays in headers, placeholders, and chat footnotes. | | accentColor | '#4fd1c5' | Primary brand color (used for buttons and user chat bubbles). | | secondaryColor | '#63b3ed' | Secondary theme color used in gradient accents. | | backgroundColor | 'rgba(10, 15, 30, 0.95)' | Background styling of the chat box. | | textColor | '#ffffff' | Main titles and admin chat bubble text color. | | welcomeTitle | ' Inquiry' | Initial title shown above the prebuilt form fields. | | welcomeDescription | 'Receive a response in less than 5 minutes!' | Subtitle text displayed below welcomeTitle. | | waitingTitle | 'Message Sent!' | Title shown while waiting for an admin to reply. | | waitingDescription | 'Thank you for reaching out!...' | Paragraph shown on the waiting/success screen. | | showOnlyWhenActive | false | If true, hides the widget completely until an active session begins. | | containerClassName | '' | Additional CSS classes for the main wrapper. | | inputClassName | '' | Custom CSS classes to override inputs. | | buttonClassName | '' | Custom CSS classes to style buttons. |

💬 How it works at runtime

1. User Submits: Customer submits your form. The page stays intact, and the form transitions into a gorgeous waiting bubble.
2. Alert Received: You receive an alert in your Slack channel with the user's name, contact details, and their query.
3. Reply: Replying directly to that message thread in Slack notifies your Next.js webhook, logging the message in Supabase.
4. Live Chat: The user's screen instantly morphs into a real-time, high-fidelity chat workspace.

License

MIT License. Created with 🤖 by Akash (ALTCode AI Software Engineering Collective).