ThunderPhone v3 đã chính thức ra mắt.Tự đăng ký và sử dụng, chỉ từ 2¢/phút.Xem thông báo ra mắt

Developer cookbook

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 chatBot 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 contextTá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ậnNhận webhook telephony.turnMỗ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ọiPOST /v1/calls/{call_id}/whisperTá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-resultsTá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.completeBot 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 context cho 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.turn và 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òn summary khi 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_id của envelope và sắp xếp theo position. 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 timeout củ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.