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

# External API Request

> Hướng dẫn cài đặt External API Request trong ChatbotX để kết nối máy chủ bên ngoài, tra cứu dữ liệu thời gian thực và tự động hóa hệ thống.

**External API Request** là một khối chức năng mạnh mẽ thuộc nhóm **Tools** trong trình chỉnh sửa kịch bản của ChatbotX. Tính năng này cho phép chatbot của bạn kết nối hai chiều thời gian thực (real-time) với các hệ thống máy chủ riêng, CRM (HubSpot, Salesforce), ERP, website bán hàng hay bất kỳ dịch vụ web (Web Services) nào bên ngoài thông qua giao thức HTTP.

Nhờ có External API Request, chatbot không chỉ dừng lại ở việc trả lời các câu hỏi cố định mà có thể chủ động tra cứu số dư, kiểm tra tồn kho, lấy trạng thái vận chuyển đơn hàng hoặc đẩy dữ liệu liên hệ mới thu thập sang hệ thống quản trị của doanh nghiệp.

## Cách tạo khối External API Request trong Flow Builder

Để chèn khối External API Request vào kịch bản hội thoại:

1. Trong màn hình chỉnh sửa kịch bản, nhấp vào nút **+** (hoặc nút **Create**).
2. Rê chuột vào mục **Actions** $\rightarrow$ chọn **Tools** $\rightarrow$ chọn **External API Request**.
3. Một khối hành động mới sẽ xuất hiện trên giao diện thiết kế kịch bản.

<Frame>
  <img src="https://mintcdn.com/chatbotx/dN5urTG4NXWUzSTq/images/flow_builder_actions_tools_external_api_request.png?fit=max&auto=format&n=dN5urTG4NXWUzSTq&q=85&s=e3fbe9036df5706fdcc5ce9949107350" alt="Flow Builder Actions Tools External Api Request" width="1901" height="1155" data-path="images/flow_builder_actions_tools_external_api_request.png" />
</Frame>

## Hướng dẫn cấu hình chi tiết External API Request

Nhấp vào khối **External API Request** trên màn hình để mở bảng thiết lập chi tiết. Cửa sổ cấu hình bao gồm các mục chính sau:

<Frame>
  <img src="https://mintcdn.com/chatbotx/QAoMJWc4FJm8iHUO/images/external_api_request_configuration.png?fit=max&auto=format&n=QAoMJWc4FJm8iHUO&q=85&s=02658167104c1f452ea1e33994dd03cf" alt="External Api Request Configuration" width="1022" height="1386" data-path="images/external_api_request_configuration.png" />
</Frame>

### 1. Phương thức kết nối (Request Method)

Lựa chọn phương thức HTTP tương ứng với thao tác bạn muốn máy chủ thực hiện:

* **GET**: Dùng để tra cứu và lấy dữ liệu từ máy chủ (ví dụ: kiểm tra mã giảm giá, tra cứu tồn kho sản phẩm, lấy trạng thái đơn hàng).
* **POST**: Dùng để gửi dữ liệu mới tới máy chủ (ví dụ: đẩy thông tin khách hàng tiềm năng sang CRM, tạo đơn hàng mới, ghi nhận lượt đăng ký).
* **PUT / PATCH**: Dùng để cập nhật dữ liệu đã tồn tại trên máy chủ (ví dụ: đổi địa chỉ giao hàng, cập nhật điểm tích lũy).
* **DELETE**: Dùng để gửi yêu cầu xóa dữ liệu trên máy chủ.

### 2. Đường dẫn kết nối (Request URL / Endpoint)

Nhập đường dẫn URL API máy chủ của bạn (ví dụ: `https://api.yourdomain.com/v1/orders`).

**Tính năng chèn biến động:** Bạn có thể chèn trực tiếp các trường dữ liệu Custom Field hoặc System Field của khách hàng vào URL bằng cú pháp `{{field_name}}`.

Ví dụ: `https://api.yourdomain.com/v1/orders/{{order_id}}` (trong đó `order_id` sẽ tự động thay bằng mã đơn hàng của khách hàng đang trò chuyện).

### 3. Cấu hình Header (Request Headers)

Điền các thông số tiêu đề HTTP phục vụ xác thực bảo mật hoặc khai báo định dạng dữ liệu:

* **Authorization**: `Bearer YOUR_API_KEY` (Xác thực tài khoản API).
* **Content-Type**: `application/json` (Khai báo định dạng gửi đi là JSON).

<Note>
  Khi thực hiện yêu cầu API, hệ thống ChatbotX sẽ tự động đính kèm thông tin ID người dùng đang trò chuyện trong HTTP Header dưới dạng `X-USER-ID`. Máy chủ của bạn có thể dựa vào thông số này để định danh chính xác liên hệ.
</Note>

### 4. Dữ liệu gửi đi (Request Body - đối với POST/PUT)

Khi sử dụng phương thức **POST** hoặc **PUT**, bạn chọn định dạng dữ liệu gửi đi (thường là **JSON**) và điền cấu trúc dữ liệu cần truyền sang máy chủ. Bạn có thể tự do chèn các biến dữ liệu của ChatbotX vào chuỗi JSON:

```json theme={null}
{
  "full_name": "{{full_name}}",
  "phone": "{{phone}}",
  "email": "{{email}}",
  "selected_product": "{{product_code}}"
}
```

### 5. Xử lý phản hồi trả về (Response Mapping)

Sau khi máy chủ xử lý xong và phản hồi chuỗi dữ liệu JSON về cho ChatbotX, bạn có 2 cách để xử lý kết quả này:

#### Cách 1: Ánh xạ lưu vào Custom Field (Response Mapping)

Sử dụng cú pháp **JSON Path** (ví dụ `$.data.order_status` hoặc `$.result.points`) để trích xuất giá trị cụ thể trong JSON trả về và lưu trực tiếp vào một **Custom Field** đã tạo sẵn trên ChatbotX. Sau đó, bạn có thể dùng biến Custom Field này để gửi tin nhắn phản hồi cho khách.

#### Cách 2: Trả về giao diện tương tác động (Dynamic Content)

Nếu bạn muốn máy chủ của mình tự động sinh ra tin nhắn giao diện trực quan (Card, Carousel, Quick Replies) kèm các lệnh Actions hệ thống, hãy bật tùy chọn **Dynamic Content**. Máy chủ của bạn sẽ trả về chuỗi JSON chuẩn theo cấu trúc `{"messages": [...], "actions": [...]}` để ChatbotX tự động hiển thị.

Để xem hướng dẫn chi tiết về cấu trúc JSON này, tham khảo bài viết [Dynamic Content](/vi/automation/dynamic-content).

## Các ví dụ kịch bản ứng dụng thực tế

### Ví dụ 1: Tra cứu trạng thái đơn hàng tự động

**Kịch bản:** Khách hàng nhập mã đơn hàng trong cuộc trò chuyện, Bot tự động gọi API tra cứu trên website và báo lại trạng thái.

<Steps>
  <Step title="Thu thập mã đơn hàng">
    Dùng khối **Get User Data** để hỏi và lưu mã đơn hàng của khách vào Custom Field `order_code`.
  </Step>

  <Step title="Gửi yêu cầu tra cứu External API Request">
    Cấu hình khối External API Request với phương thức **GET** tới đường dẫn `https://api.myshop.com/orders/{{order_code}}`.
  </Step>

  <Step title="Ánh xạ dữ liệu phản hồi">
    Trích xuất giá trị `$.data.status` trong JSON trả về và lưu vào Custom Field `order_status`.
  </Step>

  <Step title="Gửi tin nhắn kết quả cho khách">
    Tạo khối tin nhắn văn bản tiếp theo: "Đơn hàng {{order_code}} của bạn hiện đang ở trạng thái: {{order_status}}."
  </Step>
</Steps>

### Ví dụ 2: Tự động lưu thông tin khách hàng vào CRM / Google Sheets

**Kịch bản:** Khi khách hàng để lại Họ tên, SĐT và Email để nhận tư vấn, Bot sẽ tự động bắn thông tin này sang Webhook hệ thống CRM của doanh nghiệp.

* **Phương thức:** `POST`
* **URL:** `https://crm.yourcompany.com/api/v1/leads`
* **Request Body:**
  ```json theme={null}
  {
    "name": "{{full_name}}",
    "phone": "{{phone}}",
    "email": "{{email}}",
    "source": "ChatbotX Messenger"
  }
  ```

## Mẹo thực tiễn và Cảnh báo hệ thống

<Note>
  Sử dụng nút **Test Request** ngay trong cửa sổ cấu hình để gửi yêu cầu kiểm tra tới máy chủ. Hệ thống sẽ hiển thị kết quả JSON trả về thực tế, giúp bạn dễ dàng xác định chính xác đường dẫn JSON Path để ánh xạ biến vào Custom Field.
</Note>

<Warning>
  **Thời gian chờ phản hồi (Timeout):** Máy chủ của bạn cần phản hồi kết quả trong thời gian tối đa là 10 giây và trả về mã trạng thái HTTP Success (`200 OK`). Nếu máy chủ phản hồi quá chậm hoặc bị lỗi hệ thống (`500 Internal Server Error`), khối API sẽ tự động bỏ qua để kịch bản của khách hàng không bị kẹt.
</Warning>

<Note>
  Hãy đảm bảo các trường dữ liệu tùy chỉnh (Custom Fields) mà bạn muốn lưu kết quả từ API đã được khởi tạo trước tại mục **Settings** $\rightarrow$ **Custom Fields** của ChatbotX.
</Note>