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

# WhatsApp Usernames và BSUID

> Tìm hiểu về WhatsApp Usernames và BSUID từ năm 2026. Giải pháp quản lý danh bạ, đồng bộ CRM và kịch bản tự động hóa hiệu quả trên ChatbotX.

Bắt đầu từ năm 2026, WhatsApp chính thức áp dụng tính năng tên người dùng (username). Đây là thay đổi quan trọng đối với phương thức định danh khách hàng trên nền tảng. Nếu hệ thống quản lý hoặc kịch bản chatbot của bạn đang dùng số điện thoại làm thông tin định danh duy nhất, bản cập nhật này sẽ tác động trực tiếp đến hoạt động vận hành.

Với cập nhật mới, khách hàng có thể nhắn tin hoặc gọi điện cho doanh nghiệp mà không cần chia sẻ số điện thoại cá nhân. Thay vào đó, hệ thống trả về một mã định danh mới: **BSUID** (Business-Scoped User ID).

Trong tài liệu này, ChatbotX giải thích chi tiết về bản chất kỹ thuật của BSUID, những điểm cần chuẩn bị và các giải pháp tự động hóa giúp doanh nghiệp vận hành liền mạch.

<Frame>
  <img src="https://mintcdn.com/chatbotx/bShLjKwrjtqOj895/images/whats_app_username_and_bsuid_explained.png?fit=max&auto=format&n=bShLjKwrjtqOj895&q=85&s=445b81d2ed8c1ef41d439ce775b1a895" alt="Whats App Username And Bsuid Explained" width="1650" height="1100" data-path="images/whats_app_username_and_bsuid_explained.png" />
</Frame>

## Lý do WhatsApp ra mắt Username

Quyền riêng tư là mối quan tâm hàng đầu của người dùng nhắn tin hiện nay. Trước đây, khi bắt đầu trò chuyện với một doanh nghiệp trên WhatsApp, người dùng bắt buộc phải để lộ số điện thoại cá nhân. Điều này tạo rào cản tâm lý cho những khách hàng chỉ muốn hỏi nhanh thông tin sản phẩm hoặc nhận hỗ trợ sơ bộ.

Tính năng username ra đời nhằm tháo gỡ rào cản này:

* **Đối với người dùng:** Có thể tạo tên người dùng độc nhất (@username) và dùng tên này để nhắn tin cho doanh nghiệp thay vì số điện thoại.
* **Đối với doanh nghiệp:** Doanh nghiệp có thể thiết lập username riêng để khách hàng dễ dàng tìm kiếm trực tiếp trên thanh công cụ WhatsApp mà không cần lưu số điện thoại trước, giúp tăng tỷ lệ chuyển đổi khách hàng tiềm năng.

## So sánh nhận diện khách hàng trước và sau cập nhật

Bảng dưới đây tóm tắt các điểm thay đổi chính trong cơ chế định danh khách hàng:

| Đặc điểm | Trước cập nhật | Sau khi cập nhật |
| - | - | - |
| **Định danh chính** | Số điện thoại (`wa_id`) | BSUID (`user_id`) là bắt buộc, số điện thoại là tùy chọn |
| **Quyền riêng tư khách hàng** | Luôn hiển thị số điện thoại khi chat | Có thể ẩn số điện thoại bằng Username |
| **Khách hàng mới nhắn tin** | Nhận cả số điện thoại và `wa_id` | Chỉ nhận BSUID (nếu khách hàng dùng username ẩn số) |
| **Gửi OTP và xác thực** | Gửi trực tiếp qua số điện thoại | Cần thu thập số điện thoại trước khi gửi OTP |
| **Lịch sử tương tác cũ** | Lưu trữ theo số điện thoại | Tự động đồng bộ và mapping BSUID với số điện thoại cũ |

<Frame>
  <img src="https://mintcdn.com/chatbotx/bShLjKwrjtqOj895/images/wa_usernames_comparison.png?fit=max&auto=format&n=bShLjKwrjtqOj895&q=85&s=e10ecfd24d4d225e6a031bdac89ca93e" alt="Wa Usernames Comparison" width="600" height="406" data-path="images/wa_usernames_comparison.png" />
</Frame>

## Cơ chế hoạt động của BSUID

**BSUID** (Business-Scoped User ID) là mã định danh duy nhất do Meta tự động tạo ra cho từng cặp liên kết giữa một khách hàng cụ thể và một doanh nghiệp cụ thể. Mã định danh này cho phép bạn gửi tin nhắn và theo dõi khách hàng mà không cần biết số điện thoại của họ.

<Frame>
  <img src="https://mintcdn.com/chatbotx/bShLjKwrjtqOj895/images/wa_usernames_message_flow.png?fit=max&auto=format&n=bShLjKwrjtqOj895&q=85&s=22255cd70821d2e718ab6f1b2be7b058" alt="Wa Usernames Message Flow" width="600" height="219" data-path="images/wa_usernames_message_flow.png" />
</Frame>

### 4 Quy tắc kỹ thuật cốt lõi của BSUID

Doanh nghiệp cần nắm rõ 4 cơ chế vận hành sau của BSUID:

* **Tính độc bản theo doanh nghiệp:** Cùng một người dùng WhatsApp nhưng khi nhắn tin cho doanh nghiệp A sẽ có mã BSUID khác với khi nhắn tin cho doanh nghiệp B. Cơ chế này bảo vệ quyền riêng tư, ngăn chặn việc chia sẻ chéo dữ liệu giữa các doanh nghiệp.
* **Định dạng chuỗi cố định:** Mã BSUID bắt đầu bằng mã quốc gia ISO 3166 (2 ký tự chữ cái), theo sau bởi dấu chấm và chuỗi ký tự chữ số ngẫu nhiên (tối đa 128 ký tự). Ví dụ: `US.13491208655302741918`. Bạn cần sử dụng nguyên văn chuỗi ký tự này khi gọi API, không tự ý chỉnh sửa hay cắt ngắn.
* **Giới hạn trong Business Portfolio (Meta Business Manager):** Bạn không thể dùng mã BSUID của một Portfolio này để gửi tin nhắn cho khách hàng từ một Portfolio khác.
* **Tự động xuất hiện trong Webhook:** BSUID được Meta tự động sinh ra và trả về trong dữ liệu Webhook dưới trường `user_id`, ngay cả khi khách hàng chưa đặt username công khai.

<Warning>
  BSUID sẽ thay đổi nếu người dùng đổi số điện thoại đăng ký tài khoản WhatsApp. Khi đó, hệ thống sẽ nhận một Webhook cập nhật để đồng bộ lại dữ liệu liên kết.
</Warning>

## Hạ tầng hỗ trợ BSUID trên ChatbotX

ChatbotX đã xây dựng sẵn giải pháp công nghệ toàn diện nhằm thích ứng hoàn hảo với BSUID và hỗ trợ tối đa cho doanh nghiệp:

### Tính năng đã sẵn sàng hoạt động (Already Live)

* **Tự động thu thập BSUID:** Hệ thống tự động ghi nhận mã BSUID từ toàn bộ tương tác tin nhắn gửi đến (inbound) và tin nhắn gửi đi thành công (outbound) mà không yêu cầu cấu hình thủ công.
* **Hiển thị trong hồ sơ liên hệ:** Trường BSUID hiển thị trực tiếp trong chi tiết hồ sơ liên hệ (Contact Profile) và danh sách phân khúc khách hàng (Audience List).
* **Hỗ trợ Webhook và Open API:** Trường `bsuid` được trả về đồng thời trong toàn bộ payload Webhook và phản hồi của Open API song song với trường số điện thoại (`phone`).
* **Tự động ghép nối liên hệ (Automatic Contact Matching):** Khi khách hàng dùng username nhắn tin đến, ChatbotX sử dụng BSUID để đối chiếu chính xác với hồ sơ sẵn có, ngăn ngừa việc tạo liên hệ trùng lặp.
* **Gửi tin nhắn đa luồng qua BSUID:** Hỗ trợ gửi tin nhắn trực tiếp qua mã BSUID trong tất cả tính năng: hội thoại Live Chat, kịch bản Flows, Sequences, chiến dịch Broadcasts và Open API.
* **Tìm kiếm liên hệ theo BSUID:** Cho phép nhân viên tìm kiếm và lọc danh bạ trực tiếp bằng mã BSUID trong mục Contacts.
* **Nút thu thập số điện thoại (Get Contact Info):** Tích hợp thẻ hành động Native trong Flow Builder, cho phép khách hàng nhấn chia sẻ số điện thoại chỉ với một lần chạm (1-tap).
* **Đồng bộ một chiều sang CRM:** Hỗ trợ truyền dữ liệu BSUID từ ChatbotX sang các hệ thống CRM bên ngoài như HubSpot, Salesforce qua Webhook hoặc các công cụ tự động hóa như Make và n8n.

<Frame>
  <img src="https://mintcdn.com/chatbotx/lUMxkHs14uxL2BEj/images/whatsapp_bsuid_inbox_display.png?fit=max&auto=format&n=lUMxkHs14uxL2BEj&q=85&s=5c73069505c273d189fad9e38ac5d1ef" alt="Whatsapp Bsuid Inbox Display" width="3096" height="1824" data-path="images/whatsapp_bsuid_inbox_display.png" />
</Frame>

Trên giao diện **Live Chat Inbox** của ChatbotX:

* **Hiển thị BSUID trực quan:** Mã BSUID (ví dụ: `VN.1492361455966864`) hiển thị trực tiếp tại thanh thông tin khách hàng bên phải, giúp nhận diện khách hàng ngay cả khi ẩn số điện thoại.
* **Nhận số điện thoại 1-tap:** Thẻ dữ liệu liên hệ `[contacts]` được tiếp nhận tức thì khi khách hàng nhấn nút chia sẻ, tự động cập nhật số điện thoại vào hồ sơ BSUID tương ứng.
* **Hỗ trợ toàn diện:** Hỗ trợ viên dễ dàng theo dõi trạng thái Bot (`Bot is active`), gắn nhãn, thêm ghi chú và phân công hội thoại mượt mà.

### Lộ trình tính năng nâng cao (Rolling Out)

| Tính năng nâng cấp | Mục tiêu hỗ trợ |
| - | - |
| **Tự động hợp nhất và kết nối hội thoại** | Tự động merge hồ sơ liên hệ khi khách hàng cung cấp số điện thoại, hiển thị BSUID trực tiếp trong Live Chat Inbox và liên kết lịch sử hội thoại liền mạch. |
| **Mẫu tin nhắn Request Contact Info** | Hỗ trợ tạo và gửi Mẫu tin nhắn (Template Messages) có gắn nút Native Request Contact Info để xin số điện thoại khách hàng ngoài khung 24 giờ. |

## Tác động vận hành & Giải pháp cho doanh nghiệp

Khi WhatsApp áp dụng cơ chế định danh bằng BSUID, doanh nghiệp cần chủ động điều chỉnh 3 mảng nghiệp vụ trọng tâm sau để đảm bảo trải nghiệm khách hàng và dữ liệu liền mạch:

### Quản lý dữ liệu và CRM

Nếu cơ sở dữ liệu CRM của bạn đang dùng số điện thoại làm khóa chính (Primary Key), các cuộc hội thoại mới từ khách hàng ẩn số điện thoại có thể tạo ra các liên hệ vô danh hoặc gây lỗi đồng bộ.

* **Thách thức:** Hệ thống CRM truyền thống sẽ từ chối hoặc tạo bản ghi rỗng nếu không nhận được trường số điện thoại khi có khách hàng mới bắt đầu hội thoại.
* **Giải pháp:** Cập nhật bảng dữ liệu để lưu thêm trường `BSUID` song song với trường `Phone`. Nâng cấp logic truy vấn để tìm kiếm khách hàng theo cả 2 trường này. ChatbotX tự động liên kết trường `BSUID` vào đúng hồ sơ khách hàng ngay khi họ cung cấp số điện thoại trong hội thoại.

### Quảng cáo Click-to-WhatsApp (CTWA)

Với khách hàng nhấn vào quảng cáo Click-to-WhatsApp và bắt đầu nhắn tin, nếu họ bật chế độ ẩn số điện thoại, hệ thống sẽ ghi nhận thông tin ban đầu qua mã BSUID.

* **Thách thức:** Doanh nghiệp có thể bỏ lỡ cơ hội chuyển đổi hoặc chăm sóc lại nếu không có số điện thoại sau khi phiên quảng cáo 72 giờ kết thúc.
* **Giải pháp:** Thiết kế kịch bản mở đầu (Welcome Flow) tự động gửi tin nhắn chào mừng, đồng thời gắn nút xin thông tin liên hệ tiện lợi (Native 1-tap Get Contact Info) để thu thập số điện thoại phục vụ chăm sóc và nuôi dưỡng về sau.

### Đội ngũ hỗ trợ và CSKH (Inbox)

Trong giao diện hộp thư hội thoại (Inbox) của ChatbotX, toàn bộ cuộc trò chuyện từ khách hàng ẩn số điện thoại vẫn được tiếp nhận và xử lý mượt mà.

* **Thách thức:** Nhân viên tư vấn có thể bỡ ngỡ khi thấy hồ sơ khách hàng hiển thị mã BSUID thay vì số điện thoại quen thuộc.
* **Giải pháp:** Hướng dẫn nhân viên tư vấn nhận biết mã BSUID là định danh khách hàng hợp lệ và duy nhất. Nhân viên có thể sử dụng các kịch bản mẫu hoặc nút xin thông tin có sẵn trong Live Chat để yêu cầu khách hàng cung cấp số điện thoại khi cần xử lý các nghiệp vụ chuyên sâu (như bảo hành, giao hàng, xác thực).

## Kế hoạch hành động 5 bước cho doanh nghiệp

Để chuẩn bị tốt nhất cho các cập nhật của WhatsApp, doanh nghiệp nên thực hiện theo quy trình 5 bước sau:

<Steps>
  <Step title="Rà soát hệ thống và kịch bản">
    Kiểm tra toàn bộ các kịch bản chatbot, cổng kết nối API và cơ sở dữ liệu để xác định những vị trí đang dùng số điện thoại làm định danh bắt buộc duy nhất.
  </Step>

  <Step title="Cập nhật cấu trúc dữ liệu">
    Bổ sung trường `BSUID` vào bảng dữ liệu liên hệ (độ dài tối đa 131 ký tự, hỗ trợ ký tự đặc biệt) để lưu trữ song song với số điện thoại.
  </Step>

  <Step title="Điều chỉnh kịch bản tự động hóa">
    Cấu hình lại các Flow trên ChatbotX để hỗ trợ rẽ nhánh theo BSUID. Bổ sung khối tin nhắn xin số điện thoại tự động đối với các luồng đặt hàng hoặc gửi OTP.
  </Step>

  <Step title="Kiểm thử luồng hội thoại">
    Chạy thử nghiệm kịch bản với các tài khoản bật tính năng username để kiểm tra độ chính xác của luồng thu thập dữ liệu và tránh trùng lặp hồ sơ.
  </Step>

  <Step title="Vận hành và theo dõi">
    Đưa kịch bản mới vào hoạt động thực tế. Theo dõi tỷ lệ phản hồi, hiệu quả thu thập thông tin và trải nghiệm của khách hàng để tinh chỉnh nội dung kịp thời.
  </Step>
</Steps>

## Câu hỏi thường gặp (FAQ)

<AccordionGroup>
  <Accordion title="Số điện thoại của khách hàng cũ có bị mất không?">
    Không. Toàn bộ khách hàng đã có lịch sử tương tác trước đây vẫn được lưu trữ đầy đủ số điện thoại trong hệ thống liên hệ của ChatbotX. Bạn không cần thực hiện thu thập lại.
  </Accordion>

  <Accordion title="Việc gửi tin nhắn Broadcast bằng số điện thoại có bị ảnh hưởng không?">
    Không. Bạn vẫn gửi tin nhắn Broadcast đến danh sách số điện thoại của khách hàng cũ bình thường. Cập nhật mới chỉ áp dụng cho những khách hàng mới chủ động nhắn tin vào qua username.
  </Accordion>

  <Accordion title="Tôi có thể gửi tin nhắn OTP trực tiếp vào mã BSUID không?">
    Không. Tin nhắn xác thực OTP bắt buộc phải gửi qua số điện thoại thực tế. Do đó bạn cần thiết lập luồng xin số điện thoại trước khi kích hoạt gửi OTP.
  </Accordion>

  <Accordion title="Mã BSUID của một khách hàng ở hai thương hiệu khác nhau có giống nhau không?">
    Không. BSUID được quản lý theo từng Meta Business Portfolio riêng biệt. Nếu bạn quản lý hai thương hiệu trên hai Portfolio khác nhau, cùng một khách hàng sẽ có hai mã BSUID độc lập.
  </Accordion>

  <Accordion title="Nếu người dùng xóa username thì mã BSUID có thay đổi không?">
    Không. BSUID được tạo dựa trên mối liên kết cố định giữa tài khoản người dùng và tài khoản doanh nghiệp của bạn, độc lập với việc họ có đổi hay xóa username hiển thị hay không.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.