> ## 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.

# Tích hợp Klaviyo

> Kết nối Klaviyo với ChatbotX để tạo hoặc cập nhật profile và thêm liên hệ vào list đã chọn từ Flow.

Tích hợp **Klaviyo** giúp bạn tạo hoặc cập nhật Profile từ dữ liệu Contact ngay trong Flow. Action dùng email để nhận diện Profile, có thể thêm Profile vào List và đồng bộ Title, Organization cùng các Custom Properties.

Ví dụ: sau khi khách để lại email để nhận tư vấn sản phẩm, ChatbotX gửi thông tin liên hệ và nhu cầu của khách sang Klaviyo để bạn phân nhóm Profile và cá nhân hóa nội dung.

## Chuẩn bị Private API Key

Bạn cần tạo **Private API Key** trong Klaviyo trước khi kết nối. Không dùng **Public API Key / site ID**, vì loại khóa này không cấp quyền tạo hoặc cập nhật Profile.

<Steps>
  <Step title="Đăng nhập Klaviyo">
    Đăng nhập tài khoản Klaviyo mà bạn muốn kết nối với ChatbotX.
  </Step>

  <Step title="Mở API keys">
    Mở **Settings**, chọn tab **General**, sau đó chọn **API keys** trong menu bên trái.
  </Step>

  <Step title="Tạo Private API Key">
    Trong phần **Private API Keys**, nhấn **Create Private API Key** và nhập tên giúp bạn nhận biết khóa.
  </Step>

  <Step title="Cấp quyền cần thiết">
    Cấp quyền đọc và ghi cho **Profiles** cùng **Lists**. Bạn cũng có thể dùng **Full Access**, nhưng chỉ nên cấp các quyền ChatbotX cần sử dụng.
  </Step>

  <Step title="Sao chép Private API Key">
    Hoàn tất tạo khóa, sao chép giá trị và lưu ở nơi an toàn. Klaviyo không cho xem lại toàn bộ Private API Key sau khi đóng cửa sổ tạo khóa.

    Xem hướng dẫn chính thức tại [Obtain API credentials](https://developers.klaviyo.com/en/docs/retrieve_api_credentials).

    <Frame>
      <img src="https://mintcdn.com/chatbotx/f4ikNOBcEIN2hXqg/images/create_klaviyo_private_api_key.png?fit=max&auto=format&n=f4ikNOBcEIN2hXqg&q=85&s=7bdc8778b8609a16f62470c68399e98f" alt="Create Klaviyo Private Api Key" width="2979" height="1569" data-path="images/create_klaviyo_private_api_key.png" />
    </Frame>
  </Step>
</Steps>

<Warning>
  Private API Key có thể đọc hoặc thay đổi dữ liệu theo các quyền đã cấp. Không chia sẻ khóa trong email, tin nhắn, ảnh chụp công khai hoặc tài liệu dành cho khách hàng.
</Warning>

## Kết nối Klaviyo với ChatbotX

<Steps>
  <Step title="Mở Settings">
    Trong workspace ChatbotX, chọn **Settings** từ menu bên trái.
  </Step>

  <Step title="Chọn Integrations">
    Chọn tab **Integrations**, sau đó mở mục **Klaviyo**.
  </Step>

  <Step title="Mở cửa sổ kết nối">
    Nhấn **Connect** để mở cửa sổ **Connect Klaviyo**.
  </Step>

  <Step title="Nhập API Key">
    Dán Private API Key vào trường **API Key**, sau đó nhấn **Confirm**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/f4ikNOBcEIN2hXqg/images/connect_klaviyo_in_chatbotx_integrations.png?fit=max&auto=format&n=f4ikNOBcEIN2hXqg&q=85&s=39fa7bab7191bc8578e2e65909ccdcdf" alt="Connect Klaviyo In Chatbotx Integrations" width="3185" height="1557" data-path="images/connect_klaviyo_in_chatbotx_integrations.png" />
    </Frame>
  </Step>
</Steps>

Khi khóa hợp lệ và có đủ quyền, ChatbotX lưu kết nối rồi tải các Lists từ Klaviyo để sử dụng trong Flow.

## Thêm Klaviyo vào Flow

Hãy đặt action Klaviyo sau bước thu thập email và các dữ liệu bạn muốn đồng bộ. Email phải đúng định dạng để Klaviyo tạo hoặc xác định Profile.

<Steps>
  <Step title="Mở Flow cần chỉnh sửa">
    Chọn **Flows**, sau đó mở Flow mà bạn muốn dùng để thu thập Contact.
  </Step>

  <Step title="Thêm Actions">
    Trong Send Message node, nhấn **+ Create** rồi chọn **Actions**.
  </Step>

  <Step title="Chọn Email Actions">
    Mở **Email Actions** và chọn **Add Contact to Klaviyo**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/f4ikNOBcEIN2hXqg/images/select_add_contact_to_klaviyo_action.png?fit=max&auto=format&n=f4ikNOBcEIN2hXqg&q=85&s=b917643bc88b282a20202a3ae53618ef" alt="Select Add Contact To Klaviyo Action" width="3185" height="1880" data-path="images/select_add_contact_to_klaviyo_action.png" />
    </Frame>
  </Step>

  <Step title="Mở phần cấu hình">
    Nhấn **Edit** trên action vừa thêm để chọn List và đồng bộ dữ liệu Profile.
  </Step>
</Steps>

## Cấu hình Add Contact to Klaviyo

Thiết lập các trường trong cửa sổ **Add Contact to Klaviyo**, sau đó nhấn **Save**.

| Trường                       | Cách thiết lập                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Klaviyo List**             | Chọn List sẽ nhận Profile. Nếu bỏ trống, action vẫn tạo hoặc cập nhật Profile nhưng không thêm Profile vào List. Trường này không bắt buộc. |
| **Email Field**              | Chọn trường ChatbotX đang lưu email của khách. Klaviyo dùng email để tạo Profile mới hoặc xác định Profile đã tồn tại.                      |
| **Title Field**              | Chọn trường lưu chức danh hoặc vai trò của khách. Trường này không bắt buộc.                                                                |
| **Organization Field**       | Chọn trường lưu tên công ty hoặc tổ chức của khách. Trường này không bắt buộc.                                                              |
| **Custom Fields in Klaviyo** | Chọn trường Contact ở bên trái và nhập Klaviyo property key ở bên phải. Nhấn **Add mapping** để thêm hàng đồng bộ.                          |

<Frame>
  <img src="https://mintcdn.com/chatbotx/f4ikNOBcEIN2hXqg/images/configure_add_contact_to_klaviyo.png?fit=max&auto=format&n=f4ikNOBcEIN2hXqg&q=85&s=b61dac58c9d968d1492ea9219b35b147" alt="Configure Add Contact To Klaviyo" width="3183" height="1885" data-path="images/configure_add_contact_to_klaviyo.png" />
</Frame>

Action hiển thị hai kết quả để bạn tiếp tục Flow:

* **Success**: Klaviyo đã xử lý yêu cầu tạo hoặc cập nhật Profile và thêm vào List nếu bạn đã chọn List.
* **Error**: Yêu cầu thất bại do email, API Key, quyền truy cập, List hoặc dữ liệu đồng bộ không hợp lệ.

Bạn có thể nối mỗi kết quả với một node khác để gửi xác nhận hoặc xử lý lỗi.

<Warning>
  **Add Contact to Klaviyo** không đăng ký Profile nhận Email Marketing và không thay đổi trạng thái consent. Chỉ thêm Profile vào List khi khách đã đồng ý nhận nội dung phù hợp.
</Warning>

## Đồng bộ Custom Properties

Custom Properties giúp bạn lưu dữ liệu riêng của từng Profile để phân nhóm, cá nhân hóa Template hoặc đặt điều kiện cho Flow trong Klaviyo.

Mỗi hàng đồng bộ gồm hai phần:

* Bên trái: trường Contact trong ChatbotX chứa dữ liệu cần gửi.
* Bên phải: property key mà Klaviyo dùng để lưu dữ liệu trên Profile.

Hãy dùng property key ngắn, dễ nhận biết và nhất quán. Nếu bạn đổi cách viết property key, Klaviyo có thể lưu dữ liệu vào một thuộc tính mới thay vì cập nhật thuộc tính cũ.

## Ví dụ thu thập khách cần tư vấn sản phẩm

Một cửa hàng thời trang muốn lưu khách quan tâm đến sản phẩm và phân nhóm theo nhu cầu.

<Steps>
  <Step title="Thu thập thông tin khách">
    Dùng Get User Data để hỏi email, chức danh, công ty và loại sản phẩm khách quan tâm.
  </Step>

  <Step title="Thêm Profile vào Klaviyo">
    Chạy **Add Contact to Klaviyo**, chọn trường **Email** và List phù hợp nếu khách đã đồng ý nhận thông tin.
  </Step>

  <Step title="Đồng bộ dữ liệu bổ sung">
    Chọn **Title Field**, **Organization Field** và đồng bộ nhu cầu sản phẩm vào Custom Property.
  </Step>

  <Step title="Xử lý kết quả">
    Nối **Success** với tin nhắn xác nhận. Nối **Error** với nhánh yêu cầu khách kiểm tra thông tin hoặc chuyển cho nhân viên.
  </Step>
</Steps>

## Kiểm tra hoạt động của tích hợp

Trước khi Publish Flow, hãy chạy thử bằng một địa chỉ email mà bạn có thể kiểm tra.

* Mở **Audience > Profiles** trong Klaviyo và xác nhận Profile xuất hiện.
* Kiểm tra email, Title, Organization và Custom Properties đã nhận đúng dữ liệu.
* Nếu đã chọn List, kiểm tra Profile xuất hiện trong đúng List.
* Kiểm tra Flow đi qua nhánh **Success** khi email hợp lệ.
* Thử một email sai định dạng để kiểm tra nhánh **Error**.
* Nếu Lists không hiển thị, kiểm tra quyền Profiles và Lists của Private API Key rồi kết nối lại.

<Warning>
  Xóa hoặc thu hồi Private API Key sẽ làm kết nối hiện tại ngừng hoạt động. Hãy tạo khóa mới và cập nhật kết nối trong ChatbotX trước khi chạy Flow lại.
</Warning>