> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Magic Links

> Hướng dẫn tạo và sử dụng Magic Links trong ChatbotX để tạo đường dẫn điều hướng thông minh, tự động truyền tham số đo lường (UTM) và tracking dữ liệu.

**Magic Links** là tính năng tạo đường dẫn điều hướng thông minh (Deep Links), cho phép bạn tạo ra các liên kết theo dõi công khai (Public Tracking URL). Khi người dùng nhấp vào Magic Link, hệ thống sẽ tự động chuyển hướng (redirect) tới đường dẫn đích (**URL**), đồng thời tự động bắt và truyền các tham số động từ chuỗi truy vấn (Query String) bằng cú pháp ngoặc nhọn kép `{{variable_name}}`.

Tính năng này giúp doanh nghiệp đo lường chính xác hiệu quả của từng chiến dịch quảng cáo, tự động gắn tham số UTM đo lường lên website, hoặc tự động truyền dữ liệu người giới thiệu vào kịch bản chatbot (Messenger, WhatsApp, Telegram).

## Cách truy cập tính năng Magic Links

Từ thanh điều hướng bên trái của ChatbotX, chọn **Tools** và nhấn vào thẻ **Magic Links**.

<Frame>
  <img src="https://mintcdn.com/chatbotx/lQwypKcaY4LLMTWc/images/tools_magic_links_card.png?fit=max&auto=format&n=lQwypKcaY4LLMTWc&q=85&s=4a09fb94b9256a809cf58efe478de688" alt="Tools Magic Links Card" width="2356" height="1468" data-path="images/tools_magic_links_card.png" />
</Frame>

## Hướng dẫn tạo mới Magic Link

<Steps>
  <Step title="Mở trang quản lý Magic Links">
    Tại trang **Magic Links**, nhấn nút **+ Create Magic Links** ở góc trên bên phải.
  </Step>

  <Step title="Điền thông tin trong hộp thoại Create Magic Link">
    Trong cửa sổ cấu hình, bạn điền 2 trường thông tin sau:

    * **Name**: Đặt tên nhận diện cho Magic Link (chỉ sử dụng chữ cái, chữ số, dấu gạch dưới `_` và dấu gạch nối `-`). Giá trị này sẽ được đính kèm ngay sau chuỗi gốc `/r/BOT_ID/` trong đường dẫn tracking công khai (ví dụ: `https://app.chatbotx.io/r/11588479527206912/Ads`).
    * **URL**: Nhập đường dẫn đích mà bạn muốn chuyển hướng khách hàng tới. Sử dụng cú pháp ngoặc nhọn kép `{{variable_name}}` để tự động lấy giá trị tham số từ Query String của Public Tracking Link.
  </Step>

  <Step title="Hoàn tất khởi tạo">
    Nhấn nút **Create** để lưu và tạo Magic Link.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/chatbotx/lQwypKcaY4LLMTWc/images/create_magic_link_modal.png?fit=max&auto=format&n=lQwypKcaY4LLMTWc&q=85&s=5358f3ac78e293bb94b39e1847f38ec7" alt="Create Magic Link Modal" width="2641" height="1413" data-path="images/create_magic_link_modal.png" />
</Frame>

## Các mẫu URL chuẩn cho trường URL

Dưới đây là các cấu trúc đường dẫn mẫu chuẩn dành cho từng mục đích sử dụng phổ biến mà bạn có thể sao chép và điền vào ô **URL**:

### 1. Mẫu link Facebook Messenger (Kèm Ref Payload động)

Dùng khi bạn muốn chuyển hướng khách hàng vào Messenger và tự động kích hoạt kịch bản chatbot kèm các thông số chiến dịch.

* **Cấu trúc chuẩn:** `https://m.me/PAGE_USERNAME?ref={{ref_name}}`
* **Mẫu điền vào ô URL:** `https://m.me/chatbotx?ref=ads.{{campaign}}.{{source}}`
* **Cách hoạt động:** Khi bạn chạy quảng cáo với Public Tracking URL `https://app.chatbotx.io/r/11588479527206912/Ads?campaign=summer_sale&source=facebook`, khách hàng nhấp vào link sẽ được điều hướng thẳng tới Messenger với đường dẫn `https://m.me/chatbotx?ref=ads.summer_sale.facebook`.

### 2. Mẫu link Website / Landing Page (Đo lường tham số UTM)

Dùng khi bạn chạy quảng cáo và muốn tự động chuyển tiếp các tham số đo lường UTM từ đường link quảng cáo sang đường dẫn website đích.

* **Cấu trúc chuẩn:** `https://yourdomain.com/landing-page?utm_source={{source}}&utm_medium={{medium}}&utm_campaign={{campaign}}`
* **Mẫu điền vào ô URL:** `https://chatbotx.io/khuyen-mai?utm_source={{source}}&utm_campaign={{campaign}}&utm_content={{ad_id}}`
* **Cách hoạt động:** Khi khách nhấp vào Public Tracking URL `https://app.chatbotx.io/r/11588479527206912/Ads?source=facebook&campaign=black_friday&ad_id=123`, hệ thống tự động bắt các giá trị và chuyển hướng về `https://chatbotx.io/khuyen-mai?utm_source=facebook&utm_campaign=black_friday&utm_content=123`.

### 3. Mẫu link WhatsApp Business

Dùng để đưa khách hàng vào ứng dụng WhatsApp kèm câu thoại/mã tham chiếu chuẩn bị sẵn.

* **Cấu trúc chuẩn:** `https://wa.me/PHONENUMBER?text=/ref_{{campaign}}`
* **Mẫu điền vào ô URL:** `https://wa.me/84912345678?text=/ref_{{campaign}}`

### 4. Mẫu link Telegram Bot

Dùng để khởi động Telegram Bot kèm mã giới thiệu hoặc mã ưu đãi.

* **Cấu trúc chuẩn:** `https://t.me/BOT_USERNAME?start={{ref_code}}`
* **Mẫu điền vào ô URL:** `https://t.me/bnn_xbot?start=promo_{{coupon}}`

### Bảng tổng hợp các mẫu link chuẩn

| Kênh / Mục đích          | Mẫu link chuẩn điền vào ô URL                                                 |
| ------------------------ | ----------------------------------------------------------------------------- |
| Facebook Messenger       | `https://m.me/PAGE_USERNAME?ref={{ref_name}}`                                 |
| Website (UTM Parameters) | `https://yourdomain.com/page?utm_source={{source}}&utm_campaign={{campaign}}` |
| WhatsApp Business        | `https://wa.me/PHONENUMBER?text=/ref_{{campaign}}`                            |
| Telegram Bot             | `https://t.me/BOT_USERNAME?start={{ref_code}}`                                |

## Quản lý và Thao tác trên Magic Links

Sau khi khởi tạo, Magic Link sẽ xuất hiện trong bảng danh sách quản lý. Nhấn vào biểu tượng menu **...** ở cuối mỗi dòng để thực hiện các thao tác:

* **Copy URL**: Sao chép đường dẫn Public Tracking URL công khai dạng `https://app.chatbotx.io/r/11588479527206912/Ads` để dán vào bài viết quảng cáo, bài đăng mạng xã hội hoặc nút bấm.
* **QR Code**: Tự động tạo mã QR Code tương ứng cho Magic Link.
* **View Analytics**: Mở trang phân tích dữ liệu chi tiết (xem tổng số lượt nhấp chuột, thống kê theo thời gian thực).
* **Edit**: Chỉnh sửa lại Tên (**Name**) hoặc Đường dẫn đích (**URL**).
* **Delete**: Xóa Magic Link khỏi hệ thống.

<Frame>
  <img src="https://mintcdn.com/chatbotx/UCBia8TETJcCU-nB/images/magic_links_item_actions.png?fit=max&auto=format&n=UCBia8TETJcCU-nB&q=85&s=4a8825922a4afe34c5721bd1f4c0f5be" alt="Magic Links Item Actions" width="2059" height="898" data-path="images/magic_links_item_actions.png" />
</Frame>

## Mẹo thực tiễn và Lưu ý

<Note>
  Giá trị nằm trong cặp ngoặc nhọn kép `{{variable_name}}` trong trường **URL** sẽ được tự động thay thế bằng giá trị tương ứng truyền vào từ Query String của Public Tracking Link. Nếu Query String không chứa tham số đó, biến `{{variable_name}}` sẽ được để trống một cách an toàn.
</Note>

<Warning>
  Khi đặt tên trong ô **Name**, bạn chỉ được sử dụng chữ cái không dấu, chữ số, dấu gạch dưới `_` và dấu gạch nối `-`. Không sử dụng khoảng trắng hoặc ký tự đặc biệt để tránh làm hỏng cấu trúc đường dẫn tracking công khai.
</Warning>