{"_id":"chat-adapter-zalo","name":"chat-adapter-zalo","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"chat-adapter-zalo","version":"0.1.0","description":"Community Zalo adapter for Chat SDK - Zalo Bot Platform","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run --coverage","test:watch":"vitest","typecheck":"tsc --noEmit","check":"biome check .","check:fix":"biome check --write .","clean":"rm -rf dist","prepublishOnly":"pnpm run build"},"peerDependencies":{"chat":">=4.0.0","@chat-adapter/shared":">=4.0.0"},"devDependencies":{"@biomejs/biome":"^2.4.0","@chat-adapter/shared":"^4.23.0","@types/node":"^22.0.0","chat":"^4.23.0","tsup":"^8.3.5","typescript":"^5.7.2","@vitest/coverage-v8":"^4.1.2","vitest":"^4.1.2"},"repository":{"type":"git","url":"git+https://github.com/buiducnhat/chat-adapter-zalo.git"},"homepage":"https://github.com/buiducnhat/chat-adapter-zalo#readme","bugs":{"url":"https://github.com/buiducnhat/chat-adapter-zalo/issues"},"publishConfig":{"access":"public"},"keywords":["chat","chat-sdk","zalo","bot","adapter","messaging","community"],"license":"MIT","author":{"name":"Nhat Bui"},"_id":"chat-adapter-zalo@0.1.0","gitHead":"a11acb91efa9752c6d15c0a00c759b92c479e6fa","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-dHjLch8L32mwIfVvcaH4qzUpiJgeWr+w3qWG2JhtC7PugDlJjM7ZrGcmvW+v9jB8vD8uW/1PqB2ealAI5I0B4w==","shasum":"4d33ea36b646ee7d0db1de700fce6133e0efe4e1","tarball":"https://registry.npmjs.org/chat-adapter-zalo/-/chat-adapter-zalo-0.1.0.tgz","fileCount":6,"unpackedSize":65831,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/chat-adapter-zalo@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICkCL8A6WSk/2CSc+MRLRa5A4K8knw/eRNocP3713ZUpAiB3as+3d2X/fmMvLJ/g0qvg4WGkiXbwpGzWvOykqAgBtQ=="}]},"_npmUser":{"name":"buiducnhat","email":"nhaths4701@gmail.com"},"directories":{},"maintainers":[{"name":"buiducnhat","email":"nhaths4701@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/chat-adapter-zalo_0.1.0_1775489645704_0.326389085222224"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-06T15:34:05.595Z","0.1.0":"2026-04-06T15:34:05.877Z","modified":"2026-04-06T15:34:06.265Z"},"maintainers":[{"name":"buiducnhat","email":"nhaths4701@gmail.com"}],"description":"Community Zalo adapter for Chat SDK - Zalo Bot Platform","homepage":"https://github.com/buiducnhat/chat-adapter-zalo#readme","keywords":["chat","chat-sdk","zalo","bot","adapter","messaging","community"],"repository":{"type":"git","url":"git+https://github.com/buiducnhat/chat-adapter-zalo.git"},"author":{"name":"Nhat Bui"},"bugs":{"url":"https://github.com/buiducnhat/chat-adapter-zalo/issues"},"license":"MIT","readme":"# chat-adapter-zalo\n\n[![npm version](https://img.shields.io/npm/v/chat-adapter-zalo)](https://www.npmjs.com/package/chat-adapter-zalo)\n[![npm downloads](https://img.shields.io/npm/dm/chat-adapter-zalo)](https://www.npmjs.com/package/chat-adapter-zalo)\n\n> **Community adapter** — This package is a community-maintained Zalo adapter for [Chat SDK](https://chat-sdk.dev). It is not an official `@chat-adapter/*` package.\n\nZalo Bot adapter for [Chat SDK](https://chat-sdk.dev), using the [Zalo Bot Platform API](https://bot.zapps.me/docs).\n\n## Installation\n\n```bash\npnpm add chat-adapter-zalo chat @chat-adapter/shared\n```\n\n## Usage\n\n```typescript\nimport { Chat } from \"chat\";\nimport { createZaloAdapter } from \"chat-adapter-zalo\";\n\nconst bot = new Chat({\n  userName: \"mybot\",\n  adapters: {\n    zalo: createZaloAdapter(),\n  },\n});\n\nbot.onNewMention(async (thread, message) => {\n  await thread.post(`You said: ${message.text}`);\n});\n```\n\nWhen using `createZaloAdapter()` without arguments, credentials are auto-detected from environment variables.\n\n## Zalo Bot setup\n\n### 1. Create a Zalo Bot\n\n1. Go to [bot.zapps.me](https://bot.zapps.me) and sign in with your Zalo account\n2. Create a new bot and note your **Bot Token** (format: `12345689:abc-xyz`)\n3. Go to **Webhooks** settings and set your webhook URL\n\n### 2. Configure webhooks\n\n1. In the Zalo Bot dashboard, navigate to **Webhooks**\n2. Set **Webhook URL** to `https://your-domain.com/api/webhooks/zalo`\n3. Set a **Secret Token** of your choice (8–256 characters) — this becomes `ZALO_WEBHOOK_SECRET`\n4. Subscribe to the message events you need (`message.text.received`, `message.image.received`, etc.)\n\n### 3. Get credentials\n\nFrom your Zalo Bot dashboard, copy:\n\n- **Bot Token** as `ZALO_BOT_TOKEN`\n- The **Secret Token** you set in the webhook config as `ZALO_WEBHOOK_SECRET`\n\n## Configuration\n\nAll options are auto-detected from environment variables when not provided.\n\n| Option          | Required | Description                                                                       |\n| --------------- | -------- | --------------------------------------------------------------------------------- |\n| `botToken`      | No\\*     | Zalo bot token. Auto-detected from `ZALO_BOT_TOKEN`                               |\n| `webhookSecret` | No\\*     | Secret token for webhook verification. Auto-detected from `ZALO_WEBHOOK_SECRET`   |\n| `userName`      | No       | Bot display name. Auto-detected from `ZALO_BOT_USERNAME` (defaults to `zalo-bot`) |\n| `logger`        | No       | Logger instance (defaults to `ConsoleLogger(\"info\")`)                             |\n\n\\*Required at runtime — either via config or environment variable.\n\n## Environment variables\n\n```bash\nZALO_BOT_TOKEN=12345689:abc-xyz      # Bot token from Zalo Bot dashboard\nZALO_WEBHOOK_SECRET=your-secret      # Secret token for X-Bot-Api-Secret-Token verification\nZALO_BOT_USERNAME=mybot              # Optional, defaults to \"zalo-bot\"\n```\n\n## Webhook setup\n\n```typescript\n// Next.js App Router example\nimport { bot } from \"@/lib/bot\";\n\nexport async function POST(request: Request) {\n  return bot.webhooks.zalo(request);\n}\n```\n\nZalo delivers all events via POST requests with an `X-Bot-Api-Secret-Token` header. The adapter verifies this header using timing-safe comparison before processing any payload.\n\n## Features\n\n### Messaging\n\n| Feature        | Supported                         |\n| -------------- | --------------------------------- |\n| Post message   | Yes                               |\n| Edit message   | No (Zalo limitation)              |\n| Delete message | No (Zalo limitation)              |\n| Streaming      | Buffered (accumulates then sends) |\n| Auto-chunking  | Yes (splits at 2000 chars)        |\n\n### Conversations\n\n| Feature          | Supported              |\n| ---------------- | ---------------------- |\n| Reactions        | No (Zalo limitation)   |\n| Typing indicator | Yes (`sendChatAction`) |\n| DMs              | Yes                    |\n| Group chats      | Pending                |\n| Open DM          | Yes                    |\n\n### Incoming message types\n\n| Type              | Supported                     |\n| ----------------- | ----------------------------- |\n| Text              | Yes                           |\n| Images            | Yes (with optional caption)   |\n| Stickers          | Yes (rendered as `[Sticker]`) |\n| Unsupported types | Ignored gracefully            |\n\n### Message history\n\n| Feature           | Supported                |\n| ----------------- | ------------------------ |\n| Fetch messages    | No (Zalo API limitation) |\n| Fetch thread info | Yes                      |\n\n## Thread ID format\n\n```\nzalo:{chatId}\n```\n\nExample: `zalo:1234567890`\n\nThe `chatId` is the conversation ID from the Zalo webhook payload. For group chats it is the group ID; for private chats it is the user ID.\n\n## Notes\n\n- Zalo does not expose message history APIs to bots. `fetchMessages` returns an empty array.\n- All formatting (bold, italic, code blocks) is stripped to plain text — Zalo renders no markdown.\n- The bot token is embedded in the API URL path and is never logged.\n- `isDM()` always returns `true` — Zalo thread IDs do not encode chat type.\n\n## Troubleshooting\n\n### Webhook verification failing\n\n- Confirm `ZALO_WEBHOOK_SECRET` matches the value you entered in the Zalo Bot dashboard\n- The adapter compares the `X-Bot-Api-Secret-Token` header using a timing-safe byte comparison — ensure the secret contains only ASCII characters and has no trailing whitespace\n\n### Messages not arriving\n\n- Verify your webhook URL is reachable and returns `200 OK`\n- Check that the event types you need are subscribed in the Zalo Bot dashboard\n\n### \"Zalo API error\" on send\n\n- Confirm `ZALO_BOT_TOKEN` is correct — it should be in `12345689:abc-xyz` format\n- The adapter calls `getMe` during `initialize()` to validate the token; check logs for initialization errors\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-5eddd126c68c4a273b6ad6f55729086a"}