Hướng dẫn July 21, 2026

Cách gửi tin nhắn dịch vụ LINE MINI App bằng token thông báo

Để gửi tin nhắn dịch vụ LINE MINI App, hãy lấy một LIFF access token mới sau thao tác của người dùng, gửi token đó về máy chủ để đổi lấy service notification token gắn với đúng người dùng, rồi gọi endpoint gửi chính thức bằng một template đã được phê duyệt. Sau mỗi phản hồi, phải lưu lại notificationToken mới: giá trị token được luân chuyển sau từng lần gửi thành công, còn remainingCount quyết định hành động đó còn được gửi thêm bao nhiêu tin.

Điểm chính cần nhớ

Muốn gửi tin nhắn dịch vụ trong production, LINE MINI App phải được xác minh và template phải được phê duyệt. Ứng dụng chưa được xác minh chỉ có thể thử nghiệm qua kênh Developing nội bộ với tài khoản Admin hoặc Tester.
Mỗi LIFF access token chỉ phát hành được một service notification token qua POST /message/v3/notifier/token. Token nhận được thuộc về một người dùng và một phiên thao tác.
Gửi tin qua POST /message/v3/notifier/send?target=service, sau đó thay token đang lưu bằng notificationToken mới trong phản hồi.
Token mới phát hành hết hạn sau một năm và thông thường bắt đầu với năm lượt gửi. Trường hợp sử dụng đã được duyệt có thể có giới hạn khác, vì vậy hãy xem remainingCount là nguồn dữ liệu vận hành chính xác tại thời điểm chạy.
Luồng chính thức này dành cho xác nhận, kết quả và nhắc việc gắn với một thao tác trong MINI App. Đây không phải hộp thư hỗ trợ tự do, API phát nội dung quảng bá hay luồng nhắn tin Zalo.

Điều kiện cần có trước khi phát hành notification token

Hướng dẫn này bắt đầu sau bước xác định ứng dụng đủ điều kiện. Nếu bạn vẫn chưa chắc ứng dụng có thể dùng tin nhắn dịch vụ trong production hay không, hãy đọc trước danh sách kiểm tra LINE MINI App đã xác minh và chưa xác minh.

Trước khi triển khai luồng token, hãy xác nhận đủ bốn điều kiện:

Điều kiện	Trạng thái bắt buộc	Vì sao quan trọng
Kênh LINE MINI App	Đã xác minh để chạy production	Ứng dụng chưa được xác minh không thể gửi tin nhắn dịch vụ từ kênh Published
Template tin nhắn dịch vụ	Đã thêm, được phê duyệt và có trạng thái `PUBLISHING`	API chỉ chấp nhận đúng tên template đã qua xét duyệt và các biến được định nghĩa trong template đó
Thao tác của người dùng	Đặt chỗ, mua hàng, check-in, giao hàng hoặc thao tác khác đã được phê duyệt	Mỗi thông báo phải xác nhận hoặc phản hồi đúng thao tác đó
Thông tin xác thực phía máy chủ	Stateless hoặc short-lived channel access token	Kênh LINE MINI App không chấp nhận thông tin xác thực dài hạn hoặc Channel Access Token v2.1

LINE khuyến nghị dùng stateless channel access token vì ứng dụng không phải tự quản lý thời điểm hết hạn. Chỉ lưu channel access token trên máy chủ; tuyệt đối không trả token này về client của MINI App.

Phân biệt ba loại token của LINE

Kiến trúc sẽ dễ hiểu hơn khi mỗi loại thông tin xác thực chỉ đảm nhiệm một vai trò:

Thông tin xác thực	Nguồn cấp	Chứng minh điều gì	Quy tắc vòng đời quan trọng
LIFF access token	`liff.getAccessToken()` trong MINI App	Người dùng LINE hiện tại đã cấp quyền truy cập	Có hiệu lực tối đa 12 giờ, nhưng có thể bị thu hồi khi người dùng đóng ứng dụng
Channel access token	Thông tin xác thực LINE ở phía máy chủ	Kênh LINE MINI App của bạn được phép gọi API	Nên dùng stateless token khi có thể; không để lộ cho trình duyệt
Service notification token	`POST /message/v3/notifier/token`	Một người dùng đủ điều kiện nhận thông báo gắn với một thao tác	Gắn với người dùng, có hiệu lực tối đa một năm, bị giới hạn số lượt và được làm mới sau mỗi lần gửi

Một LIFF access token chỉ được phát hành một service notification token. Hãy thực hiện việc trao đổi ngay sau thao tác: dù trên danh nghĩa chưa hết hạn, LIFF token vẫn có thể mất hiệu lực khi người dùng đóng MINI App hoặc cấp thêm quyền.

Cách gửi tin nhắn dịch vụ LINE MINI App bằng notification token

1. Lấy LIFF access token sau thao tác của người dùng

Gọi liff.getAccessToken() trong MINI App sau khi thao tác đặt chỗ, mua hàng hoặc một thao tác được phê duyệt khác hoàn tất thành công. Gửi giá trị đó về backend của bạn qua HTTPS. Liên kết yêu cầu backend với bản ghi thao tác nội bộ, nhưng không ghi LIFF token hoặc service notification token nhận được sau đó vào log ứng dụng.

Trình duyệt không nên gọi trực tiếp Service Message API vì cả thao tác phát hành token lẫn gửi tin đều cần channel access token.

2. Đổi LIFF token lấy service notification token

Từ máy chủ, gọi endpoint phát hành chính thức:

curl -X POST https://api.line.me/message/v3/notifier/token \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{\"liffAccessToken\":\"${LIFF_ACCESS_TOKEN}\"}"

Phản hồi thành công có bốn trường:

{
  "notificationToken": "34c11a03-b726-49e3-8ce0-949387a9f531",
  "expiresIn": 31536000,
  "remainingCount": 5,
  "sessionId": "xD06R2407210008"
}

Mã hóa token khi lưu trữ, đồng thời lưu expiresIn, remainingCount, sessionId và mã định danh người dùng-thao tác trong hệ thống của bạn. Không dùng sessionId làm định danh người dùng: service notification token đã chứa ràng buộc với người nhận và không thể dùng cho người khác.

3. Gửi một template đã được phê duyệt

Dùng token với endpoint gửi chính thức. Query parameter target=service là bắt buộc:

curl -X POST "https://api.line.me/message/v3/notifier/send?target=service" \
  -H "Authorization: Bearer ${LINE_CHANNEL_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "thankyou_msg_en",
    "params": {
      "date": "2026-07-21",
      "username": "Brown & Cony"
    },
    "notificationToken": "34c11a03-b726-49e3-8ce0-949387a9f531"
  }'

Sử dụng chính xác templateName và các key của biến hiển thị trong LINE Developers Console. Tên template có định dạng {template name}_{BCP 47 language tag} và dài tối đa 30 ký tự. Các hậu tố ngôn ngữ được hỗ trợ cho tin nhắn dịch vụ là ja, en, zh-TW, th, id và ko. Nếu template được chọn không có biến, params vẫn là trường bắt buộc và phải có giá trị {}.

4. Lưu token mới sau mỗi lần gửi

Khi gửi thành công, LINE trả về một notificationToken khác, cùng với expiresIn, remainingCount đã cập nhật và sessionId vẫn thuộc thao tác ban đầu. Hãy cập nhật bản ghi theo cơ chế atomic trước khi lên lịch lời nhắc tiếp theo. Dùng lại token cũ có thể khiến một lần gửi tiếp theo vốn hợp lệ bị lỗi.

Nếu cả expiresIn và remainingCount đều bằng 0, LINE đã chấp nhận tin nhắn hiện tại nhưng không thể làm mới token. Hãy đánh dấu phiên thao tác là hoàn tất và không lên lịch gửi thêm từ phản hồi này.

Danh sách kiểm tra lưu trữ và thử lại

Hãy coi service notification token là thông tin xác thực được luân chuyển, không phải địa chỉ người dùng cố định:

Tạo một bản ghi thao tác khi người dùng hoàn tất hành động đủ điều kiện trong MINI App.
Chỉ đổi LIFF token một lần, rồi lưu sessionId, token đã mã hóa, thời hạn và số lượt còn lại.
Khóa hoặc đánh version bản ghi thao tác trong lúc gửi để hai worker không tiêu thụ cùng một token đồng thời.
Khi nhận HTTP 200, hãy commit token mới và các bộ đếm trước khi đưa lời nhắc kế tiếp vào hàng đợi.
Khi nhận 400, hãy kiểm tra body, trạng thái người nhận và biến template trước khi thử lại.
Khi nhận 401, hãy làm mới thông tin xác thực của channel ở phía máy chủ hoặc bắt đầu một luồng thao tác người dùng mới; không liên tục gửi lại LIFF token hoặc service notification token đã mất hiệu lực.
Khi nhận 403, hãy kiểm tra channel đã được cấp quyền và đúng template đang tồn tại ở trạng thái được phép.

Không tự đặt một chính sách thử lại theo số lần cố định cho LINE. Tài liệu chính thức mô tả các nhóm lỗi nhưng không công bố request rate cố định cho API này. Chỉ thực hiện số lần thử lại có giới hạn đối với lỗi tạm thời, và không biến một thao tác thất bại thành thông báo không liên quan.

UnifyPort nằm ở đâu trong kiến trúc này?

Hãy dùng Service Message API chính thức của LINE cho thông báo giao dịch phát sinh từ MINI App. UnifyPort không phát hành hoặc làm mới service notification token của LINE, không gửi template để xét duyệt, không cấp trạng thái verified và không biến tin nhắn thông thường thành tin nhắn dịch vụ MINI App.

UnifyPort phục vụ một luồng riêng cho hội thoại hỗ trợ tự do. Nếu khách hàng mở một cuộc trò chuyện LINE thông thường trước hoặc sau thông báo giao dịch, tài khoản LINE đã kết nối có thể chuyển nội dung nhận được thành sự kiện chuẩn message.received. Hệ thống hỗ trợ sau đó có thể định tuyến sự kiện này cùng WhatsApp, Telegram, Zalo, TikTok hoặc X và dùng POST /v1/messages khi ma trận khả năng của provider xác nhận có hỗ trợ. Vì vậy, hội thoại Zalo hoặc chat chăm sóc khách hàng thông thường là một luồng riêng; chúng không dùng notification token của LINE MINI App.

Cách tách biệt này cũng là kiến trúc được mô tả trong hướng dẫn thanh toán LINE MINI App và webhook hỗ trợ: API MINI App chính thức phụ trách giao dịch, còn pipeline tin nhắn khách hàng phụ trách hội thoại thông thường. Với luồng thứ hai, hãy bắt đầu từ hướng dẫn ủy quyền LINE và tài liệu chính xác về sự kiện message.received.

Giới hạn và đánh đổi

Luồng tin nhắn dịch vụ chính thức phù hợp khi một MINI App đã được xác minh cần xác nhận đặt chỗ, báo kết quả hoặc nhắc người dùng về thao tác họ đã hoàn tất. Thông báo luôn được gắn với người dùng LINE, template đã xét duyệt và trường hợp sử dụng đã được chấp thuận.

Phạm vi này được giới hạn có chủ đích. Mỗi thao tác thông thường cho phép tối đa năm tin nhắn, template phải qua xét duyệt, còn quảng cáo, phiếu giảm giá, phần thưởng, quảng bá sản phẩm và thông báo sự kiện chung đều bị cấm. LY Corporation có thể chỉ định số lượt khác trong quá trình xét duyệt. Mỗi channel có thể cấu hình tối đa 20 template, và mục đích tin nhắn phải tiếp tục phù hợp với trường hợp sử dụng đã đăng ký.

Một giao diện không chính thức không thể thay đổi các quy tắc đó hoặc tăng số lượt của token. Ngược lại, Service Message API cũng không thay thế hộp thư chăm sóc khách hàng mở cho hội thoại thông thường. Hãy nối hai hệ thống bằng mã đơn hàng hoặc mã đặt chỗ của riêng bạn, thay vì cố dùng chung token nền tảng giữa chúng.

Câu hỏi thường gặp

Service notification token của LINE có hiệu lực bao lâu?

Token mới phát hành hết hạn sau một năm, tức 31.536.000 giây. Token có thể mất khả năng sử dụng sớm hơn khi số lượt tin nhắn về 0. Luôn dựa trên giá trị expiresIn và remainingCount mới nhất do LINE trả về.

Tôi có thể dùng lại cùng một notification token cho tin nhắn dịch vụ sau không?

Hãy dùng notificationToken mới được trả về từ lần gửi thành công gần nhất, không dùng giá trị trước đó. Token cũng chỉ gắn với một người dùng và không thể tái sử dụng cho người nhận khác.

Mỗi thao tác của người dùng được gửi bao nhiêu tin nhắn dịch vụ LINE MINI App?

Giới hạn tiêu chuẩn là năm tin nhắn cho một thao tác người dùng đủ điều kiện. LINE có thể phê duyệt giới hạn khác cho từng trường hợp sử dụng, vì vậy remainingCount trong phản hồi mới là giới hạn vận hành.

LINE MINI App chưa được xác minh có dùng được notification token API không?

Ứng dụng có thể thử nghiệm qua kênh Developing nội bộ với tài khoản Admin hoặc Tester. Muốn gửi từ kênh Published đến người dùng production, LINE MINI App phải được xác minh và template phải được phê duyệt.

Service notification token của LINE có giống user ID của Messaging API không?

Không. Đây là quyền gửi tin nhắn dịch vụ được luân chuyển, gắn với một người dùng và một thao tác trong MINI App. Token này không phải địa chỉ người dùng có thể tái sử dụng, thông tin xác thực push message dùng chung hay định danh chat hỗ trợ.

Bước tiếp theo

Triển khai luồng hai lần gọi chính thức theo tài liệu tham chiếu LINE MINI App API và lưu token mới sau mỗi lần gửi. Nếu yêu cầu riêng của bạn là nhận tin nhắn LINE thông thường từ khách hàng, hãy dùng hướng dẫn ủy quyền LINE của UnifyPort làm luồng thứ hai.

Nguồn tham khảo

Các nguồn chính thức của LINE được kiểm tra ngày 2026-07-21: