> ## 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 SendGrid
> Kết nối SendGrid với ChatbotX để tạo hoặc cập nhật Marketing Contact và thêm liên hệ vào list đã chọn từ Flow.
Tích hợp **SendGrid** giúp bạn tạo hoặc cập nhật Marketing Contact từ ChatbotX ngay trong Flow. Action dùng email để nhận diện Contact, đồng thời có thể thêm Contact vào List và đồng bộ số điện thoại cùng Custom Fields.
Ví dụ: sau khi khách đăng ký nhận thông tin sản phẩm, ChatbotX gửi email, số điện thoại và sở thích của khách sang SendGrid để bạn phân nhóm và cá nhân hóa chiến dịch email.
## Chuẩn bị API Key
Bạn cần tạo **API Key** có quyền đọc và ghi dữ liệu Marketing trong SendGrid. Chỉ cấp các quyền cần thiết để ChatbotX truy cập Lists, Contacts và Custom Fields.
Đăng nhập tài khoản Twilio SendGrid mà bạn muốn kết nối với ChatbotX.
Từ menu bên trái, chọn **Settings > API Keys**.
Nhấn **Create API Key**, nhập tên giúp bạn nhận biết khóa và chọn **Custom Access**.
Đặt quyền **Marketing** thành **Full Access** để khóa có thể đọc và ghi Marketing Contacts, Lists cùng Custom Fields.
Nhấn **Create & View**, sau đó sao chép khóa và lưu ở nơi an toàn. SendGrid chỉ hiển thị đầy đủ API Key một lần.
Xem hướng dẫn chính thức tại [API Keys](https://www.twilio.com/docs/sendgrid/ui/account-and-settings/api-keys).
Không chia sẻ API Key trong email, tin nhắn, ảnh chụp công khai hoặc tài liệu dành cho khách hàng. Nếu khóa bị lộ, hãy xóa khóa cũ, tạo khóa mới và cập nhật kết nối trong ChatbotX.
## Kết nối SendGrid với ChatbotX
Trong workspace ChatbotX, chọn **Settings** từ menu bên trái.
Chọn tab **Integrations**, sau đó mở mục **SendGrid**.
Nhấn **Connect** để mở cửa sổ **Connect SendGrid**.
Dán khóa vào trường **API Key**, sau đó nhấn **Confirm**.
Khi khóa hợp lệ và có đủ quyền Marketing, ChatbotX lưu kết nối rồi tải Lists cùng Custom Fields từ SendGrid để sử dụng trong Flow.
## Thêm SendGrid vào Flow
Hãy đặt action SendGrid 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 để SendGrid nhận diện Marketing Contact.
Chọn **Flows**, sau đó mở Flow mà bạn muốn dùng để thu thập Contact.
Trong Send Message node, nhấn **+ Create** rồi chọn **Actions**.
Mở **Email Actions** và chọn **Add Contact to SendGrid**.
Nhấn **Edit** trên action vừa thêm để chọn List và đồng bộ dữ liệu Contact.
## Cấu hình Add Contact to SendGrid
Thiết lập các trường trong cửa sổ **SendGrid**, sau đó nhấn **Save**.
| Trường | Cách thiết lập |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **List** | Chọn List sẽ nhận Marketing Contact. Nếu bỏ trống, Contact vẫn được tạo hoặc cập nhật trong **All Contacts**. 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. SendGrid dùng email để tạo Contact mới hoặc cập nhật Contact đã tồn tại. |
| **Phone field** | Chọn trường số điện thoại cần đồng bộ sang SendGrid. Trường này không bắt buộc. |
| **Custom Fields in SendGrid** | Chọn trường ChatbotX ở bên trái và Custom Field SendGrid tương ứng ở bên phải. Nhấn **+ Add custom field** để thêm hàng đồng bộ. |
Action hiển thị hai kết quả để bạn tiếp tục Flow:
* **Success**: SendGrid đã chấp nhận và đưa yêu cầu tạo hoặc cập nhật Contact vào hàng đợi xử lý.
* **Error**: Yêu cầu bị từ chối do email, API Key, quyền truy cập 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.
SendGrid xử lý yêu cầu thêm hoặc cập nhật Contact theo cơ chế bất đồng bộ. Contact có thể chưa xuất hiện ngay trong **Marketing > Contacts** dù Flow đã đi qua nhánh **Success**.
## Đồng bộ Custom Fields
Custom Fields giúp bạn lưu thêm dữ liệu để phân nhóm Contact hoặc cá nhân hóa nội dung email.
Trước khi cấu hình action, hãy tạo các Custom Fields cần dùng trong **Marketing > Contacts** của SendGrid. Sau đó, chọn trường ChatbotX có kiểu dữ liệu phù hợp cho từng Custom Field.
Ví dụ:
| Dữ liệu SendGrid | Dữ liệu ChatbotX phù hợp |
| ----------------- | -------------------------------------------------------- |
| Sở thích sản phẩm | Custom Field lưu loại sản phẩm khách quan tâm. |
| Khu vực | Custom Field lưu tỉnh, thành phố hoặc khu vực giao hàng. |
| Ngày sinh | Custom Field lưu ngày sinh đúng định dạng. |
## Ví dụ thu thập khách nhận thông tin sản phẩm
Một cửa hàng thời trang muốn thêm khách đăng ký qua chatbot vào danh sách giới thiệu bộ sưu tập mới.
Dùng Get User Data để hỏi email, số điện thoại và loại sản phẩm khách quan tâm.
Chạy **Add Contact to SendGrid**, chọn List cần nhận Contact và trường **Email**.
Chọn trường **Phone** và đồng bộ sở thích sản phẩm vào Custom Field tương ứng.
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.
## 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ở **Marketing > Contacts** trong SendGrid và chờ Contact xuất hiện.
* Kiểm tra Contact nằm trong đúng List nếu bạn đã chọn List.
* Kiểm tra email, số điện thoại và Custom Fields đã nhận đúng dữ liệu.
* 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 hoặc Custom Fields không hiển thị, kiểm tra quyền Marketing của API Key rồi kết nối lại.
Chỉ thêm Contact vào chiến dịch Email Marketing khi khách đã đồng ý nhận thông tin. Việc tạo Marketing Contact không tự xác nhận sự đồng ý và không thay thế quy trình xử lý yêu cầu hủy đăng ký.