> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Khái niệm cốt lõi
> Bản đồ về mọi thành phần trong nền tảng — mỗi đối tượng thực hiện chức năng gì, nằm ở đâu trong bảng điều khiển và API nào tương tác với đối tượng đó.
ThunderPhone là một nền tảng đầy đủ để xây dựng, vận hành và cải thiện
tác nhân AI giọng nói. Trang này là bản đồ: mọi khái niệm bạn sẽ gặp, mỗi
khái niệm trong một phần ngắn, cùng giao diện dashboard và API hỗ trợ
khái niệm đó. Đọc lướt một lần, rồi quay lại bất cứ khi nào bạn cần tìm hiểu
một thuật ngữ.
Thanh bên dashboard phản ánh cấu trúc này:
[Tác nhân](#agents), [số điện thoại](#phone-numbers),
[tiện ích web](#web-widgets), [cuộc gọi](#calls),
[cơ sở kiến thức](#knowledge-bases).
[Giám sát trực tiếp](#live-monitoring) và
[chiến dịch](#campaigns) gọi ra.
[Ứng dụng, API, máy chủ MCP và nhà cung cấp VoIP](#connections) mà
tác nhân của bạn có thể sử dụng.
[Mô phỏng](#simulations), [thử nghiệm](#experiments),
[vấn đề](#issues), [báo cáo](#reports),
[khả năng quan sát](#observability).
[Nhóm & vai trò](#team-and-roles), [khóa API](#organizations),
[cảnh báo](#alerts), [thanh toán](#billing).
[Webhook](#webhooks) và [công cụ hàm](#function-tools) cho
mã riêng của bạn.
***
## Tổ chức
Một **tổ chức** là đơn vị thuê bao. Mọi tài nguyên khác —
tác nhân, số điện thoại, cuộc gọi, khóa — đều thuộc chính xác một tổ chức.
Tài khoản của bạn có thể thuộc nhiều tổ chức; mỗi tổ chức có số dư,
khóa và danh sách thành viên riêng.
Khóa API `sk_live_` bạn tạo trong **Tổ chức → Khóa** được
liên kết với một tổ chức. Liên kết đó giúp REST API có cấu trúc phẳng:
bạn không bao giờ cần đặt id tổ chức trong đường dẫn URL, vì khóa của bạn
đã xác định tổ chức đó.
**Trên dashboard:** trình chuyển đổi tổ chức (cuối thanh bên) và
cài đặt **Tổ chức** — các tab Chung, Khóa, Cảnh báo, Cài đặt thanh toán
và Lịch sử thanh toán.
**Trong API:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).
***
## Tác nhân
Một **tác nhân** là cấu hình AI vận hành một cuộc gọi. Cấu hình này bao gồm:
* Một **prompt** quy định tác nhân nói gì và hoạt động như thế nào —
bao gồm các hành động cuộc gọi như chuyển cuộc gọi, nhấn phím và gác máy;
đây là các dòng prompt thông thường thay vì cấu hình riêng biệt.
* Một **cấp engine** (`spark`, `bolt`, `storm-*`): Spark được tối ưu
về chi phí, Bolt về tốc độ, Storm về khả năng xử lý prompt phức tạp.
* Một **giọng nói** cùng **ngôn ngữ chính** và **các ngôn ngữ bổ sung**
tùy chọn — tác nhân tự động chuyển đổi khi người gọi đổi ngôn ngữ.
Xem [Ngôn ngữ được hỗ trợ](/vi/guides/supported-languages).
* Các khả năng được gắn: [ứng dụng đã kết nối](#connections),
[kết nối API](#connections), [cơ sở kiến thức](#knowledge-bases),
[máy chủ MCP](#connections) và
[công cụ hàm](#function-tools) nội tuyến.
* Các tùy chọn hành vi: thứ tự phát lời, chế độ xác nhận, âm thanh nền,
thời gian chờ giữ máy.
Các chỉnh sửa trong trình tạo **tự động lưu thành bản nháp**; không có gì
được đưa vào hoạt động cho đến khi bạn nhấp **Triển khai**. Mỗi lần triển khai
đều được lưu ảnh chụp trong tab **Lịch sử** của trình tạo, để bạn có thể
kiểm tra và khôi phục bất kỳ phiên bản trước đó nào.
**Trên dashboard:** **Tác nhân giọng nói** → trình tạo tác nhân
(`/dashboard/agents`). Xem
[Xây dựng tác nhân AI giọng nói đầu tiên của bạn](/vi/guides/build-an-agent).
**Trong API:** [`/v1/agents`](/api-reference/agents) — CRUD,
nhân bản, chuyển, lịch sử phiên bản và công cụ hỗ trợ prompt.
***
## Số điện thoại
Một **số điện thoại** thuộc về một tổ chức và định tuyến cuộc gọi đến đến một
tác nhân AI (và có thể thực hiện cuộc gọi đi). Có hai nguồn:
* **Số demo** — số điện thoại Hoa Kỳ thật được cấp từ nhóm số của ThunderPhone,
hoạt động trong vài giây. Chỉ hỗ trợ cuộc gọi đến, chúng trả lời bằng một
thông báo miễn trừ ngắn được đọc thành lời, và dashboard giới hạn mỗi tổ chức
ở 10 số. Phù hợp cho lần thử đầu tiên; không dành cho môi trường production.
* **Số VoIP** — được đưa từ nhà cung cấp của bạn thông qua một
[kết nối VoIP](#connections). Twilio và Telnyx kết nối trực tiếp
(Telnyx có thiết lập có hướng dẫn); SignalWire và Vonage sẽ sớm được hỗ trợ —
hiện tại bạn kết nối với chúng qua cấu hình SIP thủ công, hỗ trợ mọi
SIP trunk. Sau khi được nhập và xác minh, số VoIP hỗ trợ cuộc gọi đến
và cuộc gọi đi.
Mỗi hàng số cho phép bạn đặt chế độ định tuyến, chọn tác nhân AI cho cuộc gọi đến
và gắn nhãn cho số.
**Trong dashboard:** **Số điện thoại** (`/dashboard/phone-numbers`).
Xem [Lấy số điện thoại](/vi/guides/get-a-phone-number).
**Trong API:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).
***
## Cuộc gọi
Mọi cuộc gọi đến, cuộc gọi đi, mô phỏng và phiên tiện ích đều trở thành
một **nhật ký cuộc gọi**. Một cuộc gọi chứa bản chép lời đầy đủ có nhãn vai trò,
lịch sử lượt hội thoại có cấu trúc (bao gồm lệnh gọi công cụ), bản ghi âm,
tổng chi phí thanh toán, cùng tùy chọn chấm điểm AI và báo cáo sự cố.
Khi một cuộc gọi đang **diễn ra**, bạn có thể mở cuộc gọi đó và **nghe cùng** —
bạn tham gia im lặng và không ai trong cuộc gọi nghe thấy bạn. Sau khi nghe cùng,
bạn có thể **thì thầm**: nhập một chỉ dẫn được gửi thẳng đến tác nhân AI của bạn
giữa cuộc gọi; người gọi không bao giờ nghe thấy chỉ dẫn đó và tác nhân AI sẽ làm theo
ngay trong cuộc gọi.
**Trong dashboard:** **Lịch sử cuộc gọi** (`/dashboard/call-history`) dành cho
kho lưu trữ và thông tin chi tiết từng cuộc gọi; **Trực tiếp** dành cho các cuộc gọi
đang diễn ra. Xem
[Xem lại, nghe và hướng dẫn cuộc gọi của bạn](/vi/guides/review-calls).
**Trong API:** [`/v1/calls`](/api-reference/calls) — danh sách, bản chép lời,
lịch sử, âm thanh, chấm điểm, xuất;
[`/v1/issue-reports`](/api-reference/issue-reports).
***
## Tiện ích web
**Tiện ích web** mang đến cho khách truy cập trang web của bạn một cuộc trò chuyện
qua micrô với tác nhân AI — không cần số điện thoại. Tiện ích xác thực bằng
một **khóa có thể công khai** (`pk_live_...`) được khóa theo origin đối với
các miền được phép của bạn, vì vậy an toàn khi dùng trong mã phía client.
Khóa hoạt động ở một trong hai chế độ: `agent` (được liên kết tĩnh với một
tác nhân AI) hoặc `webhook` (server của bạn chọn cấu hình cho từng khách truy cập —
xem [Cấu hình động cho từng cuộc gọi](/vi/guides/dynamic-call-config)). Phiên tiện ích
đi qua cùng hạ tầng cuộc gọi như cuộc gọi điện thoại.
**Trong dashboard:** **Tiện ích web** (`/dashboard/web-widgets`) —
tạo tiện ích, đặt chế độ và tác nhân AI, quản lý miền được phép và
sao chép đoạn mã nhúng. Xem
[Tạo tiện ích web](/vi/guides/embed-a-web-widget-dashboard).
**Trong API:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions), và
[tài liệu Widget SDK](/vi/widget/overview).
***
## Cơ sở kiến thức
Một **cơ sở kiến thức** là tập hợp tài liệu mà tác nhân AI của bạn có thể tìm kiếm
giữa cuộc gọi để làm cơ sở cho câu trả lời — tải tệp trực tiếp hoặc nhập từ
Google Drive, sau đó liên kết cơ sở kiến thức với một tác nhân AI trong
trình tạo. Tác nhân AI truy vấn cơ sở kiến thức bằng công cụ tìm kiếm tích hợp
bất cứ khi nào cuộc trò chuyện cần đến.
**Trong dashboard:** **Kiến thức** (`/dashboard/knowledge`) dành cho
thư viện tài liệu; phần **Kiến thức** trong trình tạo để liên kết cơ sở kiến thức
với tác nhân AI. Xem
[Cung cấp cơ sở kiến thức cho tác nhân AI của bạn](/vi/guides/knowledge-base).
***
## Kết nối
Kết nối là cách tác nhân AI tiếp cận thế giới bên ngoài. Bốn loại, một
nhóm trên thanh bên:
* **Ứng dụng** (`/dashboard/app-connections`) — kết nối OAuth với
Slack, HubSpot, Salesforce, Google Calendar, Google Sheets và
Cal.com. Kết nối một lần, sau đó bật các công cụ theo từng thao tác
(đăng tin nhắn Slack, tạo hoặc cập nhật liên hệ HubSpot, đặt lịch
Cal.com…) cho bất kỳ tác nhân AI nào. Xem [Kết nối ứng dụng](/vi/guides/connect-apps).
* **API** (`/dashboard/api-connections`) — biến bất kỳ HTTP API nào thành
một hành động của tác nhân AI. Dán một lệnh cURL và trình hướng dẫn AI sẽ phác thảo
định nghĩa công cụ, hoặc tự tạo thủ công; nút **Kiểm tra yêu cầu** sẽ gửi một
lệnh gọi sandbox trước khi bạn triển khai. Xem
[Kết nối API](/vi/guides/api-connections) — giao diện dashboard của
[`/v1/integrations`](/api-reference/integrations).
* **MCP** (`/dashboard/mcp-connections`) — thêm máy chủ Model Context
Protocol bằng URL và để tác nhân AI sử dụng các công cụ mà máy chủ cung cấp.
Xem [Thêm máy chủ MCP](/vi/guides/mcp-servers).
* **VoIP** (`/dashboard/voip-connections`) — thông tin xác thực nhà cung cấp để
[sử dụng số điện thoại của riêng bạn](#phone-numbers). Xem
[Kết nối nhà cung cấp VoIP](/vi/guides/voip-providers).
**Trong API:** [`/v1/integrations`](/api-reference/integrations) và
[`/v1/voip-connections`](/api-reference/voip-connections); xem thêm
[Tạo tích hợp công cụ](/vi/guides/build-tool-integration).
***
## Chiến dịch
Một **chiến dịch** thực hiện cuộc gọi đi trên quy mô lớn: tải lên CSV
chứa liên hệ, chọn tác nhân AI và số gọi đi, rồi thiết lập khung giờ gọi
(ngày và giờ, có hỗ trợ múi giờ), số cuộc gọi đồng thời và chính sách thử lại
(số lần thử tối đa và các kết quả nào — không trả lời, hộp thư thoại, thất bại —
sẽ được thử lại). Chiến dịch xử lý danh sách và ghi lại mọi cuộc gọi
trong Lịch sử cuộc gọi.
**Trong dashboard:** **Chiến dịch** (`/dashboard/campaigns`). Xem
[Chạy chiến dịch gọi đi](/vi/guides/outbound-campaigns).
**Đối với cuộc gọi lập trình một lần:** [API cuộc gọi
đi](/vi/guides/place-outbound-calls).
***
## Giám sát trực tiếp
**Trực tiếp** hiển thị mọi cuộc gọi đang diễn ra trong toàn tổ chức và cho phép bạn
mở bất kỳ cuộc gọi nào để [nghe và thì thầm](#calls) theo thời gian thực. Đây là
giao diện giám sát: theo dõi prompt mới khi nhận lưu lượng thực đầu tiên,
hoặc giám sát một chiến dịch đang chạy.
**Trong dashboard:** **Trực tiếp** (`/dashboard/live`). Xem
[Theo dõi và giám sát cuộc gọi trực tiếp](/vi/guides/monitor-live-calls).
***
## Mô phỏng
Một **mô phỏng** là một người gọi AI thực hiện cuộc trò chuyện thực với
tác nhân AI của bạn — cùng tuyến viễn thông, bản chép lời thực, chấm điểm thực —
để bạn có thể kiểm thử trước (và sau) khi triển khai. Chỉ định một tác nhân AI
hoặc một số điện thoại, tự viết kịch bản người gọi hoặc **tạo kịch bản
bằng AI** từ prompt của tác nhân AI (bao gồm các trường hợp biên, nếu bạn yêu cầu),
và theo dõi cuộc gọi trực tiếp.
Các kịch bản được nhóm thành **bộ kiểm thử**, trong đó cố định tỷ lệ đạt tối thiểu và có thể
chặn bản phát hành trong CI; các hồi quy so với mốc chuẩn đã được chấp nhận sẽ được
báo cáo theo từng kịch bản.
**Trong dashboard:** **Mô phỏng** (`/dashboard/simulations`), cùng với
nút **Mô phỏng** bên trong trình tạo tác nhân AI. Xem
[Mô phỏng cuộc gọi](/vi/guides/simulate-a-call).
**Trong API:** [`/v1/test-calls`](/api-reference/test-calls) và
trình chạy bộ kiểm thử — xem [Kiểm thử tác nhân AI từ đầu đến cuối](/vi/guides/test-agents).
***
## Thử nghiệm
Một **thử nghiệm** kiểm thử A/B các cấu hình tác nhân AI trên lưu lượng thực:
xác định các biến thể (prompt, engine hoặc cài đặt khác nhau), phân chia
lưu lượng giữa chúng và so sánh kết quả theo từng biến thể. Dùng tính năng này thay
vì tự xây dựng logic phân nhóm trong webhook.
**Trong dashboard:** **Thử nghiệm** (`/dashboard/experiments`) và
tab **A/B** trong trình tạo tác nhân AI. Xem
[Thử nghiệm (kiểm thử A/B)](/vi/guides/experiments-ab-testing).
***
## Vấn đề
Một **vấn đề** là lỗi được đánh dấu trên một cuộc gọi cụ thể — do
người đánh giá ghi nhận hoặc được phát hiện qua chấm điểm AI. Vấn đề có mức độ nghiêm trọng,
nguồn và trạng thái; trang Vấn đề là hàng đợi phân loại: lọc,
kiểm tra cuộc gọi có lỗi và theo dõi việc khắc phục.
**Trong dashboard:** **Vấn đề** (`/dashboard/issues`), cùng với chức năng
đánh dấu theo từng cuộc gọi trong Lịch sử cuộc gọi. Xem [Phân loại vấn đề](/vi/guides/issues).
**Trong API:** [`/v1/issue-reports`](/api-reference/issue-reports).
***
## Báo cáo
Một **báo cáo** trả lời câu hỏi bằng ngôn ngữ tự nhiên về dữ liệu cuộc gọi của bạn
("Ba lý do hàng đầu khiến người gọi yêu cầu gặp người thật vào tuần
trước là gì?") bằng một bản phân tích do AI soạn, giới hạn theo
các tác nhân AI và khoảng thời gian bạn chọn.
**Trong dashboard:** **Báo cáo** (`/dashboard/reports`). Xem
[Báo cáo](/vi/guides/reports).
***
## Khả năng quan sát
**Khả năng quan sát** là khu vực chỉ số: khối lượng cuộc gọi, kết quả và
chất lượng theo thời gian, có thể lọc theo tác nhân AI và khoảng thời gian, đồng thời hỗ trợ xuất dữ liệu
để phân tích hạ nguồn.
**Trong dashboard:** **Khả năng quan sát** (`/dashboard/observability`).
Xem [Khả năng quan sát](/vi/guides/observability).
***
## Cảnh báo
Một **quy tắc cảnh báo** theo dõi một chỉ số (tỷ lệ thành công, tỷ lệ thất bại,
điểm trung bình, khối lượng cuộc gọi, hồi quy suite) trong một khoảng thời gian và
kích hoạt khi chỉ số đó vượt ngưỡng của bạn. Thông báo được gửi đến email và
Slack, đồng thời kích hoạt sự kiện `alert.triggered` đến
[các endpoint webhook](/vi/webhooks/endpoints) của bạn.
**Trong dashboard:** **Tổ chức → Cảnh báo**. Xem
[Cảnh báo](/vi/guides/alerts).
***
## Webhook
ThunderPhone gửi **webhook HTTP POST** đến máy chủ của bạn khi các sự kiện
xảy ra trong và sau cuộc gọi. Có hai mô hình gửi:
* **Endpoint webhook** (khuyến nghị): quản lý nhiều URL tại
[`/v1/developer/webhook-endpoints`](/vi/webhooks/endpoints) với
bí mật riêng cho từng endpoint và đăng ký sự kiện riêng cho từng endpoint.
* **Webhook URL đơn cũ**: một URL cho mỗi tổ chức. Quản lý tại
[`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
hoặc trong **Tổ chức → Chung**. Được giữ lại để tương thích ngược.
Sự kiện được chia thành hai nhóm:
* **Sự kiện chặn** yêu cầu máy chủ của bạn phản hồi bằng cấu hình
định hình cuộc gọi đang diễn ra — các
[sự kiện cuộc gọi đến](/vi/webhooks/call-incoming)
(`telephony.incoming` / `web.incoming`). Bạn có tối đa 10 giây
để phản hồi; nếu hết thời gian chờ, tác nhân AI được gán tĩnh sẽ xử lý
cuộc gọi.
* **Sự kiện không chặn** là thông báo gửi rồi bỏ qua, được thử lại
với khoảng lùi theo cấp số nhân — xem
[ngữ nghĩa gửi](/vi/webhooks/overview).
Mọi yêu cầu đều có chữ ký HMAC-SHA256 trong
`X-ThunderPhone-Signature`. Xem
[Xác minh chữ ký](/vi/webhooks/overview).
***
## Công cụ hàm
Một **công cụ hàm** là endpoint HTTP mà tác nhân AI của bạn có thể gọi
giữa cuộc hội thoại. Bạn cung cấp cho ThunderPhone một schema hàm theo kiểu OpenAI
cùng URL endpoint; tác nhân AI quyết định thời điểm gọi, và
ThunderPhone thực hiện yêu cầu HTTP có chữ ký từ máy chủ của mình rồi chuyển
kết quả lại cho tác nhân AI.
Tác nhân AI cũng có **khả năng gọi tích hợp sẵn** — chuyển cuộc gọi,
gửi dữ liệu bàn phím (DTMF), kết thúc cuộc gọi, chờ máy — mà
bạn bật bằng các dòng prompt đơn giản thay vì định nghĩa công cụ.
**Trong dashboard:** phần **Kết nối API** của trình xây dựng (xem
[Kết nối](#connections)).
**Trong API:** [`/v1/integrations`](/api-reference/integrations) và
[đặc tả Công cụ hàm](/vi/tools/overview).
***
## Nhóm và vai trò
Mỗi tổ chức có danh sách thành viên với hai vai trò: **Thành viên** xây dựng
và vận hành tác nhân AI; **Quản trị viên** cũng quản lý nhóm và thanh toán.
Mời qua email — lời mời hết hạn sau 7 ngày và có thể bị thu hồi;
menu ⋯ trên hàng của thành viên dùng để thay đổi vai trò hoặc xóa một người. Đăng nhập
một lần có thể được cấu hình cho toàn tổ chức — xem [SSO](/vi/guides/sso).
**Trong dashboard:** **Tổ chức → Chung**. Xem
[Mời nhóm của bạn](/vi/guides/invite-your-team).
**Trong API:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/invites).
***
## Thanh toán
ThunderPhone là dịch vụ **trả trước**. Mỗi tổ chức có số dư USD; các cuộc gọi
sẽ trừ số dư theo đơn giá mỗi phút của tác nhân AI (cấp engine cộng phụ phí —
trình tạo hiển thị trực tiếp đơn giá tổng khi bạn thay đổi cài đặt, và
[ngôn ngữ cao cấp](/vi/guides/supported-languages) cộng thêm 2¢/phút). Khi
số dư về không, các cuộc gọi đến sẽ bị từ chối và các cuộc gọi đi sẽ trả về
`402 Payment Required`.
Nạp tiền thủ công hoặc bật **tự động nạp tiền** với ngưỡng số dư, số tiền
nạp lại và giới hạn chi tiêu hằng tháng tùy chọn — để cuộc gọi không bao giờ
bị ngắt giữa câu.
**Trong dashboard:** **Tổ chức → Cài đặt thanh toán** và
**Lịch sử thanh toán**. Xem
[Nạp tiền và bật tự động nạp tiền](/vi/guides/billing-and-topups).
**Trong API:** [`/v1/billing`](/api-reference/billing).
***
## Trợ lý đồng hành trong ứng dụng
Dashboard đi kèm **trợ lý đồng hành** tích hợp — hãy hỏi "làm thế nào để X"
và trợ lý sẽ trả lời dựa trên tài liệu này, cung cấp hướng dẫn từng cú nhấp
làm nổi bật các nút điều khiển thực tế, đồng thời có thể phát lại bất kỳ
Tour hướng dẫn nào. Đây là cách nhanh nhất để tìm một nút điều khiển được
đề cập trên trang này. Xem [Hỏi trợ lý đồng hành trong ứng dụng](/vi/guides/ask-the-copilot).
***
## Tổng hợp
Trình hướng dẫn năm bước: tác nhân AI → thanh toán → số điện thoại → mô phỏng → xem lại.
Cùng cuộc gọi đầu tiên trong bốn lệnh gọi REST.
Tạo tác nhân AI, nạp tiền, lấy số điện thoại, mô phỏng và xem lại cuộc gọi.
Ứng dụng OAuth, API tùy chỉnh, máy chủ MCP và nhà cung cấp VoIP.
Báo cáo, khả năng quan sát, thử nghiệm, sự cố và cảnh báo.
Lời mời và vai trò, khóa API, bảo mật và SSO.
Các công thức API: cuộc gọi đến, cuộc gọi đi, cấu hình động, công cụ, kiểm thử.
Thiết lập kiểm tra HMAC đúng một lần và tái sử dụng ở mọi nơi.