Cẩm nang August 8, 2026

Cách triển khai nút hành động tùy chỉnh trong LINE MINI App

Nút hành động tùy chỉnh của LINE MINI App nằm trong phần nội dung ứng dụng và mở màn hình chọn người nhận. Người dùng chọn bạn bè, nhóm hoặc cuộc trò chuyện, sau đó liff.shareTargetPicker() gửi thẻ chia sẻ do nhà phát triển chuẩn bị dưới danh nghĩa người dùng. Phần triển khai cần tuân thủ định dạng Flex Message của LINE, dùng permanent link và phân biệt rõ thành công, hủy thao tác và lỗi.

Điểm chính

Nút có sẵn trên header tự chia sẻ trang hiện tại; nút tùy chỉnh trong nội dung cho phép kiểm soát nội dung thẻ.
Cả LINE MINI App chưa xác minh và đã xác minh đều có thể dùng nút này. Đây không phải quyền gửi Service Message trên production.
Người dùng phải đăng nhập và share target picker phải được bật trong LINE Developers Console.
Thẻ chia sẻ tùy chỉnh dùng một Flex Message bubble, không dùng carousel.
Chỉ { status: "success" } xác nhận thao tác chia sẻ; Promise resolve không có object nghĩa là người dùng đã hủy.

Nút hành động tùy chỉnh khác gì các API tin nhắn

Hướng dẫn chính thức của LINE phân biệt hai nút. Nút trên header do LINE hiển thị, chia sẻ trang đang mở và không cho tùy biến hành vi hay nội dung. Nút trong phần nội dung chuyển thẻ do ứng dụng tạo sang màn hình chọn người nhận.

Tiêu chí	Custom action button	Service Message	Messaging API
Bên khởi tạo	Người dùng nhấn và chọn người nhận	Server gửi sau hành động hợp lệ trong MINI App	Official Account trả lời hoặc gửi tin
API	`liff.shareTargetPicker()` trong MINI App	Service Message API trên server	Messaging API trên server
Người gửi hiển thị	Người dùng chia sẻ	Phòng thông báo MINI App theo khu vực	LINE Official Account
Điều kiện xác minh	Dùng được ở cả hai trạng thái	Production cần MINI App đã xác minh	Theo quy định Official Account

Xem giới hạn MINI App chưa xác minh và đã xác minh nếu câu hỏi là điều kiện tính năng, hoặc so sánh Service Message và Messaging API nếu cần chọn luồng thông báo. Nút tùy chỉnh không cấp quyền cho hai API đó.

Checklist triển khai nút hành động LINE MINI App

Khởi tạo LIFF, xác nhận người dùng đã đăng nhập và bật share target picker trong LINE Developers Console. LIFF API Reference nêu rõ cả hai điều kiện.

Trước khi bật nút, kiểm tra liff.isApiAvailable("shareTargetPicker"). Trình duyệt ngoài trên điện thoại cần phiên SSO; chỉ auto login có thể khiến màn hình đăng nhập email xuất hiện thay vì picker. Hãy kiểm thử cả LIFF browser lẫn đường dẫn trình duyệt ngoài thực tế.

2. Tạo Flex Message theo định dạng quy định

LINE yêu cầu một container bubble và không cho dùng carousel cho thẻ này. Card cần title, subtitle hoặc detail, vùng button và footer nhận diện MINI App. Hãy dùng đúng property trong tài liệu thay vì xem ví dụ như một canvas Flex tự do.

Có thể thêm tối đa ba nút; ít nhất một nút phải mở trang chi tiết của nội dung được chia sẻ. Footer hiển thị icon, tên MINI App và quay về trang đầu.

3. Dùng permanent link cho trang chi tiết

Không đặt endpoint URL thông thường vào nút cần mở lại một màn hình cụ thể trong MINI App. Tài liệu permanent link đưa ra công thức:

LIFF URL + (URL trang MINI App - Endpoint URL) = permanent link

Với LIFF URL https://miniapp.line.me/123456-abcdefg và trang https://example.com/orders/42?from=share, kết quả là:

https://miniapp.line.me/123456-abcdefg/orders/42?from=share

Link có thể chứa path, query và hash. Kiểm thử trong LINE khi chưa đăng nhập, đơn hàng hết hạn hoặc nội dung đã bị xóa. Nút header tự tạo link cho trang hiện tại; nút trong thẻ tùy chỉnh thì ứng dụng phải tạo.

4. Gọi API từ thao tác nhấn rõ ràng

Dữ liệu card nên lấy từ bản ghi đã được server kiểm tra quyền, không lấy thẳng từ tham số URL.

async function shareItem(messages) {
  if (!liff.isApiAvailable("shareTargetPicker")) {
    return { outcome: "unavailable" };
  }
  try {
    const result = await liff.shareTargetPicker(messages);
    return result?.status === "success"
      ? { outcome: "shared" }
      : { outcome: "cancelled" };
  } catch (error) {
    return { outcome: "failed", error };
  }
}

messages vẫn phải chứa Flex Message bubble đúng với hướng dẫn LINE hiện hành.

5. Tách thành công, hủy và lỗi

Kết quả	Hành vi API	Cách xử lý
Đã chia sẻ	Resolve với `{ status: "success" }`	Chỉ báo thao tác hoàn tất, không khẳng định người nhận đã xem
Hủy	Resolve không có object	Trở lại trang, không hiện lỗi
Lỗi trước khi hiện picker	Reject với `LiffError`	Ghi mã lỗi an toàn và cho phép thử lại

LINE không cung cấp số người nhận. Không nên biến kết quả thành công thành số liệu giao tin, lượt xem hay chuyển đổi.

6. Kiểm thử trên thiết bị thật

Hãy kiểm tra trạng thái đăng nhập/chưa đăng nhập, LIFF browser/trình duyệt ngoài, picker bật/tắt, một/nhiều người nhận, hủy, deep link hợp lệ/hết hạn và nội dung tiếng Việt dài. OpenChat không nằm trong nhóm người nhận được hỗ trợ.

UnifyPort phù hợp ở đâu

UnifyPort không triển khai liff.shareTargetPicker(), giao diện chọn người nhận, layout Flex Message hay phân tích người nhận. Đây là chức năng chính thức của LINE MINI App và LIFF.

UnifyPort xử lý một hành động khác: khách hàng gửi tin nhắn tới tài khoản LINE đã kết nối. Tin nhắn được hỗ trợ có thể đến dưới dạng sự kiện chuẩn hóa message.received. Khi webhook endpoint có signing_secret, backend xác minh HMAC-SHA256 qua X-Device-Timestamp và X-Device-Signature.

Nếu trang được chia sẻ sau đó tạo ra cuộc hội thoại hỗ trợ, hãy lưu sự kiện share, order/campaign ID và hội thoại inbound thành các bản ghi riêng rồi liên kết trong hệ thống. Xem hướng dẫn xác thực LINE và ma trận hỗ trợ tin nhắn. Ma trận cũng giúp đội Việt Nam phân biệt đường nhận LINE với Zalo và WhatsApp.

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

Chỉ cần chia sẻ trang hiện tại thì nút header có sẵn đơn giản hơn và tự tạo permanent link.
Chỉ dùng nút tùy chỉnh khi cần card có hướng dẫn; nó đòi hỏi thêm kiểm thử layout, link, đăng nhập và thiết bị.
Nút không gửi âm thầm, không tự chọn người nhận, không chứng minh giao tin và không trả về số người nhận.
Nó không thay thế Service Message, Messaging API, Official Account hay luồng hỗ trợ inbound.

FAQ

LINE MINI App chưa xác minh có dùng custom action button được không?

Có. Ma trận tính năng hiện tại của LINE cho phép cả MINI App chưa xác minh và đã xác minh dùng nút này. Service Message trên production là tính năng riêng chỉ dành cho app đã xác minh.

Nút có sẵn và nút tùy chỉnh khác nhau thế nào?

Nút header có sẵn chia sẻ trang hiện tại và không tùy biến nội dung. Nút trong nội dung gửi message đúng hướng dẫn vào liff.shareTargetPicker().

Có lấy được số người nhận không?

Không. LINE không thu thập hoặc cung cấp số người nhận qua share target picker.

Vì sao Promise resolve nhưng không có `status`?

Người dùng đã đóng picker trước khi gửi. Đây là hủy thao tác, không phải lỗi API.

Nút chi tiết nên dùng URL nào?

Mọi trang ngoài trang đầu nên dùng permanent link, có thể kèm path, query hoặc hash.

Bước tiếp theo

Hoàn tất card và kiểm thử theo hướng dẫn custom action button chính thức. Nếu còn cần nhận tin nhắn khách hàng LINE thông thường, hãy bắt đầu với hướng dẫn xác thực LINE của UnifyPort.

Nguồn

Nguồn chính thức của LINE được kiểm tra ngày 08-08-2026: