@yourname168/zalo-tools

Reusable Node.js helpers for Zalo login, message listening, cookie refresh callbacks, and normalized message payloads.

Requirements

• Node.js 20 or newer.
• A valid Zalo imei, cookie JSON, and userAgent.
• Long-running process support if you use the message listener.

Install

npm install @yourname168/zalo-tools

Environment

Create these variables in your consuming project. Do not commit real cookies.

ZALO_IMEI=
ZALO_COOKIE_JSON=
ZALO_USER_AGENT=
ZALO_LANGUAGE=vi
ZALO_ALLOWED_THREAD_IDS=

ZALO_COOKIE_JSON must be a JSON cookie array or an object with a cookies array.

Start A Listener

import {
  parseZaloCredentialFromEnv,
  startZaloMessageListener,
} from "@yourname168/zalo-tools"

const credential = parseZaloCredentialFromEnv(process.env)

const handle = await startZaloMessageListener({
  ...credential,
  allowedThreadIds: [],
  blockedThreadIds: [],
  ignoreSelf: true,
  onMessage: async (message) => {
    console.log({
      threadId: message.threadId,
      senderName: message.senderName,
      text: message.text,
      imageUrls: message.imageUrls,
    })
  },
  onCookieRefreshed: async (cookies) => {
    console.log(`Received ${cookies.length} refreshed cookies`)
  },
  onError: (error) => {
    console.error(error)
  },
})

process.on("SIGINT", () => {
  handle.stop()
  process.exit(0)
})

Login Manually

import { createZaloClient, getZaloCookiesFromApi } from "@yourname168/zalo-tools"

const api = await createZaloClient({
  imei: process.env.ZALO_IMEI || "",
  cookie: JSON.parse(process.env.ZALO_COOKIE_JSON || "[]"),
  userAgent: process.env.ZALO_USER_AGENT || "",
  language: process.env.ZALO_LANGUAGE || "vi",
})

const refreshedCookies = getZaloCookiesFromApi(api)
console.log(refreshedCookies.length)

Normalize A Raw Message

import { normalizeZaloMessage } from "@yourname168/zalo-tools"

const normalized = normalizeZaloMessage(rawMessage)
if (normalized) {
  console.log(normalized.text)
}

Main API

• createZaloClient(options)
• startZaloMessageListener(options)
• getZaloCookiesFromApi(api)
• parseZaloCredentialFromEnv(env?)
• parseZaloCookie(payload)
• normalizeZaloMessage(message)

Normalized Message Shape

interface NormalizedZaloMessage {
  source: "zalo"
  threadId: string
  threadType: "user" | "group"
  messageId: string
  senderId: string
  senderName: string | null
  text: string
  imageUrls: string[]
  isSelf: boolean
}

Notes

• This package does not write credentials to a database or .env file.
• Use onCookieRefreshed to persist refreshed cookies in your own app.
• Keep cookies server-side only.