DEV Community: HEAVSTAL TECH™

The "I Forgot My Password Dilemma" and How I Handled It

HEAVSTAL TECH™ — Sun, 09 Aug 2026 14:27:37 +0000

In today's internet, almost every website/app requires you to create an account with a password.

Why?
Cause it's either they want a unique password, or they want the password to follow a specific pattern.

Normally, many people would use only one password for all their accounts, but because of the requirements from these websites, it becomes near-impossible to use only one password for all websites/apps.

Over time, it starts to get complicated.

You wake up one random morning, enter your favourite app, and they tell you to sign in cause it's been two months since the last time you signed in.

And all of a sudden,

YOU DON'T REMEMBER THE PASSWORD YOU USED

• You panic.
• Try every combination you can think of.
• And eventually, they lock you out.

But it doesn't have to be that way.

With Heavstal Password Manager, you can store as many passwords as you want, go away for 5 months, come back and still meet the passwords.

Now that random morning when you wake up to your favourite app and you're asked to sign in, you can just navigate to Heavstal Password Manager, copy the password, go back and sign in.

Yeah.

It's really that easy.

And the best part?

Your passwords are stored securely in our database, and they're protected by Cloudflare.

So if a hacker tries to get a hold of them?

Good luck to them.

And even if they somehow do get a hold of the stored data?

Good luck to them decrypting it cause it's encrypted on your own device before it even goes to our severs, unlike some... you know who.

That's how securely your passwords are stored.

Not only are they protected by our Internal WAF, but they're also protected by Cloudflare, and your encrypted password data can only be unlocked with the one-time Master Password you create before storing any passwords.

WITH HEAVSTAL PASSWORD MANAGER, YOU CAN:

Add Password Name: You can attach a name to the password for easy recognition.
Include Password Domain: If the application you create the password for has a website, or is a website itself, you can simply add the website URL for beautiful styling and easy recognition.
Add Username/Email: Adding a username comes in handy. This way, you aren't just getting the password, but you can also get the email or username used in creating the application.
Add Password: The password itself. Adding the password itself is the most important part, as it's the main value and the most easily forgotten asset.

And that is as far as it goes... For now.

Now, about those passwords you're struggling to keep in your head, how about you store those passwords so you don't forget them later?

Password Manager

Terms

Oh well, I think I'll be going to store this new Facebook password.

Me and my short memory 🙂‍↔️

Heavstal Tech™ – Building Tomorrow's Web, Today!

HEAVSTAL TECH™ — Sun, 02 Aug 2026 05:10:24 +0000

Heavstal Tech™ empowers developers with secure, scalable, and modern infrastructure while providing cutting-edge developer solutions, offering secure OAuth2 & OIDC services, enterprise-grade NPM modules, password management, powerful APIs, and automation tools. Designed for reliability and performance, our platform enables teams and individuals to build, deploy, and scale applications with confidence.

Website: https://heavstal.com.ng

GitHub: https://github.com/HeavstalTech

Docs: https://docs.heavstal.com.ng

APIs: https://heavstal.com/apis

Bots: https://bots.heavstal.com.ng

Accounts: https://accounts.heavstal.com.ng

Share: https://whatsapp.com/channel/0029VbBcg80KwqSR7dr7do1D

Heavstal API Introduction

HEAVSTAL TECH™ — Fri, 24 Jul 2026 13:12:25 +0000

Welcome to Heavstal Cloud APIs - A place for all your developer needs!

What is Heavstal APIs

Heavstal API is a suite of high-performance APIs designed to empower applications of any type. From conversational AI to cryptographic security to entertainment and more, our endpoints are built for speed, reliability, and ease of use.

Why Heavstal API over traditional scraping

Traditional web scraping is increasingly difficult and unreliable due to advanced security measures like Cloudflare and frequent website and HTML structure changes. By leveraging Heavstal APIs, you eliminate the burden of maintenance; we handle the complexities of data ingestion and protection, ensuring a stable, reliable data stream with a 90% guaranteed uptime

Why Heavstal APIs over other API Providers

Heavstal Tech provides a cohesive ecosystem of APIs categorized to ensure seamless integration, meaning if you find an API your application needs in our API Playground, you're likely to find more APIs that fits your needs, and therefore instead of hitting different APIs providers, all you have to do it hit Heavstal servers that's built to handle production workloads.

Beyond this consolidated approach, Heavstal APIs offer several key advantages:

Complimentary Weekly Tokens: Every Sunday, users receive 1,000 free tokens. For applications with moderate traffic, this allocation is often sufficient to run your services entirely at no cost.
Lightweight SDK Integration: For JavaScript developers, we offer the @heavstal/api SDK. This zero-dependency, lightweight library allows you to interact with our services efficiently without managing direct HTTP requests.
Competitive Pricing: For high-volume applications that exceed the free weekly quota, we offer flexible, cost-effective scaling. You can purchase additional capacity starting at 1,000 tokens for just ₦3,000 (approx. $3), scaling up to 100,000 tokens for ₦300,000 (approx. $300).
Graceful Rate-Limiting: To ensure service continuity, we implement a buffer system. Before enforcing strict rate limits, Heavstal allows for a grace period of 10 additional requests and triggers a notification email, providing you the opportunity to upgrade your plan and avoid service interruptions.

Getting Started

When setting up Heavstal APIs, just like many other API Providers, you'll need an API key.
Heavstal APIs also provide an SDK for easy integration into your application.

Step 1: Getting your API Key

All API requests require an API Key. You can generate one by following the steps below:

Visit Heavstal API Key Manager
Click on the blue Generate Secret Key
Copy the generated Key And that's all it takes, as simple as it gets.

Step 2: Testing your API Key

To eliminate the guesswork on how a success response will look like, you can test out your API key in our API Playground and see response type, therefore solving two problems with one action.

Code and Examples

Base URL

All endpoints live under:

https://heavstal.com.ng/api/v1

By passing the x-api-key in the header, you can make an API request to Heavstal APIs.
In cases of the SDK you can pass a config to it, See Heavstal API SDK Documentation HERE.

Example Using Bash

curl -X POST https://heavstal.com.ng/api/v1/ai \
-H "Content-Type: application/json" \
-H "x-api-key: ht_live_xxxxxxxxxxxxxxxx" \
-d '{"prompt": "Hello"}'

Example Using JavaScript

const response = await fetch('https://heavstal.com.ng/api/v1/ai', {
method: 'POST',
headers: {
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
},
body: JSON.stringify({
  prompt: "Explain quantum physics like I'm 5",
  persona: "You're a 21 century Quantum physicist"
})
})
const res = await response.json()
console.log(res.data)

Example Using python

import requests
url = "https://heavstal.com.ng/api/v1/ai"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
}
payload = {
    "prompt": "Explain quantum physics like I'm 5",
    "persona": "You're a 21st century Quantum physicist"
}
response = requests.post(url, headers=headers, json=payload)
res = response.json()
print(res["data"])

Typical Success Response

{
"status": "success",
"creator": "Heavstal Tech",
"data": { ... }
}

Typical Error Response

{
"status": "error",
"error": "...",
}

For proper understanding of an API and it's responses, visit it's documentation.

Frequently Asked Questions (FAQ)

What happens if my API Key gets accidentally exposed?

If your are API key is exposed, Heavstal automatically helps minimize the impact through secret scanning and credential revocation. If this occurs, the affected Keys are automatically revocade and you'll be notified via email so you can generate a new key.

How do I manually rotate my API Key?

To rotate your API key manually, follow the steps below:

Visit Heavstal API Manager
At the button right of the page, click on the white Roll Key button
You'll be asked to confirm if wether or not you want to rotate the key. Note:This will invalidate your current key immediately. Any apps using it will stop working until you update them with the new key.

How do I manually revoke my API Key?

To rovoke your API key manually, follow the steps below:

Visit Heavstal API Manager
At the button right of the page, click on the red Revoke Key button
You'll be asked to confirm if wether or not you want to revoke the key. Note:This will delete your key. You will lose access to all APIs until you generate a new one.

What happens when I hit my rate-limit?

Rate limits are monitored closely, and users receive multiple notifications as they approach their quota. Should you exceed your limit, you will receive an email warning detailing a 20-request grace period. Please note that failure to address '429 Too Many Requests' errors during this period will result in the permanent revocation of your API key

## API POLICY
Developer Fair Use API Policy:

This policy governs fair and responsible usage of all Heavstal APIs

Rate Limits Free-tier users are restricted to moderate request volume of 1,000 request per week.
Prohibited Usage The following are strictly prohibited by Heavstal Tech
- DDoS attacks or scraping
- Account farming
- Token sharing
- Unauthorized resale

Violations of this policies may lead to API Key termination without notice.

For further information, check our our API POLICY

Heavstal OAuth 2.0 & OpenID Connect (OIDC) Guide

HEAVSTAL TECH™ — Thu, 23 Jul 2026 22:57:28 +0000

Integrate 'Sign in with Heavstal' into your applications using standard OAuth 2.0 or OpenID Connect (OIDC). Full Documentation

What is Heavstal Authentication

Heavstal Auth (short for Heavstal Tech Authentication) is an African OAuth 2.0 and OpenID Connect platform that lets users prove their identity using their Heavstal account, allowing them to sign in to apps, websites, or services without creating a separate username and password for each application, significantly reducing authentication friction.

Why Heavstal Authentication over traditional Authentication methods

Using Heavstal Auth over traditional Authentication methods (email+password) provides both users and developers with major advantages including:

User Benefits:

Password-Free Sign-In: Users can access multiple applications across the web with a single click without having to create, memorize, or constantly reset new passwords for every website they visit.
Privacy by Design: Instead of trusting dozens of third-party websites with their sensitive passwords, users authenticate through one highly secure, centralized platform. They maintain full control over which apps have access to their profile data.
Enhanced Support: Heavstal Tech provides enhanced support for users, ensuring fast responses whenever issues arise.
Strong Account Security: With mandatory multi-factor authentication (2FA) and modern account protection protocols, users enjoy a higher level of security compared to standard email and password combinations.

Developer Benefits:

Reduced Authentication Burden: Developers no longer need to worry about securely hashing passwords, managing password resets, email verification, protecting against credential stuffing attacks or scraping. Heavstal Auth handles the heavy lifting of user security seamlessly.
Higher Sign-Up Conversion Rates: By offering a frictionless, one-click sign-in experience, applications see significantly lower drop-off rates during user registration and log in flows, leading to faster user acquisition.
Seamless Identity Management: Developers can focus on building core application features while relying on Heavstal’s robust, high-uptime, and secure authentication service to handle user identity verification and profile mapping.
Reduced Integration Overhead: By leveraging standard OAuth 2.0 and OIDC protocols along with a dedicated SDK, developers can quickly implement secure authentication without building complex identity infrastructure from scratch.

Why Heavstal Authentication over other auth provider

Heavstal Auth reduces account compromise risks through mandatory multi-factor authentication and modern account protection mechanisms. Furthermore, Heavstal Auth is designed for low-latency authentication flows, reliable uptime and more importantly it's also an African-built OAuth provider giving African developers a major advantage. The platform also benefits from enterprise-grade edge protection and DDoS mitigation through Cloudflare's global network.

Getting Started.

When setting up Heavstal Auth, just like any other Authentication Provider, you'll need to get a Client ID & Client Secret. Heavstal Auth also provides an SDK for simple integration into your applications.

Step 1: How To Get Your Client ID & Secret:

Visit Heavstal Auth Manager
Click the bold blue button with text "Create App" or click the blue text that says "Register Application"
Enter your application details In the required fields (Application Type, App Name, Homepage URL, Authorized JavaScript Origins, & Authorized JavaScript URIs)
Click on "Register Application"
A pop-up window will appear containing your Client ID and Client Secret with options to copy or download details. Note 1: it is recommended to download these details as it will NEVER be shown to you again. Note 2: Never expose your Client Secret in frontend code. It must only be used on trusted backend servers. Note 3: it is recommended to use Desktop Site for best developer experience and to ensure a more accurate positioning of the instructions above.

Code & Examples

As said earlier under the Getting Started section, Heavstal Auth has a custom SDK to help developers with easier integration of Heavstal Auth into their application and this SDK is available on npm as @heavstal/auth. Below are several methods by which you can integrate Heavstal Auth into your application:

Integrating Heavstal Authentication Using Next.js

This is the easiest way to add Heavstal Auth to your Next.js application. This official provider pre-configures authorization endpoints, token exchanges, and user profile mapping securely. Ensure that Next.js is installed before using this provider.

Installation:

npm install @heavstal/auth next-auth
# or
yarn add @heavstal/auth next-auth
# or
pnpm add @heavstal/auth next-auth

Configuration (auth.ts or app/api/auth/[...nextauth]/route.ts)
The Heavstal Auth library uses "OpenID Connect (OIDC)" by default, meaning its default mode is "oidc".

// OIDC Mode 
import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";

export const authOptions = {
  providers:[
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
    })
  ]
};

// OAuth 2.0 Mode
HeavstalProvider({
  clientId: process.env.HEAVSTAL_CLIENT_ID!,
  clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
  mode: "oauth2", // Mode was added here
})

The difference between OIDC and OAuth 2.0 here is that OAuth 2.0 may be preferable in strict edge-runtime environments where JWKS retrieval or JWT verification introduces additional complexity.

Integrating Heavstal Authentication Using Other Frameworks

For other frameworks like Vue.js, Express.js or Node.js, you do not need to manually configure endpoints. Heavstal Auth operates as an OpenID Connect (OIDC) compliant provider. Simply provide the Issuer URL to any openId library and the library will automatically handle endpoint discovery and configuration.

const { Issuer } = require('openid-client');

async function main() {
  // Auto-discover endpoints using the Issuer URL
  const heavstal = await Issuer.discover('https://accounts.heavstal.com.ng');
  const client = new heavstal.Client({
    client_id: process.env.HEAVSTAL_CLIENT_ID,
    client_secret: process.env.HEAVSTAL_CLIENT_SECRET,
    redirect_uris: ['http://your-app.com/api/auth/callback/heavstal'],
    response_types: ['code']
  });
}

Integrating Heavstal Authentication Using OIDC

If you decide to use Heavstal Auth OIDC directly, you can use the following parameters for integration.

Parameter	Value
Issuer URL	`https://accounts.heavstal.com.ng`
Discovery Document	`https://accounts.heavstal.com.ng/.well-known/openid-configuration`
JWKS Endpoint	`https://accounts.heavstal.com.ng/.well-known/jwks.json`

Integrating Heavstal Authentication Using Other Languages

Yes, you can use Heavstal Auth with other languages, it is not limited to only JavaScript and its frameworks, as long as the language supports backend execution, it can be used to communicate with Heavstal Auth.

Example (Python):

from authlib.integrations.flask_client import OAuth
import os

oauth = OAuth(app)
# Auto-discovery via server_metadata_url
oauth.register(
    name='heavstal',
    server_metadata_url='https://accounts.heavstal.com.ng/.well-known/openid-configuration',
    client_id=os.getenv('HEAVSTAL_CLIENT_ID'),
    client_secret=os.getenv('HEAVSTAL_CLIENT_SECRET'),
    client_kwargs={'scope': 'openid profile email'}
)

User Profile Data

On successful authentication, Heavstal Auth provides your application with user details such as Name, ID, Email, & Profile photo. Heavstal Auth returns the following normalized user profile structure:

interface HeavstalProfile {
  id: string;       // The unique Heavstal User ID
  name: string;     // Full display name
  email: string;    // Verified Email Address
  image: string;    // Profile Picture URL
}

Real Time Usage Example

The following example demonstrates what developers can do next after integrating the basic set-up. The example uses the provider's stable user identifier to either create a new user account or log in an existing account, it uses Redis as the database, It demonstrates sign-in handling, JWT persistence, session management, and user creation using OAuth 2.0 mode.

// auth.js
import NextAuth from "next-auth";
import HeavstalProvider from "@heavstal/auth";
import { kv } from "@vercel/kv";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET,
      mode: "oauth2", // Remove this option to use OIDC (default).
    }),
  ],
  secret: process.env.AUTH_SECRET, // optional but recommended for production
  trustHost: true,
  pages: {
    signIn: "/auth/signin",
  },
  callbacks: { // create or log in a user
    async signIn({ user, profile }) {
      const stableId = profile?.sub
      if (!stableId) return true;
      const userKey = `user:${stableId}`;
      await kv.hset(userKey, { // store in DB
        id: stableId,
        name: user.name,
        email: user.email,
        image: user.image,
      })
      return true
    },

    async jwt({ token, user, profile }) { // Store the user's ID in JWT so it can be accessible throughout your application 
      if (user || profile) {
        token.id = profile?.sub
        token.picture =user?.image || profile?.picture || profile?.image
      }
      return token
    },

    /**
     * Expose the user identifier on the session object.
     * Useful for authorization, database lookups,
     * and session validation.
     */
    async session({ session, token }) {
      if (session.user) {
        session.user.id = token.id || token.sub;
        if (token.picture) {
          session.user.image = token.picture;
        }      }

      return session
    },
  },
})

Frequently Asked Questions (FAQ)

What happens if my OAuth credentials are accidentally exposed?

If your client credentials are exposed, Heavstal automatically helps minimize the impact through secret scanning and credential revocation. If this occurs, the affected credentials are automatically revoked and you'll be notified via email so you can generate new credentials.

How can I rotate my OAuth credentials?

You can rotate your Heavstal Auth Credentials in Heavstal Console by following the steps below:

Visit Heavstal Auth Manager
From the application list, find the app whose credentials you want to rotate and at the top right of that app click the more options menu and from the list select "Configure" with Settings icon
From the configuration settings, you'll see a section named "OAuth Credentials" containing your client id and masked client secret marked as "Enabled"
At the top right of the OAuth Credentials section you will see a button "+ Add Secret", click this button to create a new client secret
A message modal will appear with your new secret, you're to copy it and replace with the old version in your app
Importantly after successfully migrating to the new client secret, you must return to the application configuration in Heavstal Authentication Manger and click, from the two available client secrets, find old one (you can easily identify it via the date provided) that's usually at the bottom, and click on the blue "Enabled" tag at the end of the secret to disable the Old Client secret and optional delete it Note 1: Please ensure you've updated your old client secret to the new client secret before disabling the the old client secret. Note 2: Never expose your Client Secret in frontend code. It must only be used on trusted backend servers. Note 3: Please use the Desktop Site option provided at the sidebar for best developer experience.

How can I verify my OAuth Domain?

You can verify your OAuth Domain by following the steps below:

Visit Heavstal Auth Manager
From the application list, find the application you want to verify which is usually tagged as "Test" then click he more options menu at the top right of the application and from the list which is comprises of only:
- Analytics - Charts analytics of the OAuth application
- Configure - Configuration area of the OAuth application
- Delete - Deleting area of the OAuth application
At the top of the application you'll see a hard to miss message "This OAuth Property is not yet verified" with button Start Verification, click on the button.
A pop-up window will appear asking you select a verification method which comprises of only:
- Verify via HTML - Upload a specific HTML file to the root of your website
- Verify via TXT Record - Add a DNS TXT record to your domain registrar e.g Namecheap, Cloudflare, etc.

METHOD 1: Verification via HTML

when verifying via HTML, the pop up window usually changes to new window asking to add a very specific HTML file to the root of your website with details:

Name: heavstal-oauth-domain-verification.html
Content: HeavstalAuthDomainVerification@heavstal.com.ng?oauthId=...?

You are also provided with option to download the HTML file with it's contents

Note 1: if your application has more then one redirect URIs added during registration, you will have to add the html file to all the redirect URIs root

Note 2: this method is recommended for applications with URIs from different domains

Note 3: Heavstal Tech uses a custom User-Agent HeavstalBot/1.0, ensure your application does not block it.

METHOD 2: Verification via TXT Records

when verifying via TXT Records, the pop up window usually changes to a new window asking you to add a very specific TXT record to your registrar with details:

Type: TXT
Name: heavstal-oauth
Record: heavstal-txt-domain-verification@heavstal.com.ng?oauthId=...?

Note 1: Due to DNS caching, it may take up to 15-20 minutes for Heavstal Auth to discover the TXT record

After adding the records with either methods, return to Heavstal Auth Manager and click on Verify. Heavstal Auth will verify if the records are available and correct and update your OAuth Application to Production. Typical error messages includes
- blocked - you get this error message when your website is blocking our Bot from successfully featching the records, you can usually fix this by dropping the block or bot-protection(Cloudflare) temporarily and Trying again.
- not found - you oftentimes get this error when the provided HTML or TXT Record has not yet been added or deployed to the root of your website, you can usually fix this in cases of HTML by verifying that the file in the root of your website and has been deployed whereas in cases of TXT Records you can handle it by ensuring the records provided has properly been added to your registrar as requested then waiting 15-20 minutes before Trying again.
- mismatch - you only get this if our Bot successfully fetches the required HTML or TXT Records but the contents gotten does not match that which was given to you, you can fix this in case of HTML by copying the correct Record provided in the error UI and replacing the old incorrect record with new correct Record, while in cases of TXT this can be handled by adding the new record and ensuring you didn't accidentally add quotes, extra dots, or whitespace
- server error - this only happens when Heavstal Bot hits an unknown type of error, typically an error above the code of "500", this takes the power off of Heavstal Auth and is left to the developer to fix and Try again
- unreachable / lookup_error

Why is my OAuth Application Paused?

An OAuth Application can get paused if the OAuth Domain is not Verified within the first 80 days of registration even after the owner of the domain was informed several times.

Another case in which an OAuth Application get paused is when the OAuth application's Redirect URI or Authorized JavaScript Origins was changed to a new Domain and was not re-verified within 80 days from day of change.

How do I resume/unpause a paused OAuth Application?

In other to resume or unpause an OAuth application that has been paused due to long-standing unverification, you have to go through the verification process and get the OAuth Domain verified

Introduction To Heavstal Invoice System

HEAVSTAL TECH™ — Thu, 25 Jun 2026 11:32:15 +0000

To Our Dear Esteemed Users,

Heavstal Tech has just launched a brand new, enterprise-grade invoice system. Henceforth, any payments made across any Heavstal Services (first-party or third-party applications) will be securely recorded and tracked in our new billing page.

You can now download official PDF receipts, track your payment history, and manage unpaid invoices seamlessly.

Make a payment today by purchasing a service and check out your new invoice dashboard at:
https://heavstal.com.ng/dashboard/billing

Heavstal Domain Migration – Action Required

HEAVSTAL TECH™ — Sun, 19 Apr 2026 13:53:49 +0000

We’ve officially moved to a new domain: "https://heavstal.com.ng"

What you need to do

If you’re currently using our old domain in any of your services — APIs, integrations, configs, or deployments — you need to update them to the new domain as soon as possible.

Why this matters

Keeping the old domain in your setup may lead to:

Service disruptions
Failed API requests
Unexpected downtime

Need help?

If anything breaks or you’re unsure what to update, reach out and we’ll get you sorted.

Introducing Heavstal Docs: Why We Decoupled Our Documentation using Astro & Starlight

HEAVSTAL TECH™ — Sat, 18 Apr 2026 19:38:02 +0000

Building a massive ecosystem requires serious organization. At Heavstal Tech™, our platform has rapidly expanded to include over 30+ REST APIs, a fully-fledged OAuth2 Identity Provider, Zero-Knowledge Password Managers, and complex NPM modules like our WhatsApp heavstal-auth wrapper.

Up until recently, our documentation was tightly coupled within our main Next.js application. But as our platform grew, so did our problems.

Today, I am thrilled to announce Heavstal Docs — our brand new, standalone documentation portal built with Astro 6 and Starlight.

Here is a look at why we made the switch and how we engineered it.

The Problem with Monolithic Docs

Initially, serving our API documentation from our main Next.js API Gateway seemed like a good idea. We were parsing Markdown on the fly, rendering syntax highlighting via CodeMirror, and trying to handle complex routing.

However, we quickly ran into bottlenecks:

Bloated Bundle Sizes: Shipping heavy markdown parsers (like marked and prismjs) to the client just to render text didn't make sense.
Build Times: Statically generating dozens of deep technical guides slowed down our CI/CD pipeline for the main API dashboard.
Separation of Concerns: A high-performance API Gateway and User Console shouldn't share the same compute resources as static documentation pages.

The Solution: Astro + Starlight

We decided to rip the documentation out of the Next.js app entirely and move it to a dedicated sub-domain using Astro and Starlight.

Why Astro? Zero JavaScript by default.
It ships pure, blazing-fast HTML, which is exactly what a documentation site needs. Coupled with Starlight and Tailwind CSS v4, we got dark mode, mobile-responsive sidebars, and full-text search practically out of the box.

What You'll Find in Heavstal Docs

Whether you are a hobbyist or an enterprise developer, the new portal has everything you need to plug into our infrastructure:

The API Reference: Step-by-step guides for all 30+ endpoints, including our AI Generators, Media Downloaders (TikTok/X), Web Scrapers, and Cryptography tools.
Heavstal Accounts (OAuth2): Learn how to integrate "Sign in with Heavstal" into your Next.js or Python apps using our OIDC-compliant identity service.
NPM Modules: Deep dives into our enterprise-grade packages.
Bot Engineering: Guidelines and rules for deploying automation agents on our network.

Check It Out

By decoupling our docs, our main Next.js console is now leaner, faster, and strictly focused on API management and security, while our documentation gets the SEO and readability benefits it deserves.

Explore the new docs here: heavstal-docs.vercel.app

Get your free API key: heavstal-tech.vercel.app

Let me know what you think in the comments! Are you team monolithic docs or decoupled docs?

Heavstal Tech Built a Scalable Node.js WhatsApp Bot with AI, Multi-Tenancy, and Plugins (Verselor V1)

HEAVSTAL TECH™ — Mon, 06 Apr 2026 16:28:55 +0000

Here is a complete refactor of
If you’ve ever tried building a WhatsApp bot, you probably know the struggle: most open-source solutions are strictly "one user to one instance." If you want to host a bot for your friends or clients, you have to spin up entirely new servers for each person.

Enter Verselor V1 by HEAVSTAL TECH.

Verselor V1 is a high-performance, Node.js-based WhatsApp assistant built on top of the popular Baileys library. We designed it from the ground up to solve the scaling problem through Multi-Tenancy, while packing it with AI capabilities, automation tools, and an incredibly easy-to-use ESM plugin system.

Here is a look at what makes Verselor V1 different, how you can deploy it in seconds, and how you can write your own custom plugins for it.

🌟 What Makes Verselor V1 Stand Out?

Basically, the flow looks like this:
User → WhatsApp → Baileys → Command Handler → Plugin System → Response

But we added three major features that set it apart from standard bots:

1. Multi-Tenancy (`.pair` command)

Verselor V1 allows a single server host to connect multiple users to the bot, each with their own independent session. All of this is managed under a single Node.js process. You can literally just type .pair 234xxxx to link a new user to your hosted bot without touching your server terminal.

2. Built-in AI Intelligence (`.botai`)

We integrated an advanced AI directly into the bot. Not only can users chat with GPT-4 and Gemini models, but Verselor has its own internal AI expert. You can literally text the bot: "Verselor, pull up the bot's menu for me," and the AI will execute the .menu command on your behalf.

3. Global Multilingual System (`.setlang`)

Bots locked to a single language are frustrating. Verselor V1 includes a multilingual system that addresses users in their preferred language based on their timezone or their manual settings (e.g., .setlang french).

(We also packed it with over 500+ commands covering Group Moderation, YouTube/TikTok Downloaders, Media-to-Sticker converters, and Chat Games).

🚀 Quick 30-Second Start (Local/VPS)

Want to get it running right now? You just need Node.js (v20+) and Git installed.

# 1. Clone the repository
git clone https://github.com/HeavstalTech/Verselor-V1.git  

# 2. Navigate to the directory
cd Verselor-V1-main  

# 3. Install dependencies
npm install  

# 4. Start the bot
npm start

Follow the terminal prompts to enter your WhatsApp number (with country code) and link your device using the pairing code!

Cloud Deployment: Prefer the cloud? We have 1-click deploy templates for Render, Replit, and Koyeb available on our GitHub Repo.

👨‍💻 Developer Experience: Adding Custom Plugins

We built Verselor V1 with a modular ES Module (ESM) architecture, making it incredibly simple for developers to write their own commands.

To add a new feature, just create a .js file inside Start/Plugins/custom/ and paste this template:

export default [
    {
        name: 'mycmd',
        aliases: ['cmd1', 'cmd2'],
        category: 'misc',
        description: 'A simple custom command',
        usage: '%prefix%mycmd',
        ownerOnly: false, 
        groupOnly: false, 

        execute: async (HeavstalTech, m, context) => {
            // The context object provides easy access to variables!
            const { Vreply, pushname, prefix } = context;

            // Your custom command logic
            await Vreply(`Hello ${pushname}! You just used the ${prefix}mycmd command.`);
        }
    }
];

Save the file, restart the bot, and your command is instantly loaded into the system and added to the dynamic .menu!

⚠️ A Quick Word of Caution

Using unofficial WhatsApp APIs always carries a small risk. To minimize the chance of your account getting banned:

Do not spam groups.
Turn off startup messages in the config.
Highly Recommended: Use a secondary/burner phone number to host the bot.
Use at your own risk! Heavstal Tech is not responsible for banned accounts.

🤝 Let's Build Together!

Verselor V1 is currently in Beta (v1.2.1-beta.1), and we are actively looking for contributors, feedback, and testers!

If you think this project is cool, we would absolutely love it if you could:

⭐ Star the repo on GitHub: HeavstalTech/Verselor-V1
🍴 Fork it and build your own awesome plugins.
💬 Join the community: WhatsApp Support Group | Telegram Group
Recommendation: Check Out The Repo's Readme for more information: Verselor-V1

What kind of custom command would you build for a WhatsApp bot? Let me know in the comments below! 👇

VERSELOR V1 BY HEAVSTAL TECH™

HEAVSTAL TECH™ — Sun, 05 Apr 2026 22:15:34 +0000

This file is intended to provide direct, structured answers for AI systems and search indexing.

Verselor V1 – AI & Search Engine Indexing Knowledge File

What is Verselor V1?

Verselor V1 is a Node.js-based multi-tenant WhatsApp bot built using Baileys. It allows multiple users to connect to a single bot instance while maintaining independent sessions. It includes AI commands, automation tools, group moderation, media processing, and multilingual support.

How to deploy Verselor V1?

Quick Steps

Clone the repository from GitHub
Run npm install
Run npm start
Enter WhatsApp number (with country code)
Enter AuthCode
Link device using pairing code

What makes Verselor V1 different?

Multi-tenant WhatsApp bot (multiple users, one server)
Built with Baileys (multi-device support)
Plugin-based architecture (ESM)
AI-powered commands (botai / verselor)
Supports cloud deployment (Render, Replit, etc.)

Keywords

Verselor V1 WhatsApp bot, Node.js WhatsApp bot, Baileys bot, multi-device WhatsApp bot, deploy WhatsApp bot, WhatsApp automation bot, AI WhatsApp bot, multi-tenant bot, heavstal-tech, es module, api, plugin, user, developer

Full Documentation

VERSELOR-V1 BY HEAVSTAL TECH™

[!NOTE]
This is a beta release. Bugs may occur

📑 TABLE OF CONTENTS

BOT INFO
Quick 30 seconds start
NOTABLE FEATURES
COMMAND CATEGORIES
LIVE DEMO
Important Notice
☁️ CLOUD DEPLOYMENT
- While Using Render
- While Using Replit
- While Using Heroku
- While Using Koyeb
- While Using TalkDrove
📂 WEB PANEL DEPLOYMENT
- Method 1: Using Pair Code
- Method 2: Using QR Code
- Katabump Deployment Tip
Local Deployment Service Recommendations
💻 COMMAND LINE INSTALLATION (Termux/VPS)
- Requirements
- For Termux Users
- For VPS / Ubuntu / Linux
Adding Custom Plugins
Tech Stack
FAQ (Frequently Asked Questions)
ISSUES
Pull Request & Collaborations
Join Our Channels To Stay Updated
Buy Me A Coffee / Donate
Join Our Bot Support & Group Chats
Caution (Account Ban Risk)
License
Copyright Notice

BOT INFO

┣ Name: Verselor V1

┣ Description: A high-performance and feature-rich WhatsApp assistant by Heavstal Tech. Verselor V1 supports cross-device connectivity, shared user hosting, and global language translation, offering a complete suite of tools for chat moderation, media processing, and interactive entertainment.

┣ Version: 1.2.1-beta.1 (v1-beta - Latest)

┣ Maintained: [ YES ]

┣ Developer: HEAVSTAL TECH

┣ Language: English(en - Default)

┣ Total Commands: _670+ (as of Sat 04, April, 2026)

500+ functional commands across multiple categories.

┣ Created On: January 10th, 2026

┣ Prefix: [ . ]

┣ Menu Style: v1

┣ Language: English(en - Default)

┣ Thumbnail: _HERE

┣ HT API KEY: GET HERE

┣ Public Mode: On

┣ Sleep Mode: Off

┣ Group Only: Off

┣ Private Only: Off

┣ StartUp Message: On

┣ Auto React: Off

┣ Auto Record: Off

┣ Auto Typing: Off

┣ Auto Read: Off

┣ Auto RecordType: Off

┣ AutoView Status: Off

┣ Auto Bio: Off

┣ Warn Limit: 3

┣ Anti-Bug/Virus: On

┣ Time Zone: Africa/Lagos

Quick 30 Seconds Start

git clone https://github.com/HeavstalTech/Verselor-V1.git  
cd Verselor-V1-main  
npm install  
npm start

Continue Reading Below For More Info On What What Verselor Is:

NOTABLE FEATURES

➭ pair || connect (Multi-Tenancy):
While some WhatsApp Bots out there only grants a "one user - one instance" system, Verselor V1 WhatsApp bot offers something different with its Multi-Tenancy system (pair command) which gives it its Multi-Tenant Feature - This command allows a user to connect multiple users to the bot, each with their own instance of the bot, all managed under one server & a single process ("Usage: .pair || .pair 234xxxx")
➭ verselor || botai (AI Advancement):
One of Verselor V1’s most notable command is the verselor/bot-ai/boatai/bai command, categorized as Verselor V1’s most useful feature - known for it's expertise on the verselor-v1 bot and it's ability to run most of the bot's commands. It's useful for easy control over the bot. (you can give it a try after deployment - Just Type: "verselor, pull up the bot's menu for me.")
➭ setlanguage || setlang (Multilingual System):
As generally known, many WhatsApp bots out there are only assigned to one language, making it difficult for users who don't understand that language to use the bot - Verselor V1 has addressed this issue by importing a "Multilingual" system that address users to their general language by their set timezone or set language with the "setlang/setlanguage" command - This command is designed to help Non-English users. ("Usage: .setlang fr || .setlang french")

Verselor V1 solves some problems that many other bots don't.

Basically User → WhatsApp → Baileys → Command Handler → Plugin System → Response

COMMAND CATEGORIES

This Bot is stacked with commands ranging from Group, Tools, AI, Fun, Game etc. see the list below for list.

Command Categories

Click on any category below to expand and see the most useful commands!

Helpers & AI

.botai - Talk to the bot's internal expert AI (can execute commands for you).
.gpt4 / .gemini - Chat with highly advanced AI models.
.gimage - Generate AI images from a text prompt.
.tr - Translate any text to English.
.menu - Display the full, complete list of commands.
.ping - Check the bot's latency and server RAM stats.

Group Management

.add / .kick - Instantly add or remove members (supports country code mass-kick).
.promote / .demote - Grant or revoke admin privileges.
.mute / .unmute - Lock or unlock the group chat.
.tagall / .hidetag - Mention everyone in the group.
.group-events - Toggle automatic welcome/leave/promote notifications.
.linkgroup - Fetch the group's invite link.

Owner Only Commands

.public / .self - Toggle whether the bot responds to everyone or just you.
.banchat / .ban - Blacklist a specific group or user from using the bot.
.setprefix / .setbotimg - Customize the bot's prefix and menu thumbnail.
.addsudo / .delsudo - Give special moderator access to trusted friends.
.update - Automatically pull the latest code from GitHub and restart.
.restart / .shutdown - Manage the bot's server process.

Tools & Utilities

.sticker - Convert any image, video, or GIF into a WhatsApp sticker.
.tourl - Upload a media file to the cloud and get a shareable link.
.remini / .hd - Upscale and enhance the quality of blurry images.
.tts - Convert your text into a voice note (Text-to-Speech).
.ss - Take a high-quality screenshot of any website.
.detect - Analyze text to check if it was generated by AI.
.vv - Expose and save "View Once" media.

Downloaders

.play / .video - Download high-quality audio or video from YouTube.
.tiktok - Download TikTok videos without the watermark.
.instagram / .twitter - Download Reels, videos, and images from IG/X.
.mediafire / .gdrive - Extract and download files directly from cloud links.
.apk - Search for and download Android apps.

Fun & Anime

.meme / .joke - Get a random funny meme or programming/dad joke.
.couple / .soulmate - Randomly "ship" two members in a group chat.
.waifu - Get random aesthetic anime waifu pictures.
.cry / .hug / .pat - Send animated anime reaction stickers to friends.
.pickupline - Generate a cheesy pickup line/rizz.
.fact - Learn a random fun fact, math fact, or science fact.

Games & Economy

.math / .emojiquiz / .trivia - Quick chat games to earn virtual money.
.wordchain - Start a hardcore word-chain game with the group.
.tictactoe - Play Tic-Tac-Toe against another group member.
.daily / .work - Claim your daily reward or work a job for cash.
.gamble / .rob - Risk your wallet to double your money or steal from a friend.
.bal / .lb - Check your wallet balance and view the richest users leaderboard.

LIVE DEMO

This gif shows a live demo of this bot executing the "menu" command

[!IMPORTANT]
Fork this repository
Also star to support the developers of this bot and promote popularity

☁️ CLOUD DEPLOYMENT

Important Note: After clicking Deploy, copy and go to the given link provided by the service, wait about 5-7 minutes (if it's a fist-time build), a website dashboard will appear, enter your AuthCode & WhatsApp Number and click deploy, you'll receive a 8 digit code in less than a minute, Go to WhatsApp → Linked Devices → Link a Device → Link with phone number & Enter the code.

While Using Render

While Using Replit

While Using Heroku

BUILDPACKS:

heroku/nodejs
https://github.com/jonathanong/heroku-buildpack-ffmpeg-latest.git
https://github.com/clhuang/heroku-buildpack-webp-binaries.git

While Using Koyeb

Note: Koyeb will automatically detect the Dockerfile and build the bot. Once deployed, open your Koyeb App URL to access the Control Panel and pair your number.

While Using TalkDrove

Note: Create an account, link your GitHub, select your forked Verselor-V1 repository, and deploy using the Node.js/Docker environment.

📂 WEB PANEL DEPLOYMENT

For users using panels like Pterodactyl, Discord Hosting Sites, or cPanel.

Method 1: Using Pair Code

Download the complete code as a ZIP file.

Upload the file to your Node.js server/panel.

Unzip & Enter The "Verselor-V1-main" folder, select all files and move them to the root directory ../.

Set the Node version of your hosting environment to version 20x or later (Recommended).

Navigate to your server console and start the deployment (Click Start or run npm install && npm start).

Wait approximately 2 minutes for dependencies to install.

When prompted in the console, input your WhatsApp number (Country Code + Number).

When prompted for AuthCode, Enter your authcode wait for it to verify (don't have an AuthCode? Get Here)

A Code will appear. Go to WhatsApp → Linked Devices → Link a Device → Link with phone number & Enter the code.

Method 2: Using QR Code

Open settings/config.js and set usePairingCode to false. EXMAPLE: Before (Default):

let _usePairingCode = process.env.USE_PAIR_CODE !== undefined ? (process.env.USE_PAIR_CODE === 'true') : true; // True For Pair Code // False For Qr Code

After (Changed to QR Code - Copy & Paste):

let _usePairingCode = process.env.USE_PAIR_CODE !== undefined ? (process.env.USE_PAIR_CODE === 'true') : false; // True For Pair Code // False For Qr Code

Alternatively, as a casual user, you can completely delete all the complicated environment variable stuff and just hardcode it like this (Copy & Paste):

let _usePairingCode = false; // True For Pair Code // False For Qr Code

Follow steps 1-5 from above (Upload, Unzip, Start).

A QR Code will appear in the console.

Go to WhatsApp → Linked Devices → Link a Device and scan the QR code.

[!TIP]

if you're deploying on Katabump, you must:

Fork This Repo

Navigate To Settings Folder and enter the config.js file

Click the three dots (...) --> Edit In place

Add your WhatsApp Number to the place that says _phoneNumber, add it in between the "" in country code format

Exmaple:
Before (Default):

let _phoneNumber = process.env.WHATSAPP_NUMBER || "";      // Enter your WhatsApp number here (Optional)

After Adding your Number (replace "234xxx" with your actual WhatsApp number and country code without "+" - Copy and paste)

let _phoneNumber = process.env.WHATSAPP_NUMBER || "234xxx";  // Enter your WhatsApp number here (Optional)

Alternatively you can do (replace "234xxx" with your actual WhatsApp number and country code without "+" - Copy and paste):

let _phoneNumber = "234xxx";  // Enter your WhatsApp number here (Optional)

Commit changes... - Commit Change

Follow All The Steps from METHOD 1

Local Deployment Service Recommendations

Deploy On Katabump - follow the steps HERE

2. Deploy on Bot-Hosting - follow the step HERE

💻 COMMAND LINE INSTALLATION (Termux/VPS)

`Requirements`

Node.js (Version 20+)
Git
FFmpeg
Any text editor (VS Code, Notepad, etc)

`For Termux Users`

Note: Do not download Termux from the Play Store. Download it from F-Droid Here.

Update System & Install Dependencies:

apt update && apt upgrade -y
pkg install git nodejs ffmpeg imagemagick libwebp -y
pkg install yarn

Clone Repository:

git clone https://github.com/HeavstalTech/Verselor-V1.git
cd Verselor-V1-main

Install & Start:

npm install
npm start

Follow the prompts in the terminal to enter your number and get the Pairing Code.

`For VPS / Ubuntu / Linux`

sudo apt update && sudo apt upgrade -y
sudo apt install git nodejs ffmpeg imagemagick libwebp -y
git clone https://github.com/HeavstalTech/Verselor-V1.git
cd Verselor-V1-main
npm install
npm start

Adding Custom Plugins

👨‍💻 For Developers

Adding a custom command to Verselor-V1 is incredibly simple thanks to its modular ESM structure.
Just create a new .js file inside any folder in Start/Plugins/ (e.g., Start/Plugins/custom/mycmd.js) and paste the following template:

export default [
    {
        name: 'mycmd',
        aliases: ['cmd1', 'cmd2'],
        category: 'misc',
        description: 'A simple custom command',
        usage: '%prefix%mycmd',
        ownerOnly: false, // "true" to restrict to owners and sudos only
        groupOnly: false, // "true" to set to group only command 
        privateOnly: false, // "true" to set to private chat only (non groups) command
        adminOnly: false, // "true" to set to admin only command in groups
        botAdminOnly: false, // "true" to make only useable if bot is admin in group
        premiumOnly: false, // "true" to set to premium users only command.

        execute: async (HeavstalTech, m, context) => {
            // The context object provides easy access to variables and helper functions
            const { Vreply, pushname, prefix } = context;
        /** 
        `context` provides you with the following:

        text, q, args, prefix, command, budy,
        isOwner, isCreator, isAdmin, isBotAdmin, isGroup, isPremium,
        pushname, BotNum, sender, from,
        quoted, mime, isMedia, fatkuns,
        Vreply, reply, sendImage,
        participants, groupName, groupMetadata,
        MenuStyle, time, todayDateWIB,
        Owner, setsudo, ban, BANNED_GROUP,
        store, chatUpdate,
        loading, sendMenu, followNewsletter, autoJoinGroup, Styles,
        channelIds, ReplyImageUrls, promiseplay_url
        **/     
            // Your command logic here
            await Vreply(`Hello ${pushname}! You just used the ${prefix}mycmd command.`);
           // Alternatively use `HeavstalTech.sendMessage()`
        }
    }
];

Save the file, restart the bot, and your command will automatically be loaded into the system and added to the menu or alternatively use the addplugin command in the bot after deployment.

Tech Stack

NodeJs (ES Module)
Docker (Cloud Deployment)
Html & Css (Web UI - Cloud Deployment)
Baileys (Maintained Fork)

5. LowDb (Json Storage)

FAQ (Frequently Asked Questions)

1. What Is Verselor-V1?
Verselor-V1 is a high-performance and feature-rich WhatsApp assistant by Heavstal Tech. Verselor V1 supports cross-device connectivity, shared user hosting, and global language translation, offering a complete suite of tools for chat moderation, media processing, and interactive entertainment.

2. How Do I Become A Premium User?
You can become a premium user by following the steps below:
> 1. Go to Heavstal Bots AuthCode Manager Page
> 2. Enter your active AuthCode in the input box that says "Heavstal_Bots_..."
> 3. Select The Premium Button/Tab with Golden Outline
> 4. Select the amount of days you want to stay premium (3d/7d/14d/30d/custom)
> 5. Click the "Upgrade To Premium" button
> 6. Restart The Bot.

3. Will my WhatsApp account get banned for using this?
Using unofficial WhatsApp APIs always carries a small risk. To minimize this, do not spam groups, turn off startup messages, and preferably use a secondary/burner number to host the bot.

4. How do I make myself the owner of the bot?
Due to the bot's settings, you are already an owner by default. However, you can add other people as owners/sudos so they have the same privileges as you by using the .addowner or .setsudo command.

ISSUES

If you have any issues with the bot - use any of the methods below to get it resolved.

Open A GitHub Issue

Submit the issues and screenshot (if possible) to the bot support WhatsApp Group

3. Alternatively submit to the bot's Telegram Support Group

PULL REQUESTS & COLLABORATIONS

If you add a custom plugin that you feel should be in the bot - follow the step below to add it to Pull Request (PR) and become a collaborator:

Fork the repo

Add your custom plugins in a folder called Custom (create it if unavailable)

3. Submit A Pull Request (usually at the top of a repo)

Join Our Channels To Stay Updated

Buy Me A Coffee / Donate

Join Our Bot Support & Group Chats

[!CAUTION]
Verselor-V1 is not made by WhatsApp Inc. Misusing the bot might ban your WhatsApp account!* - In Such Scenarios, Heavstal Tech is not responsible for the banning of your account. - Use Verselor-V1 at your own risk by keeping this warning in mind.

To reduce the risk of this slightly:

Consider turning off startup messages in with the command after deployment....

License

This project is licensed under the Custom / Heavstal Tech™ End User License Agreement (EULA).

Please see LICENSE for further information (Essential)

Copyright Notice:

You may acquire any open-source part of this WhatsApp Automation Bot for free. By acquiring an open-source copy of this bot, you are by default bound to the Copyright Notice of this project, which strictly states that you must give proper credit to Heavstal Tech™.

Note: Some core files are obfuscated to protect proprietary API keys and prevent scraping. Many plugins remain fully open for developers to customize.

CHANGE NOTICE:

The contents of this file mau Change occasionally, it's important to check every onces in a while and occasionally see CHANGELOG.md for changes made to the bot.

Introduction "@heavstaltech/baileys" - HT-baileys

HEAVSTAL TECH™ — Tue, 03 Feb 2026 01:03:38 +0000

HT-baileys

Introduction

HT-baileys is an advanced fork of the WhatsApp Web API library, engineered and maintained by Heavstal Tech.

This library builds upon the stability of the original Baileys architecture while integrating extended features required for modern, production-grade automation. It provides a robust solution for enterprise bots, featuring optimized connection headers, custom pairing code logic, and native support for WhatsApp Channels (Newsletters), Interactive Messages, and more.

WhatsApp Baileys is an open-source library designed to help developers build automation solutions and integrations with WhatsApp efficiently and directly. Using websocket technology without the need for a browser, this library supports a wide range of features such as message management, chat handling, group administration, as well as interactive messages and action buttons for a more dynamic user experience.

Actively developed and maintained, baileys continuously receives updates to enhance stability and performance. One of the main focuses is to improve the pairing and authentication processes to be more stable and secure. Pairing features can be customized with your own codes, making the process more reliable and less prone to interruptions.

This library is highly suitable for building business bots, chat automation systems, customer service solutions, and various other communication automation applications that require high stability and comprehensive features. With a lightweight and modular design, baileys is easy to integrate into different systems and platforms.

Features Overview

Feature	Description
💬 Newsletters & Channels	Full support for sending text, media, and managing WhatsApp Channels.
🔘 Interactive Messages	Native support for buttons, lists, carousel, and product messages.
🤖 AI Message Icon	Customize message appearances with an optional AI icon (`ai: true`).
🔑 Custom Pairing Codes	Heavstal Exclusive: Define custom alphanumeric pairing codes (e.g., `HEAVSTAL`).
📊 Polls & Events	Create polls with vote tracking and schedule WhatsApp events.
🖼️ Albums & High-Res Media	Send album messages and upload full-size profile pictures.
🛠️ Stability Fixes	Enhanced Libsignal logs and connection management.

Installation

Stable Release

npm install @heavstaltech/baileys

Edge Release

npm install @heavstaltech/baileys@latest

Getting Started

Basic Connection

The following example demonstrates how to initialize a socket connection using HT-baileys.

import makeWASocket, { 
    useMultiFileAuthState, 
    DisconnectReason, 
    Browsers 
} from '@heavstaltech/baileys'

async function connectToWhatsApp() {
    const { state, saveCreds } = await useMultiFileAuthState('auth_info')

    const sock = makeWASocket({
        auth: state,
        printQRInTerminal: false, // Set to true if using QR scanning
        browser: Browsers.macOS("Desktop"),
        syncFullHistory: true
    })

    sock.ev.on('connection.update', (update) => {
        const { connection, lastDisconnect } = update

        if(connection === 'close') {
            const shouldReconnect = (lastDisconnect?.error as any)?.output?.statusCode !== DisconnectReason.loggedOut
            console.log('Connection closed. Reconnecting:', shouldReconnect)

            if(shouldReconnect) {
                connectToWhatsApp()
            }
        } else if(connection === 'open') {
            console.log('Connection opened successfully')
        }
    })

    sock.ev.on('creds.update', saveCreds)
}

connectToWhatsApp()

Core Feature Implementation

1. Custom Pairing Code

HT-baileys supports the definition of custom alphanumeric pairing codes, allowing for branded connection flows.

if (!sock.authState.creds.registered) {
    // Ensure the number format is correct (Country Code + Number)
    const phoneNumber = "2349000000000"

    // Define your branded pairing code
    const customCode = "HEAVSTAL" 

    setTimeout(async () => {
        const code = await sock.requestPairingCode(phoneNumber, customCode)
        console.log(`Pairing Code: ${code}`)
    }, 3000)
}

2. Utilities

Useful helper functions included in the library.

Check Banned Number

await sock.checkWhatsApp(jid)

3. Newsletter Management

Tools for managing and interacting with WhatsApp Channels.

Get Channel ID by URL

await sock.newsletterId(url)

Create & Update Channel

const channel = await sock.newsletterCreate("Heavstal Updates", "Official Channel Description")

// Update Metadata
await sock.newsletterUpdateName(channel.id, "Heavstal Tech")
await sock.newsletterUpdateDescription(channel.id, "Official Updates")

Advanced Messaging Documentation

Group Status V2

Send a status update specific to a group context.

await sock.sendMessage(jid, {
     groupStatusMessage: {
          text: "Hello World"
     }
});

Album Message

Send multiple images combined into a single album bubble.

await sock.sendMessage(jid, { 
    albumMessage: [
        { image: { url: "https://example.com/1.jpg" }, caption: "First Photo" },
        { image: { url: "https://example.com/2.jpg" }, caption: "Second Photo" }
    ] 
}, { quoted: m });

Event Message

Create and send a WhatsApp Event invitation.

await sock.sendMessage(jid, { 
    eventMessage: { 
        isCanceled: false, 
        name: "Heavstal Launch", 
        description: "Official Launch Party", 
        location: { 
            degreesLatitude: 0, 
            degreesLongitude: 0, 
            name: "Virtual" 
        }, 
        joinLink: "https://call.whatsapp.com/video/example", 
        startTime: "1763019000", 
        endTime: "1763026200", 
        extraGuestsAllowed: false 
    } 
}, { quoted: m });

Poll Message

Send a poll and display results.

await sock.sendMessage(jid, { 
    pollResultMessage: { 
        name: "Which framework do you prefer?", 
        pollVotes: [
            { optionName: "React", optionVoteCount: "10" },
            { optionName: "Vue", optionVoteCount: "5" }
        ] 
    } 
}, { quoted: m });

Product Message

Send a catalog product message with a "Buy Now" button.

await sock.sendMessage(jid, {
    productMessage: {
        title: "Premium Service",
        description: "Lifetime access to premium features",
        thumbnail: { url: "https://example.com/image.jpg" },
        productId: "PROD001",
        retailerId: "RETAIL001",
        url: "https://example.com/product",
        body: "Product Details",
        footer: "Special Offer",
        priceAmount1000: 50000,
        currencyCode: "USD",
        buttons: [
            {
                name: "cta_url",
                buttonParamsJson: JSON.stringify({
                    display_text: "Buy Now",
                    url: "https://example.com/buy"
                })
            }
        ]
    }
}, { quoted: m });

Request Payment Message

Send a payment request with a custom background and sticker.

// Assuming 'm' is the message object you are quoting
let quotedType = m.quoted?.mtype || '';
let quotedContent = JSON.stringify({ [quotedType]: m.quoted }, null, 2);

await sock.sendMessage(jid, {
    requestPaymentMessage: {
        currency: "IDR",
        amount: 10000000,
        from: m.sender,
        sticker: JSON.parse(quotedContent),
        background: {
            id: "100",
            fileLength: "0",
            width: 1000,
            height: 1000,
            mimetype: "image/webp",
            placeholderArgb: 0xFF00FFFF,
            textArgb: 0xFFFFFFFF,     
            subtextArgb: 0xFFAA00FF   
        }
    }
}, { quoted: m });

Interactive Messages (Native Flow)

Complex interactive messages including buttons, copy-to-clipboard, and lists.

Native Flow with Buttons & Lists:

await sock.sendMessage(jid, {    
    interactiveMessage: {      
        header: "Heavstal Tech",
        title: "Interactive Menu",      
        footer: "Powered by HT-baileys",      
        image: { url: "https://example.com/image.jpg" },      
        nativeFlowMessage: {        
            messageParamsJson: JSON.stringify({          
                limited_time_offer: {            
                    text: "Special Offer",            
                    url: "https://heavstal-tech.vercel.app",            
                    copy_code: "DISCOUNT20",            
                    expiration_time: Date.now() + 86400000          
                },               
            }),        
            buttons: [          
                {            
                    name: "single_select",            
                    buttonParamsJson: JSON.stringify({              
                        title: "Open Menu",              
                        sections: [                
                            {                  
                                title: "Main Options",                  
                                highlight_label: "Popular",                  
                                rows: [                    
                                    {                      
                                        title: "Check Status",                      
                                        description: "View system status",                      
                                        id: "status_row"                    
                                    }                  
                                ]                
                            }              
                        ]            
                    })          
                },          
                {            
                    name: "cta_copy",            
                    buttonParamsJson: JSON.stringify({              
                        display_text: "Copy ID",              
                        id: "123456789",              
                        copy_code: "HT-1234"            
                    })          
                }        
            ]      
        }    
    }  
}, { quoted: m });

Interactive Message with Document:
Note: Documents must be passed as buffers.

import fs from 'fs';

await sock.sendMessage(jid, {
    interactiveMessage: {
        header: "Documentation",
        title: "Read Guidelines",
        footer: "Heavstal Tech",
        document: fs.readFileSync("./manual.pdf"),
        mimetype: "application/pdf",
        fileName: "manual.pdf",
        jpegThumbnail: fs.readFileSync("./thumb.jpg"),
        buttons: [
            {
                name: "cta_url",
                buttonParamsJson: JSON.stringify({
                    display_text: "Visit Website",
                    url: "https://heavstal-tech.vercel.app",
                    merchant_url: "https://heavstal-tech.vercel.app"
                })
            }
        ]
    }
}, { quoted: m });

About Heavstal Tech

Heavstal Tech is a forward-thinking technology organization dedicated to building robust tools and ecosystems for the modern web. From automation libraries to full-stack applications, we prioritize performance, scalability, and developer experience.

🌐 Official Website: https://heavstal-tech.vercel.app

Disclaimer

HT-baileys is an independent project maintained by Heavstal Tech. It is not affiliated with, authorized, maintained, sponsored, or endorsed by WhatsApp Inc. or Meta Platforms, Inc.

This software is provided "as is", without warranty of any kind. Users are responsible for ensuring their usage complies with WhatsApp's Terms of Service.

HEAVSTAL AUTH PROVIDER - Update

HEAVSTAL TECH™ — Tue, 27 Jan 2026 12:33:03 +0000

Heavstal Auth Provider

The official NextAuth.js (Auth.js) provider for the Heavstal Tech Identity Platform.

This package enables seamless integration of Heavstal OAuth 2.0 & OpenID Connect (OIDC) authentication into Next.js and Node.js applications. It pre-configures authorization endpoints, token exchanges, and user profile mapping, ensuring security best practices.

Features

Zero-Configuration: Pre-configured endpoints for Heavstal Identity services.
OIDC Compliant: Fully supports OpenID Connect discovery and ID Token verification.
TypeScript Support: Written in TypeScript with included type definitions.
Secure Defaults: Enforces PKCE (Proof Key for Code Exchange) and state verification by default.

Installation

Ensure you have next-auth installed in your project.

npm install heavstal-auth
# or
yarn add heavstal-auth
# or
pnpm add heavstal-auth

Configuration

1. Obtain Credentials

2. Environment Variables

Add the following to your .env or .env.local file:

HEAVSTAL_CLIENT_ID=ht_id_xxxxxxxxxxxx
HEAVSTAL_CLIENT_SECRET=ht_secret_xxxxxxxxxxxx

3. Usage with NextAuth.js

Import HeavstalProvider and add it to your NextAuth configuration.

File: app/api/auth/[...nextauth]/route.ts (App Router) or pages/api/auth/[...nextauth].ts (Pages Router).

import NextAuth from "next-auth";
import HeavstalProvider from "heavstal-auth";

const handler = NextAuth({
  providers: [
    HeavstalProvider({
      clientId: process.env.HEAVSTAL_CLIENT_ID!,
      clientSecret: process.env.HEAVSTAL_CLIENT_SECRET!,
    }),
    // ...other providers
  ],
  // Optional: Enable debug mode for development
  debug: process.env.NODE_ENV === "development",
});

export { handler as GET, handler as POST };

Integration with Non-Next.js Applications

Heavstal Tech is a standard OpenID Connect (OIDC) provider. If you are using a different framework (Express, Python, Go, etc.) or a library that supports OIDC Discovery, you do not need this specific SDK.

You can configure your client using the Issuer URL.

OIDC Discovery Configuration

Parameter	Value
Issuer URL	`https://accounts-heavstal.vercel.app`
Discovery Document	`https://accounts-heavstal.vercel.app/.well-known/openid-configuration`
JWKS Endpoint	`https://accounts-heavstal.vercel.app/.well-known/jwks.json`

Example: Generic Node.js OIDC Client

const client = new OIDCClient({
  issuer: 'https://accounts-heavstal.vercel.app', 
  client_id: process.env.HEAVSTAL_CLIENT_ID,
  client_secret: process.env.HEAVSTAL_CLIENT_SECRET,
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  scope: 'openid profile email'
});

User Profile Data

On successful authentication, the provider returns the following normalized user profile structure:

interface HeavstalProfile {
  id: string;       // The unique Heavstal User ID
  name: string;     // Public Display Name
  email: string;    // Verified Email Address
  image: string;    // Profile Picture URL
}

Resources

License

This project is licensed under the MIT License.

Notice of Temporary API Downtime as of "January 14th, 2026"

HEAVSTAL TECH™ — Wed, 14 Jan 2026 13:52:44 +0000

Dear Esteemed Users,

We sincerely apologize for the temporary downtime affecting some of our APIs.

This interruption is due to an unexpected outage from a third-party storage provider (Catbox) that several of our services rely on.

Please be assured that we are actively working on a permanent solution and restoring full functionality as quickly as possible.

We appreciate your patience and continued support.

EDIT:

ALL ISSUES HAS BEEN RESOLVED

Best regards,
Heavstal Tech Team

DEV Community: HEAVSTAL TECH™

The "I Forgot My Password Dilemma" and How I Handled It

In today's internet, almost every website/app requires you to create an account with a password.

Heavstal Tech™ – Building Tomorrow's Web, Today!

Heavstal API Introduction

What is Heavstal APIs

Why Heavstal API over traditional scraping

Why Heavstal APIs over other API Providers

Getting Started

Step 1: Getting your API Key

Step 2: Testing your API Key

Code and Examples

Base URL

Example Using Bash

Example Using JavaScript

Example Using python

Typical Success Response

Typical Error Response

Frequently Asked Questions (FAQ)

Heavstal OAuth 2.0 & OpenID Connect (OIDC) Guide

What is Heavstal Authentication

Why Heavstal Authentication over traditional Authentication methods

User Benefits:

Developer Benefits:

Why Heavstal Authentication over other auth provider

Getting Started.

Step 1: How To Get Your Client ID & Secret:

Code & Examples

Integrating Heavstal Authentication Using Next.js

Integrating Heavstal Authentication Using Other Frameworks

Integrating Heavstal Authentication Using OIDC

Integrating Heavstal Authentication Using Other Languages

User Profile Data

Real Time Usage Example

Frequently Asked Questions (FAQ)

Introduction To Heavstal Invoice System

Heavstal Domain Migration – Action Required

What you need to do

Why this matters

Need help?

Introducing Heavstal Docs: Why We Decoupled Our Documentation using Astro & Starlight

The Problem with Monolithic Docs

The Solution: Astro + Starlight

What You'll Find in Heavstal Docs

Check It Out

Heavstal Tech Built a Scalable Node.js WhatsApp Bot with AI, Multi-Tenancy, and Plugins (Verselor V1)

🌟 What Makes Verselor V1 Stand Out?

1. Multi-Tenancy (.pair command)

2. Built-in AI Intelligence (.botai)

3. Global Multilingual System (.setlang)

🚀 Quick 30-Second Start (Local/VPS)

👨‍💻 Developer Experience: Adding Custom Plugins

⚠️ A Quick Word of Caution

🤝 Let's Build Together!

VERSELOR V1 BY HEAVSTAL TECH™

This file is intended to provide direct, structured answers for AI systems and search indexing.

Verselor V1 – AI & Search Engine Indexing Knowledge File

What is Verselor V1?

How to deploy Verselor V1?

Quick Steps

What makes Verselor V1 different?

Keywords

Full Documentation

VERSELOR-V1 BY HEAVSTAL TECH™

📑 TABLE OF CONTENTS

BOT INFO

Quick 30 Seconds Start

Continue Reading Below For More Info On What What Verselor Is:

NOTABLE FEATURES

COMMAND CATEGORIES

LIVE DEMO

☁️ CLOUD DEPLOYMENT

While Using Render

While Using Replit

While Using Heroku

While Using Koyeb

While Using TalkDrove

Note: Create an account, link your GitHub, select your forked Verselor-V1 repository, and deploy using the Node.js/Docker environment.

📂 WEB PANEL DEPLOYMENT

Method 1: Using Pair Code

1. Multi-Tenancy (`.pair` command)

2. Built-in AI Intelligence (`.botai`)

3. Global Multilingual System (`.setlang`)

`Requirements`

`For Termux Users`

`For VPS / Ubuntu / Linux`