Open in
Thực hiện cuộc gọi từ Slack hoặc ứng dụng chat
Xây dựng bot Slack, Teams hoặc chat web riêng để bắt đầu cuộc gọi, theo dõi trực tiếp, điều hướng tác nhân AI và trả lời câu hỏi của tác nhân AI bằng API công khai.
Bạn có thể điều khiển một tác nhân AI từ ứng dụng chat mà nhóm của bạn đã dùng. Một tin nhắn bắt đầu một cuộc gọi. Cuộc gọi diễn ra trực tiếp trong một chuỗi thảo luận. Một phản hồi trong chuỗi sẽ điều hướng tác nhân AI. Khi tác nhân AI cần một quyết định, tác nhân AI sẽ hỏi bạn tại đó và chờ câu trả lời của bạn.
ThunderPhone không lưu trữ bot này cho bạn. Bạn (hoặc tác nhân lập trình của bạn) xây dựng một máy chủ nhỏ kết nối ứng dụng chat của bạn với API công khai. Trang này trình bày các thành phần. Chúng giống nhau với Slack, Microsoft Teams, Discord hoặc trang web chat riêng tư; ví dụ sử dụng Slack.
Cách các thành phần kết hợp với nhau
| Bạn thực hiện việc này trong chat | Bot của bạn gọi | Điều gì xảy ra |
|---|---|---|
| Gửi "Gọi Comcast và lấy ETA sự cố" | POST /v1/call với tin nhắn làm context | Tác nhân AI quay số. Bot của bạn mở một chuỗi thảo luận cho cuộc gọi |
| Theo dõi chuỗi thảo luận | Nhận webhook telephony.turn | Mỗi dòng mà tác nhân AI hoặc người bên kia nói sẽ xuất hiện trong chuỗi thảo luận |
| Trả lời trong chuỗi thảo luận giữa cuộc gọi | POST /v1/calls/{call_id}/whisper | Tác nhân AI nhận ghi chú của bạn một cách riêng tư và thực hiện theo. Người bên kia không bao giờ nghe thấy |
| Trả lời câu hỏi của tác nhân AI | Điểm cuối công cụ của bạn trả về câu trả lời, hoặc gửi câu trả lời sau bằng POST /v1/calls/{call_id}/tool-results | Tác nhân AI tiếp tục cuộc gọi với câu trả lời đó; ở chế độ chờ, người bên kia sẽ nghe nhạc chờ trong lúc đó |
| Đọc kết quả | Nhận telephony.complete | Bot của bạn đăng bản tóm tắt và kết quả |
Bot của bạn duy trì một ánh xạ: chuỗi thảo luận chat nào thuộc về call_id nào.
Trước khi bắt đầu
- Khóa API, được lưu trên máy chủ của bạn và không bao giờ trong trình duyệt hoặc ứng dụng chat. Tạo một khóa trong Tích hợp → Khóa API (xem Tạo khóa API máy chủ).
- Số điện thoại được bật gọi đi và tác nhân AI cho các cuộc gọi. Tin nhắn
trở thành
contextcho từng cuộc gọi, vì vậy một tác nhân AI tổng quát có thể xử lý mọi tác vụ. - Máy chủ có thể nhận webhook, chẳng hạn như Railway, Fly.io, Render hoặc máy chủ của riêng bạn.
- Điểm cuối webhook trỏ đến máy chủ đó và đăng ký nhận
telephony.turnvàtelephony.complete. Sự kiện lượt chỉ được gửi đến các điểm cuối có liệt kê chúng. Xem Webhook. Sự kiện lượt yêu cầu bật ghi âm cuộc gọi của tác nhân AI, cònsummarykhi kết thúc cuộc gọi yêu cầu cài đặt Tạo tóm tắt cuộc gọi của tác nhân AI; nếu không, các trường đó sẽ để trống. - Ứng dụng chat của riêng bạn. Với Slack, hãy tạo ứng dụng trong không gian làm việc của bạn tại api.slack.com/apps.
1. Bắt đầu cuộc gọi từ một tin nhắn
Khi bot của bạn nhận được một tin nhắn (tin nhắn trực tiếp hoặc một lượt @đề cập),
hãy xác nhận yêu cầu của Slack ngay lập tức (Slack sẽ thử lại bất kỳ yêu cầu nào không được
xác nhận trong vòng 3 giây) rồi xử lý phần còn lại ở chế độ nền. Kiểm tra
người gửi có được phép thực hiện cuộc gọi hay không, sau đó bắt đầu cuộc gọi với
tin nhắn làm context:
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+18005550100",
"agent_id": 12,
"context": "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
"idempotency_key": "slack-D012AB3CD-1731000000.000100"
}'Lưu call_id được trả về theo chuỗi thảo luận Slack (channel cộng với
ts của tin nhắn) và trả lời trong chuỗi thảo luận ("Đang gọi…"). Tạo
idempotency_key từ kênh và ts của tin nhắn (một ts chỉ duy nhất
trong kênh của nó), để một sự kiện Slack được thử lại không thực hiện cuộc gọi
thứ hai. Nếu yêu cầu nêu tên một người thay vì một số điện thoại, bot của bạn
sẽ tra cứu số đó trước. ThunderPhone chỉ quay số to_number bạn gửi.
2. Theo dõi cuộc gọi trong chuỗi thảo luận
Mỗi webhook telephony.turn mang theo call_id, người nói (role:
assistant cho tác nhân AI, user cho người còn lại), text và
position của lượt. Tra cứu chuỗi thảo luận theo call_id và
đăng dòng đó.
- Xác minh mọi webhook trước khi xử lý. Xem Xác minh chữ ký webhook.
- Khử trùng lặp theo
event_idcủa envelope và sắp xếp theoposition. Việc gửi được đảm bảo ít nhất một lần và các lượt có thể đến không đúng thứ tự. - Gom các dòng nếu một cuộc gọi bận rộn có thể làm ngập chuỗi thảo luận; đăng vài giây một lần sẽ dễ đọc hơn một tin nhắn cho mỗi dòng.
Khi telephony.complete đến, đăng cách cuộc gọi kết thúc (status
và end_reason), summary cùng mọi dữ liệu được trích xuất, rồi hoàn tất
chuỗi thảo luận. Xem Cuộc gọi hoàn tất để biết các trường.
3. Điều hướng cuộc gọi từ chuỗi thảo luận
Khi ai đó trả lời trong chuỗi thảo luận của một cuộc gọi đang diễn ra, hãy gửi câu trả lời dưới dạng thì thầm, trừ khi tác nhân AI đang chờ câu trả lời cho một câu hỏi (bước 4), khi đó câu trả lời chính là đáp án:
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Ask whether they can waive the late fee."}'Tác nhân AI nghe riêng và đưa nội dung đó vào lượt nói tiếp theo; người còn lại
không bao giờ nghe chính lời thì thầm. Một lời thì thầm dài từ 1 đến 1000 ký tự. Mã
409 nghĩa là cuộc gọi không còn đang diễn ra: hãy báo cho chuỗi thảo luận rằng cuộc gọi đã kết thúc.
4. Để tác nhân AI hỏi bạn
Cung cấp cho tác nhân AI một công cụ, ví dụ ask_owner với một tham số
question, gọi đến máy chủ của bạn. Tạo công cụ này dưới dạng một
kết nối API và liên kết nó với tác nhân AI.
Mọi yêu cầu công cụ đều mang thông tin cuộc gọi trong header X-ThunderPhone-Call-ID.
Có ba cách để nhận lại câu trả lời.
Giữ cuộc gọi (tối đa 10 phút). Đặt công cụ ở chế độ giữ: spec.wait_mode
"hold" và spec.timeout tối đa 600 giây (nếu không có thời gian chờ, chế độ giữ
kéo dài 20 giây), thông qua
API, hoặc yêu cầu Zeus
đặt các giá trị này (trình chỉnh sửa của ứng dụng chưa có cả hai trường). Điểm cuối của bạn đăng câu hỏi vào luồng của cuộc gọi và trả lời ngay
bằng một kết quả đang chờ:
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}Người kia nghe một câu từ tác nhân AI, rồi nhạc chờ. Trên menu
điện thoại hoặc hộp thư thoại, tác nhân AI sẽ dùng cập nhật bằng lời nói thay vào đó, và
tác nhân AI song công hoàn toàn không giữ cuộc gọi: nó nhận phản hồi đang chờ làm kết quả. Khi
phản hồi đến trong luồng, gửi nó bằng
POST /v1/calls/{call_id}/tool-results:
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'Nhạc nhỏ dần rồi tắt và tác nhân AI tiếp tục với câu trả lời của bạn. Nếu không ai
trả lời trước timeout, tác nhân AI được thông báo là chưa có câu trả lời và đề xuất
các bước tiếp theo cho người kia. Trong khi một câu hỏi đang chờ cho một cuộc gọi,
phản hồi tiếp theo trong luồng của cuộc gọi đó sẽ trả lời câu hỏi: gửi nó làm kết quả công cụ và
đừng đồng thời gửi dưới dạng thì thầm (thì thầm chỉ đến được tác nhân AI sau khi
công cụ trả về). Xem
Chờ lâu.
Chờ trong yêu cầu (tối đa 3 phút). Endpoint của bạn đăng câu hỏi,
chờ phản hồi rồi trả về phản hồi đó, chẳng hạn {"answer": "Yes, book Tuesday at 10."}.
Đặt spec.timeout của công cụ qua API, tối đa 180 giây (mặc định
là 20). Đặt deadline riêng cho endpoint của bạn ngắn hơn vài giây
(ví dụ 170 giây), để khi không ai trả lời, endpoint vẫn trả về
một nội dung mà tác nhân AI có thể xử lý, chẳng hạn
{"answer": null, "note": "No reply yet. Offer to take a message."}. Công cụ
chạm timeout sẽ đến tác nhân AI dưới dạng lỗi, và máy chủ của bạn phải
giữ yêu cầu mở trong khoảng thời gian đó. Trong lúc chờ, tác nhân AI nói với người kia
rằng đang kiểm tra, nói rằng vẫn đang xử lý sau khoảng 12 giây, rồi
cập nhật ngắn khoảng mỗi 15 giây. Chế độ giữ cũng hoạt động ở đây:
đặt spec.wait_mode thành "hold" và người kia sẽ nghe nhạc
thay vì các cập nhật.
Trả lời bằng thì thầm. Endpoint của bạn đăng câu hỏi và trả về ngay,
ví dụ {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}.
Khi phản hồi đến, gửi nó dưới dạng thì thầm (bước 3), và tác nhân AI
phản hồi ngay. Dùng cách này cho các câu trả lời có thể mất hơn
10 phút. Cuộc gọi không bị giữ: prompt của bạn nên chỉ dẫn tác nhân AI
cần làm gì trong thời gian đó, chẳng hạn trò chuyện cùng người đó hoặc đề nghị
gọi lại cho họ.
Trong mọi trường hợp, hãy nêu trong prompt của tác nhân AI khi nào dùng công cụ và cần nói gì với người kia trong lúc chờ:
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.Giới hạn cần tính đến
- Endpoint của bạn phải phản hồi trong
timeoutcủa công cụ, tối đa 180 giây. Công cụ ở chế độ giữ máy có thể giữ cuộc gọi trong tối đa 600 giây với kết quả đang chờ. - Trong khi công cụ chờ, tác nhân AI không trả lời người còn lại. Ở chế độ giữ máy, họ sẽ nghe nhạc; nếu không, họ sẽ nghe các cập nhật ngắn bằng lời nói.
- Lời thì thầm có tối đa 1000 ký tự.
- Việc gửi
telephony.turnđược đảm bảo ít nhất một lần và có thể không theo thứ tự.
Danh sách kiểm tra bảo mật
- Giữ khóa API trên máy chủ của bạn.
- Xác minh chữ ký của ThunderPhone trên webhook và yêu cầu công cụ, cùng
secret ký của Slack trên các yêu cầu của Slack. Hai chữ ký của ThunderPhone
sử dụng các secret khác nhau: lượt gửi webhook dùng secret riêng của endpoint
webhook, còn yêu cầu công cụ dùng secret webhook của tổ chức bạn
từ
GET /v1/webhook. - Quyết định ai được phép bắt đầu cuộc gọi: kiểm tra ID người dùng Slack trước khi thực hiện cuộc gọi.
- Cuộc gọi đi tuân theo các quy tắc giống mọi cuộc gọi khác. Xem Luật về cuộc gọi đi.
Xây dựng bằng tác nhân lập trình
Trỏ tác nhân lập trình của bạn đến máy chủ MCP tài liệu và trang này, rồi yêu cầu "một bot Slack cho tác nhân AI ThunderPhone của tôi tuân theo hướng dẫn này". Zeus, trợ lý trong ứng dụng ThunderPhone, có thể thiết lập phần của tác nhân AI (endpoint webhook, công cụ và các dòng prompt) và viết mã khởi đầu cho bot trong cuộc trò chuyện.