LINE Messaging API SDK for Node.js

Audience management in LineBotClient features significant renames and changes to how groups are updated. For updating descriptions, you must now use a separate call. Many methods also changed their parameter types (e.g., audienceGroupId from string to number) and file types (from Buffer | Readable to Blob).

Audience Method Mapping

This project is a boilerplate for creating a custom OpenAPI generator for the line-bot-sdk-nodejs-generator. To use it, you must first modify the generator logic and templates, build it into a JAR file using Maven, and then run it using the OpenAPI Generator CLI.

1. Modify the Generator

You must customize the following files to implement your specific logic:

• LineBotSdkNodejsGeneratorGenerator.java: The core generator logic.
• src/main/resources/line-bot-sdk-nodejs-generator: The Mustache template files.

2. Build the JAR

Run the following command in your generator project directory:

mvn package

The resulting JAR file will be located in the target directory.

3. Run the Generator

Use the java command to run the OpenAPI Generator CLI with your custom JAR in the classpath. Replace the placeholder paths with your actual file locations.

macOS / Linux:

java -cp /path/to/openapi-generator-cli.jar:/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g line-bot-sdk-nodejs-generator -i /path/to/openapi.yaml -o ./test

Windows:

java -cp /path/to/openapi-generator-cli.jar;/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g line-bot-sdk-nodejs-generator -i /path/to/openapi.yaml -o ./test

The @line/bot-sdk library is written in TypeScript and provides built-in type definitions for its core components. While you can use the pre-compiled JavaScript files via npm without any extra configuration, using TypeScript provides several benefits:

1. Type Safety for Configuration: Prevents typos in configuration keys (e.g., using channelAccessToken correctly).
2. Message Validation: Ensures complex message objects (like TemplateMessage) contain all required fields and follow the correct structure.
3. Literal Type Support: Uses literal types for type fields, allowing the compiler to validate specific string values and infer object types based on the type property.
4. Autocomplete: Provides a default type set for most objects used in webhooks and the client.

import {
  LineBotClient,
  middleware,
  webhook,
  JSONParseError,
  SignatureValidationFailed,
} from "@line/bot-sdk";

const client = LineBotClient.fromChannelAccessToken({ channelAccessToken: "..." });

When migrating from the legacy Client to LineBotClient, note that OAuth methods are no longer available on LineBotClient. Instead, they have been moved to channelAccessToken.ChannelAccessTokenClient.

To use these methods, you must construct a new ChannelAccessTokenClient without passing a channel access token in the configuration object.

Method Mapping Table

const { channelAccessToken } = require('@line/bot-sdk');
const oauthClient = new channelAccessToken.ChannelAccessTokenClient({});

When developing custom templates (e.g., in api.mustache), you can inspect the data available to the template engine by passing debug flags to the java generation command. This helps you identify which keys and objects are accessible during the generation process.

Debug Flags

• -DdebugOpenAPI: Prints the OpenAPI Specification as interpreted by the codegen.
• -DdebugModels: Prints models passed to the template engine.
• -DdebugOperations: Prints operations passed to the template engine.
• -DdebugSupportingFiles: Prints additional data passed to the template engine.

Example Usage

To debug operations, include the -DdebugOperations flag in your execution command:

java -DdebugOperations -cp /path/to/openapi-generator-cli.jar:/path/to/your.jar org.openapitools.codegen.OpenAPIGenerator generate -g line-bot-sdk-nodejs-generator -i /path/to/openapi.yaml -o ./test

The webhook middleware() can throw two specific error types that should be handled using Express error-handling middleware:

• SignatureValidationFailed: Thrown when the X-Line-Signature header is missing or the signature does not match the request body (indicating a potential fraud attempt).
• JSONParseError: Occurs when the request body cannot be parsed as valid JSON.

Example of handling these errors in Express:

import express from 'express'
import {middleware, JSONParseError, SignatureValidationFailed} from '@line/bot-sdk'

const app = express()
const config = { channelSecret: 'YOUR_CHANNEL_SECRET' }

app.post('/webhook', middleware(config), (req, res) => {
  res.json(req.body.events)
})

// Error handling middleware
app.use((err, req, res, next) => {
  if (err instanceof SignatureValidationFailed) {
    // Handle invalid signature (e.g., 401 Unauthorized)
    res.status(401).send(err.signature)
    return
  } else if (err instanceof JSONParseError) {
    // Handle invalid JSON (e.g., 400 Bad Request)
    res.status(400).send(err.raw)
    return
  }
  next(err)
})

app.listen(8080)

A LINE webhook server is an HTTP(S) server that receives requests from the LINE Platform when user events occur. The recommended way to build this server is using the middleware() function from @line/bot-sdk, which handles both Signature validation (verifying the X-Line-Signature header) and Webhook event object parsing (converting the JSON body into usable objects).

When using Express, apply the middleware specifically to your webhook route to avoid errors on other routes.

import express from 'express'
import { middleware } from '@line/bot-sdk'

const app = express()

const config = {
  channelSecret: 'YOUR_CHANNEL_SECRET'
}

// Apply middleware only to the webhook route
app.post('/webhook', middleware(config), (req, res) => {
  // req.body.events contains the webhook event objects
  // req.body.destination contains the user ID of the bot
  console.log(req.body.events)
  res.status(200).send('OK')
})

app.listen(8080)

An Echo Bot is a basic bot that replies to a user's message with the same content. This guide demonstrates how to set up a LINE Echo Bot from scratch using TypeScript and CommonJS (CJS).

Prerequisites

• Node.js: Version 20 or higher.
• LINE Channel: A channel created in the LINE Developers Console providing a CHANNEL_ACCESS_TOKEN and CHANNEL_SECRET.

Installation and Setup

1. Clone the repository and navigate to the example directory:

   git clone https://github.com/line/line-bot-sdk-nodejs.git
   cd line-bot-sdk-nodejs/examples/echo-bot-ts-cjs

2. Install dependencies:

   npm install

3. Configure environment variables:

   export CHANNEL_ACCESS_TOKEN=<YOUR_CHANNEL_ACCESS_TOKEN>
   export CHANNEL_SECRET=<YOUR_CHANNEL_SECRET>
   export PORT=<YOUR_PORT>

4. Set up your Webhook URL in the LINE Official Account settings (e.g., https://example.com/callback). Note: Disable greeting messages and auto-response messages in your LINE Official Account settings for the best experience.
5. Build and run the application:

   npm run build
   npm start