@hca-rx/hopenity 〄

HCA is an unofficial Node.js client for Hopenity — built for reliable, fast, and modular bot development. Designed with clean FCA-style API, it gives you full control over Hopenity chat automation through a simple, stable interface.

Zero external dependencies — pure Node.js https / http / events.

✨ Features

• 🔐 Secure Login — Email or phone number authentication with device approval support
• 💬 Real-time Messaging — Poll and receive messages, replies, reactions, and group events
• 📎 Attachments — Upload and send files, images, and media
• 👥 Full Group Control — Create, join, leave, manage members and admins
• 🔔 Notifications — Fetch and mark notifications as read
• 🎵 Media & Extras — Music, stories, donations, premium calls, LiveKit tokens
• 🛡️ Self-Defending — Core source is protected against copying and tampering
• ⚡ FCA-Style API — Familiar structure for anyone who has used fca-unofficial or ws3-fca

📦 Installation

npm install hca

🚀 Quick Start

const hca = require("hca");

(async () => {
  const session = await hca.login({
    email: "[email protected]",
    password: "yourpassword",
  });

  session.listen({ interval: 3000 }, async (err, event) => {
    if (err) return console.error(err);

    if (event.type === "message") {
      console.log(`${event.senderName}: ${event.body}`);
      await session.sendMessage(event.threadID, "Hello!", {
        isGroup: event.isGroup,
      });
    }
  });
})();

🔑 Login

// Login with email
const session = await hca.login({
  email: "[email protected]",
  password: "yourpassword",
});

// Login with phone number
const session = await hca.login({
  phoneNumber: "01XXXXXXXXX",
  password: "yourpassword",
});

📲 Device Approval

If Hopenity requires approval from a trusted device:

try {
  const session = await hca.login({ email, password });
} catch (err) {
  if (err.requiresApproval) {
    console.log("Approve from a trusted device:", err.message);

    const session = await hca.waitForDeviceApproval(
      err.requestToken,
      null,
      { interval: 5000, timeout: 120000 }
    );
  }
}

👂 session.listen(opts, callback)

Listens for new messages, replies, reactions, and group events.

const stop = session.listen({
  interval: 3000,        // message poll interval ms   (default: 3000)
  selfListen: false,     // emit your own messages?    (default: false)
  groupEvents: true,     // track group changes?       (default: true)
  reactionEvents: true,  // track reactions?           (default: true)
}, (err, event) => {
  if (err) return console.error(err);

  if (event.type === "message") { /* new message */ }
  if (event.type === "reply")   { /* reply to a message */ }
  if (event.type === "reaction"){ /* reaction on a message */ }
  if (event.type === "event")   { /* group event */ }
});

stop(); // stop listening

📨 Message / Reply Fields

| Field | Type | Description | |---|---|---| | type | string | "message" or "reply" | | senderID | string | Sender user ID | | senderName | string | Sender display name | | body | string | Message text | | threadID | string | Conversation ID | | messageID | string | Message ID | | timestamp | number | Unix ms | | attachments | Array | Attached files | | isGroup | boolean | Is it a group chat? | | replyToId | string\|null | ID of the message being replied to | | isSelf | boolean | Sent by the logged-in account? |

📣 Group Event Types (event.logMessageType)

| Value | Description | |---|---| | log:subscribe | Member joined or was added | | log:unsubscribe | Member left or was removed | | log:admin-promote | Member promoted to admin | | log:admin-demote | Admin demoted to member | | log:thread-name | Group name changed | | log:thread-image | Group avatar changed |

📖 API Reference

💬 Messages

await session.sendMessage(threadID, "Hello!", { isGroup: false });
await session.sendAttachment(threadID, buffer, { fileName: "photo.jpg", mimeType: "image/jpeg", isGroup: false });
await session.getMessages(threadID, { limit: 20, isGroup: false });
await session.deleteMessage(threadID, messageID, { isGroup: false });
await session.reactToMessage(threadID, messageID, "❤️", { isGroup: false });
await session.markAsRead(threadID, { isGroup: false });

🔍 Threads & Users

await session.getThreadList();
await session.searchUsers("John");
await session.getUserInfo(userId);
await session.acceptChatRequest(chatId, userId);

👥 Groups

await session.getGroups();
await session.getGroupInfo(groupId);
await session.getGroupMembers(groupId);
await session.joinGroup(groupId);
await session.leaveGroup(groupId);
await session.createGroup({ name: "My Group", memberIds: ["id1", "id2"] });
await session.updateGroupInfo(groupId, { name: "New Name" });
await session.addUserToGroup(groupId, userId);
await session.removeUserFromGroup(groupId, userId);
await session.promoteAdmin(groupId, userId);
await session.demoteAdmin(groupId, userId);

🔔 Notifications

await session.getNotifications({ page: 1, limit: 50 });
await session.markAllNotificationsRead();

🎵 Media & Extras

await session.getStories();
await session.getMyPages();
await session.getMusicList();
await session.getMusicTracks();
await session.getDonations();
await session.getPremiumCalls();
await session.getLiveKitToken({ liveKitRoom: "room", conversationId: "id" });
await session.updateFCMToken(fcmToken);
await session.updatePrivacySettings(settings);
await session.rawRequest("/api/v1/any-endpoint", { method: "GET" });

🤝 Contributing

Found a bug or want to add something new? Send a Pull Request!

GitHub: https://github.com/abdullahrx07/Hopechat-hca.git

When submitting a PR, include the following info:

GitHub Username : your_github_username
Hopenity ID     : your_hopenity_id
Change / Feature: brief description of what you added or fixed

All PRs are reviewed manually. Hopenity ID is required.

👤 Credits

Made with ❤️ by rX

HCA is unofficial and not affiliated with Hopenity.