Getting Started

Khái niệm cốt lõi

Bản đồ về mọi thành phần trên nền tảng — chức năng của từng đối tượng, vị trí của chúng trong bảng điều khiển và API nào tương tác với chúng.

ThunderPhone là nền tảng toàn diện để 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 có một phần ngắn, cùng giao diện dashboard và API hỗ trợ nó. Đọc lướt một lần, rồi quay lại bất cứ khi nào cần làm rõ một thuật ngữ.

Thanh bên dashboard phản ánh cấu trúc này:

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 về 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 này giúp API REST trở nên đơn giản: bạn không bao giờ đặt id tổ chức trong đường dẫn URL, vì khóa của bạn đã xác định tổ chức đó.

Trong dashboard: bộ chuyển đổi tổ chức (chân thanh bên) và phần cài đặt Tổ chức — các thẻ Tài khoản của tôi, Chung, Khóa, Cảnh báo, Cài đặt thanh toán và Lịch sử thanh toán. Xem tham chiếu cài đặt tổ chức.

Trong API: /v1/orgs, /v1/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, bấm phím và ngắt cuộc gọi, vốn 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 thay đổi ngôn ngữ. Xem Ngôn ngữ được hỗ trợ.
• Các khả năng được đính kèm: ứng dụng đã kết nối, kết nối API, cơ sở kiến thức, máy chủ MCP và công cụ hàm nội tuyến.
• Các tùy chọn hành vi: thứ tự nói, chế độ xác nhận, nhạc nền, thời gian chờ tối đa.

Các chỉnh sửa trong trình tạo sẽ tự động lưu vào bản nháp; không có gì được phát hành cho đến khi bạn nhấp Triển khai. Mỗi lần triển khai đều được chụp lại trong thẻ Lịch sử của trình tạo, để bạn có thể xem xét và khôi phục bất kỳ phiên bản trước đó nào.

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

Trong API: /v1/agents — CRUD, nhân bản, chuyển cuộc gọi, lịch sử phiên bản và trình hỗ trợ prompt.

Giọng nói#

Thư viện giọng nói chứa các giọng nói mà tác nhân AI có thể sử dụng, các mẫu có thể phát, ngôn ngữ tương thích, nhóm giới tính và giọng vùng miền, cùng mọi phụ phí cho giọng nói/ngôn ngữ cao cấp. Công cụ nghe thử có trả phí có thể tổng hợp câu của riêng bạn dài từ 1–500 ký tự trước khi bạn chọn.

Các tổ chức đủ điều kiện cũng có thể tạo giọng nói tùy chỉnh từ một mẫu WAV hoặc MP3 ngắn. Giọng nói tùy chỉnh có hạn mức và trạng thái tạo bất đồng bộ; khi sẵn sàng, chúng xuất hiện trong cùng bộ chọn tác nhân AI như các giọng nói trong thư viện.

Trong bảng điều khiển: Giọng nói (/dashboard/voices). Xem Thư viện giọng nói và giọng nói tùy chỉnh.

Trong API: /v1/voices, mẫu giọng nói, và giọng nói tùy chỉnh.

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 cho 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ực được cấp từ nhóm số của ThunderPhone, hoạt động trong vài giây. Chỉ dành cho cuộc gọi đến, chúng trả lời bằng một tuyên bố từ chối ngắn bằng giọng nói, và bảng điều khiển giới hạn một tổ chức tối đa 10 số. Phù hợp cho lần kiểm thử đầu tiên; không dành cho môi trường production.
• Số VoIP — được mang từ nhà cung cấp của riêng bạn thông qua một kết nối VoIP. 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 hỗ trợ — hiện tại bạn có thể kết nối chúng qua cấu hình SIP thủ công, chấp nhận 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 bảng điều khiển: Số điện thoại (/dashboard/phone-numbers). Xem Lấy số điện thoại.

Trong API: /v1/phone-numbers, /v1/voip-connections, /v1/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 widget đều trở thành một nhật ký cuộc gọi. Một cuộc gọi chứa toàn bộ bản chép lời có gắ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 bằng AI và báo cáo vấn đề.

Khi một cuộc gọi đang trực tiếp, bạn có thể mở cuộc gọi và nghe — bạn tham gia trong im lặng và không ai trong cuộc gọi nghe thấy bạn. Sau khi nghe, 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, và tác nhân AI sẽ thực hiện chỉ dẫn ngay lúc đó.

Trong bảng điều khiển: Lịch sử cuộc gọi (/dashboard/call-history) cho kho lưu trữ và chi tiết từng cuộc gọi; Trực tiếp 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.

Trong API: /v1/calls — danh sách, bản chép lời, lịch sử, âm thanh, chấm điểm, xuất dữ liệu; /v1/issue-reports.

Cổng thông tin khách hàng#

Một cổng thông tin khách hàng là chế độ xem lịch sử cuộc gọi có thương hiệu, chỉ đọc dành cho khách hàng bên ngoài. Quản trị viên tổ chức chọn các tác nhân AI có cuộc gọi hiển thị, thêm email người xem được phê duyệt, tải lên logo và màu nhấn, đồng thời tùy chọn xác minh miền tùy chỉnh. Người xem cổng thông tin có thể kiểm tra chi tiết cuộc gọi, bản chép lời và các bản ghi âm có sẵn mà không nhận quyền truy cập bảng điều khiển.

Trong bảng điều khiển: Cổng thông tin khách hàng (/dashboard/client-portals). Xem Cổng thông tin khách hàng.

Trong API: /v1/client-portals dành cho giao diện quản lý của quản trị viên.

Tiện ích web#

Tiện ích web cho phép khách truy cập trang web của bạn trò chuyện bằng mic 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 khóa có thể công khai (pk_live_...) được khóa theo origin với các miền được phép của bạn, nên an toàn khi dùng trong mã phía máy khách.

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 (máy chủ 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 mỗi cuộc gọi). Phiên tiện ích đi qua cùng hạ tầng cuộc gọi như các cuộc gọi điện thoại.

Trong bảng điều khiển: Tiện ích web (/dashboard/web-widgets) — tạo tiện ích, đặt chế độ và tác nhân AI, quản lý các miền được phép, và sao chép đoạn mã nhúng. Xem Tạo tiện ích web.

Trong API: /v1/publishable-key, /v1/mic-session, và tài liệu SDK Tiện ích.

Cơ sở kiến thức#

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 trong khi gọi để làm cơ sở cho câu trả lời — tải tệp lên, dán văn bản hoặc nhập trang web bằng URL, sau đó gắn cơ sở kiến thức vào một tác nhân AI trong trình tạo. Tác nhân AI truy vấn cơ sở này 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 bảng điều khiển: 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 để gắn cơ sở kiến thức vào một tác nhân AI. Xem Cung cấp cơ sở kiến thức cho tác nhân AI.

Kết nối#

Kết nối là cách các 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 (gửi tin nhắn Slack, upsert mộ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.
• 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 lệnh cURL và trình hướng dẫn AI sẽ soạn bản nháp định nghĩa công cụ, hoặc tự tạo thủ công; nút Yêu cầu kiểm thử sẽ thực hiện cuộc gọi sandbox trước khi bạn triển khai. Xem Kết nối API — giao diện bảng điều khiển của /v1/integrations.
• MCP (/dashboard/mcp-connections) — thêm máy chủ Model Context Protocol bằng URL và cho phép 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.
• VoIP (/dashboard/voip-connections) — thông tin xác thực nhà cung cấp để mang số điện thoại của riêng bạn. Xem Kết nối nhà cung cấp VoIP.

ThunderPhone cũng cung cấp endpoint MCP riêng để một ứng dụng khách MCP bên ngoài có thể liệt kê tác nhân AI, kiểm tra cuộc gọi và bản chép lời, cũng như thực hiện cuộc gọi. Xem Sử dụng ThunderPhone làm máy chủ MCP.

Trong API: /v1/integrations, /v1/mcp-servers, và /v1/voip-connections; xem thêm Xây dựng tích hợp công cụ.

Chiến dịch#

Chiến dịch thực hiện các cuộc gọi đi ở 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 đặt khung giờ gọi (ngày và giờ, có nhận biết múi giờ), mức đồng thời và chính sách thử lại (số lần thử tối đa và kết quả nào — không trả lời, 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 bảng điều khiển: Chiến dịch (/dashboard/campaigns). Xem Chạy chiến dịch gọi đi.

Đối với cuộc gọi lập trình một lần: API cuộc gọi đi.

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 tổ chức và cho phép bạn mở bất kỳ cuộc gọi nào để nghe và thì thầm theo thời gian thực. Đây là bề mặt 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 bảng điều khiển: Trực tiếp (/dashboard/live). Xem Theo dõi và giám sát cuộc gọi trực tiếp.

Mô phỏng#

Một mô phỏng là tác nhân AI đóng vai người gọi và thực hiện cuộc trò chuyện thực với tác nhân của bạn — cùng tuyến điện thoại, 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 phát hành. Chỉ định tác nhân hoặc 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 (bao gồm các trường hợp biên nếu bạn yêu cầu), rồi 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ử, thiết lập 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 đường cơ sở đã chấp nhận được báo cáo theo từng kịch bản.

Trong bảng điều khiển: Mô phỏng (/dashboard/simulations), cùng với nút Mô phỏng trong trình tạo tác nhân. Xem Mô phỏng cuộc gọi.

Trong API: /v1/test-calls và trình chạy bộ kiểm thử — xem Kiểm thử tác nhân đầu cuối.

Tập xác thực#

Một tập xác thực biến các khoảnh khắc từ cuộc gọi thực thành các lần kiểm tra hồi quy một lượt có thể lặp lại. Mỗi ví dụ cố định ngữ cảnh cuộc trò chuyện, âm thanh người gọi liên quan, phản hồi gốc và hành vi mong đợi. Các lần phát lại chạy trên bản nháp tác nhân hiện tại mà không thực hiện thêm cuộc gọi nào, và hộp thoại triển khai có thể hiển thị liệu lần chạy mới nhất vẫn khớp với bản nháp đó hay không.

Trong bảng điều khiển: Tập xác thực (/dashboard/validation) dành cho tập dữ liệu của tổ chức và tab Xác thực trong trình tạo tác nhân dành cho các lần chạy. Xem Tập xác thực.

Trong API: /v1/validation-sets và các endpoint phát lại tác nhân/ví dụ trên cùng trang tham chiếu.

Thử nghiệm#

Một thử nghiệm kiểm thử A/B các cấu hình tác nhân trên lưu lượng thực: xác định các biến thể (prompt, engine hoặc chế độ 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ể. Sử dụng tính năng này thay vì tự xây dựng logic phân nhóm trong webhook.

Trong bảng điều khiển: Thử nghiệm (/dashboard/experiments) và tab A/B trong trình tạo tác nhân. Xem Thử nghiệm (kiểm thử A/B).

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á báo cáo hoặc được phát hiện bằng chấm điểm AI. Vấn đề bao gồm 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 gây ra lỗi và theo dõi việc khắc phục.

Trong bảng điều khiển: Vấn đề (/dashboard/issues), cùng với tính 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 đề.

Trong API: /v1/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 phổ biến nhất 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 viết, trong phạm vi các tác nhân và khoảng thời gian bạn chọn.

Trong bảng điều khiển: Báo cáo (/dashboard/reports). Xem Báo cáo.

Khả năng quan sát#

Khả năng quan sát là bề mặt chỉ số: số 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 và khoảng thời gian, đồng thời hỗ trợ xuất dữ liệu để phân tích phía sau.

Trong bảng điều khiển: Khả năng quan sát (/dashboard/observability). Xem Khả năng quan sát.

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, số lượng cuộc gọi, hồi quy bộ kiểm thử) trong một khoảng thời gian và kích hoạt khi chỉ số vượt qua ngưỡng của bạn. Thông báo được gửi qua email và Slack, đồng thời kích hoạt sự kiện alert.triggered đến các endpoint webhook của bạn.

Trong bảng điều khiển: Tổ chức → Cảnh báo. Xem Cảnh báo.

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 phân phối:

• Điểm cuối webhook (khuyến nghị): quản lý nhiều URL tại /v1/developer/webhook-endpoints với secret riêng cho từng điểm cuối và đăng ký sự kiện riêng cho từng điểm cuối.
• Webhook URL đơn cũ: một URL cho mỗi tổ chức. Quản lý tại /v1/webhook hoặc trong Tổ chức → Chung. Được giữ lại để tương thích ngược.

Các sự kiện được chia thành hai loại:

• 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 (telephony.incoming / web.incoming). Bạn có tối đa 10 giây để phản hồi; khi 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 đi không cần chờ phản hồi, được thử lại với thời gian chờ tăng theo cấp số nhân — xem ngữ nghĩa phân phối.

Mỗi yêu cầu đều mang chữ ký HMAC-SHA256 trong X-ThunderPhone-Signature. Xem Xác minh chữ ký.

Công cụ hàm#

Một công cụ hàm là điểm cuối 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 điểm cuối; 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 trả kết quả lại cho tác nhân AI.

Tác nhân AI cũng có khả năng cuộc gọi tích hợp sẵn — chuyển cuộc gọi, gửi dữ liệu nhập bàn phím (DTMF), kết thúc cuộc gọi, chờ giữ 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 tạo (xem Kết nối).

Trong API: /v1/integrations và đặc tả Công cụ hàm.

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 thành viên 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.

Trong dashboard: Tổ chức → Chung. Xem Mời nhóm của bạn.

Trong API: /v1/members, /v1/invites.

Thanh toán#

ThunderPhone là dịch vụ trả trước. Mỗi tổ chức có số dư USD; cuộc gọi trừ số dư theo mức giá mỗi phút của tác nhân AI (hạng engine cộng phụ phí — trình tạo hiển thị trực tiếp mức giá trọn gói khi bạn thay đổi cài đặt, và các ngôn ngữ bổ sung được chọn thêm 3¢/phút). Khi số dư bằng không, cuộc gọi đến bị từ chối và cuộc gọi đi 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 Thêm tiền và bật tự động nạp tiền, cùng tài liệu tham khảo giá đầy đủ.

Trong API: /v1/billing.

Copilot trong ứng dụng#

Dashboard đi kèm copilot tích hợp sẵn — hãy hỏi "làm thế nào để tôi X" và nó sẽ trả lời dựa trên các tài liệu này, cung cấp hướng dẫn từng bước 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 trang này đề cập. Xem Hỏi copilot trong ứng dụng.

Tổng hợp#