---
title: "Thực hiện cuộc gọi từ Slack hoặc ứng dụng chat"
description: "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`](/api-reference/outbound-calls) 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`](/vi/webhooks/events) | 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`](/api-reference/calls#whisper-to-the-agent) | 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ụ](/vi/guides/build-tool-integration) 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`](/api-reference/calls#deliver-a-tool-result) | 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`](/vi/webhooks/events) | 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ủ](/vi/guides/api-keys)).
- **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](/vi/webhooks/endpoints).
  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](https://api.slack.com/apps).

<Tip>
  Hãy dùng một ứng dụng Slack do bạn tạo cho không gian làm việc của riêng mình, và nhận tin nhắn
  qua Events API của Slack thay vì đọc lịch sử kênh. Slack
  áp dụng giới hạn đọc chặt chẽ cho các ứng dụng được phân phối đến những không gian làm việc khác bên ngoài
  Marketplace; ứng dụng bạn xây dựng cho không gian làm việc của riêng mình không bị áp dụng
  các giới hạn đó, và sự kiện đến với bạn ngay khi chúng xảy ra mà không cần đọc. Các phạm vi
  bot thường dùng: `chat:write`, `app_mentions:read`, `im:history` (tin nhắn
  trực tiếp), `channels:history` và `groups:history` (phản hồi trong chuỗi thảo luận ở
  các kênh công khai và riêng tư mà bot tham gia). Đăng ký các sự kiện bot
  `app_mention`, `message.im`, `message.channels` và `message.groups`, đồng thời
  bật tab Tin nhắn trong App Home để mọi người có thể nhắn tin trực tiếp cho bot.
</Tip>

## 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`:

```bash
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](/vi/guides/verify-webhook-signatures).
- **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](/vi/webhooks/call-complete) để 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:

```bash
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](/vi/guides/build-tool-integration) 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](/api-reference/integrations#timeout-and-wait-mode), 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ờ:

```json
{"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`](/api-reference/calls#deliver-a-tool-result):

```bash
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](/vi/tools/overview).

**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ờ:

```text
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`](/api-reference/organizations#legacy-single-url-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](/vi/guides/outbound-calling-laws).

## 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](/vi/guides/docs-mcp) 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.
