Project setup

1. Copy the source/ directory into your project, e.g. as src/line-bot-sdk/.
2. Ensure your tsconfig.json targets ES2020 or later and has moduleResolution set to node16 or bundler (the source uses .js extension imports for ESM compatibility):

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "Node16",
    "moduleResolution": "Node16",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "dist"
  }
}

3. Set your channel credentials as environment variables:

CHANNEL_ACCESS_TOKEN=your_channel_access_token
CHANNEL_SECRET=your_channel_secret

4. Import from the source root:

import { LineBotClient, middleware, validateSignature } from "./line-bot-sdk/index.js";

5. If you use a bundler (Webpack, esbuild, Vite), ensure .js extension resolution for TypeScript source files is configured, or alias the imports accordingly.

Public API

LineBotClient

class LineBotClient extends LineBotClientBase {
  static fromChannelAccessToken(
    config: LineBotClientChannelAccessTokenConfig
  ): LineBotClient;
}

interface LineBotClientChannelAccessTokenConfig {
  readonly channelAccessToken: string;
  readonly defaultHeaders?: Record<string, string>;
  readonly apiBaseURL?: string;
  readonly dataApiBaseURL?: string;
  readonly managerBaseURL?: string;
}

The primary entry point for all LINE Bot API operations. Use LineBotClient.fromChannelAccessToken to construct a fully configured instance. It delegates to sub-clients for Insight, LIFF, Messaging API, Manage Audience, Module, and Shop. Use this when you want a single client rather than managing individual API clients.

middleware

function middleware(config: { channelSecret: string }): RequestHandler;

Express-compatible middleware that parses and verifies incoming LINE webhook requests. It validates the x-line-signature header and populates req.body with parsed webhook events. Use this as an Express route middleware on your webhook endpoint.

validateSignature

function validateSignature(
  body: string | Buffer,
  channelSecret: string,
  signature: string
): boolean;

Low-level utility to manually verify a LINE webhook HMAC-SHA256 signature. Use this when you cannot use the Express middleware directly (e.g. in Fastify, Koa, or raw http servers) and need to validate the signature yourself before processing events.

Working examples

Scenario - Send a reply message using LineBotClient

Create a unified client and reply to a webhook text event using the Messaging API sub-client.

import { LineBotClient } from "./line-bot-sdk/index.js";

const client = LineBotClient.fromChannelAccessToken({
  channelAccessToken: process.env.CHANNEL_ACCESS_TOKEN!,
});

async function handleTextEvent(replyToken: string, userText: string) {
  await client.messagingApi.replyMessage({
    replyToken,
    messages: [{ type: "text", text: `You said: ${userText}` }],
  });
}

Scenario - Verify webhook signatures with Express middleware

Wire the middleware export into an Express app to automatically validate incoming LINE webhook requests.

import express from "express";
import { middleware } from "./line-bot-sdk/index.js";

const app = express();

app.post(
  "/webhook",
  middleware({ channelSecret: process.env.CHANNEL_SECRET! }),
  (req, res) => {
    const events = req.body.events;
    for (const event of events) {
      console.log("Received event:", event.type);
    }
    res.sendStatus(200);
  }
);

app.listen(3000);

Scenario - Retrieve audience demographics via the Insight sub-namespace

Use the insight named export directly when you only need analytics without constructing a full LineBotClient.

import { insight } from "./line-bot-sdk/index.js";

const insightClient = new insight.InsightClient({
  channelAccessToken: process.env.CHANNEL_ACCESS_TOKEN!,
});

async function printDemographics() {
  const data = await insightClient.getFriendsDemographics();
  console.log("Demographics:", JSON.stringify(data, null, 2));
}

printDemographics();

Scenario - Validate a webhook signature manually in Fastify

Use validateSignature for frameworks where you control raw body parsing.

import Fastify from "fastify";
import { validateSignature } from "./line-bot-sdk/index.js";

const fastify = Fastify();

fastify.post("/webhook", {
  config: { rawBody: true },
}, async (request, reply) => {
  const signature = request.headers["x-line-signature"] as string;
  const rawBody = (request as any).rawBody as Buffer;
  const isValid = validateSignature(rawBody, process.env.CHANNEL_SECRET!, signature);
  if (!isValid) {
    return reply.status(401).send({ error: "Invalid signature" });
  }
  const events = (request.body as any).events;
  console.log("Valid events:", events);
  reply.status(200).send("OK");
});

fastify.listen({ port: 3000 });

File walkthrough

• index.ts - Barrel file; re-exports middleware, validateSignature, all exceptions, types, and all sub-namespace API clients. This is the only import path consumers need.
• line-bot-client.ts - Defines LineBotClient and LineBotClientChannelAccessTokenConfig; the manual wrapper that exposes fromChannelAccessToken static factory.
• line-bot-client.generated.ts - Auto-generated abstract base with one method per API operation, delegating to the appropriate typed sub-client.
• line-bot-client.factory.generated.ts - Auto-generated createLineBotClientDelegates factory that constructs all sub-clients from a single config object.
• middleware.ts - Express RequestHandler that validates LINE webhook signatures and parses event bodies.
• validate-signature.ts - Standalone HMAC-SHA256 signature check; framework-agnostic.
• http-fetch.ts - Internal HTTPFetchClient class; exposes normalizeHeaders, mergeHeaders, convertResponseToReadable helpers.
• exceptions.ts - Exports HTTPFetchError and any other SDK-specific error classes.
• types.ts - Shared types including ApiResponseType<T> wrapping HTTP response metadata.
• utils.ts - Internal helpers such as createURLSearchParams.
• version.ts - Exports USER_AGENT string used in HTTP request headers.
• channel-access-token/ - ChannelAccessTokenClient for issuing, verifying, and revoking channel access tokens.
• insight/ - InsightClient covering friend demographics, message events, and delivery statistics.
• liff/ - LiffClient for adding, updating, and listing LIFF apps.
• manage-audience/ - ManageAudienceClient and ManageAudienceBlobClient for audience group CRUD and CSV uploads.
• messaging-api/ - MessagingApiClient and MessagingApiBlobClient for the full Messaging API surface.
• module/ - LineModuleClient for LINE Module operation endpoints.
• module-attach/ - LineModuleAttachClient for module attachment flows.
• shop/ - ShopClient for LINE Shop related API calls.
• webhook/ - Type definitions for all LINE webhook event payloads.

Common pitfalls and fixes

• .js extension imports fail in CJS projects - The source uses ESM-style .js imports; set "module": "Node16" or "module": "ESNext" in tsconfig.json and use "type": "module" in package.json.
• req.body is undefined in middleware - Do not place express.json() before the LINE middleware; middleware handles raw body parsing internally for signature validation.
• CHANNEL_SECRET vs CHANNEL_ACCESS_TOKEN confusion - channelSecret is used only for signature verification; channelAccessToken is used for API calls. Both are required but for different purposes.
• LineBotClient does not include channel access token management - Use channelAccessToken sub-namespace directly from index.ts for issuing or revoking tokens; LineBotClient intentionally omits this.
• Node.js version below 20 - The SDK uses the native fetch API (no node-fetch dependency); Node.js 20+ is required or you must polyfill fetch globally.
• TypeScript errors on request.rawBody - When using validateSignature in Fastify or Koa, configure your framework to preserve the raw body buffer before JSON parsing; the SDK has no control over this step.

Vibe-coding prompt template

I have the LINE Bot SDK source code in `src/line-bot-sdk/` and a USAGE.md
integration guide in the same directory. The upstream npm package is
`@line/bot-sdk@1.0.0-test`.

Please integrate this SDK into my existing Express + TypeScript project
step by step:

1. Read USAGE.md and src/line-bot-sdk/index.ts to understand all exports.
2. Add the webhook endpoint using the `middleware` export with my CHANNEL_SECRET
   environment variable.
3. Create a `LineBotClient` instance using `LineBotClient.fromChannelAccessToken`
   with my CHANNEL_ACCESS_TOKEN environment variable.
4. Handle incoming `message` events of type `text` and reply using
   `client.messagingApi.replyMessage`.
5. Show me the complete updated Express app file with all required imports
   from `src/line-bot-sdk/index.js`.
6. Warn me about any tsconfig.json changes needed for ESM module resolution.

License and credit

Licensed under the Apache License, Version 2.0. See the full license text at https://www.apache.org/licenses/LICENSE-2.0 or in source/LICENSE if present in this block.

Upstream package: @line/bot-sdk by LINE Corp. Upstream repository: https://github.com/line/line-bot-sdk-nodejs

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

WordPress & WooCommerce Plugins

Free