---
title: "Slack 또는 채팅 앱에서 통화 실행"
description: "공개 API를 사용하여 통화를 시작하고, 실시간으로 진행 상황을 확인하며, 에이전트를 조정하고, 에이전트의 질문에 답하는 자체 Slack, Teams 또는 웹 채팅 봇을 구축합니다."
---

팀에서 이미 사용하는 채팅 앱에서 에이전트를 제어할 수 있습니다. 메시지를 보내면
통화가 시작됩니다. 통화는 스레드에서 실시간으로 진행됩니다. 스레드에 답장하면
에이전트를 안내할 수 있습니다. 에이전트가 결정을 내려야 하면 해당 스레드에서 질문하고
답변을 기다립니다.

ThunderPhone은 이 봇을 대신 호스팅하지 않습니다. 사용자가(또는 코딩 에이전트가) 채팅 앱을
공개 API에 연결하는 작은 서버를 구축합니다. 이 페이지에서는 필요한 구성 요소를 보여 줍니다.
Slack, Microsoft Teams, Discord 또는 비공개 웹 채팅 페이지에서도 동일하며, 예시는 Slack을
사용합니다.

## 작동 방식

| 채팅에서 수행하는 작업 | 봇이 호출하는 항목 | 발생하는 작업 |
|---|---|---|
| "Comcast에 전화해서 장애 복구 예상 시간을 알아봐" 전송 | 메시지를 `context`로 포함한 [`POST /v1/call`](/api-reference/outbound-calls) | 에이전트가 전화를 겁니다. 봇이 통화용 스레드를 엽니다 |
| 스레드 확인 | [`telephony.turn`](/ko/webhooks/events) 웹훅 수신 | 에이전트 또는 상대방이 말하는 각 문장이 스레드에 표시됩니다 |
| 통화 중 스레드에 답장 | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | 에이전트가 메모를 비공개로 받고 이에 따라 행동합니다. 상대방은 절대 듣지 못합니다 |
| 에이전트의 질문에 답변 | [도구 엔드포인트](/ko/guides/build-tool-integration)가 답변을 반환하거나 [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result)를 통해 나중에 전달 | 에이전트가 해당 내용을 바탕으로 통화를 계속합니다. 보류 모드에서는 그동안 상대방에게 대기 음악이 들립니다 |
| 결과 확인 | [`telephony.complete`](/ko/webhooks/events) 웹훅 수신 | 봇이 요약과 결과를 게시합니다 |

봇은 하나의 매핑을 유지합니다. 어떤 채팅 스레드가 어떤 `call_id`에 속하는지 추적합니다.

## 시작하기 전에

- **API 키**: 서버에 보관하고 브라우저나 채팅에는 절대 저장하지 마세요.
  **통합 → API 키**에서 생성합니다(
  [서버 API 키 만들기](/ko/guides/api-keys) 참조).
- 통화에 사용할 **발신이 활성화된 번호와 에이전트**. 메시지는 통화별 `context`가
  되므로, 하나의 범용 에이전트가 모든 작업을 처리합니다.
- Railway, Fly.io, Render 또는 자체 호스트처럼 웹훅을 수신할 수 있는 **서버**.
- 해당 서버를 가리키고 `telephony.turn` 및 `telephony.complete`를 구독하는
  **웹훅 엔드포인트**. 턴 이벤트는 이를 목록에 포함한 엔드포인트에만 전송됩니다.
  [웹훅](/ko/webhooks/endpoints)을 참조하세요.
  턴 이벤트에는 에이전트의 통화 녹음이 켜져 있어야 하며, 통화 종료 `summary`에는
  에이전트의 **통화 요약 생성** 설정이 필요합니다. 설정하지 않으면 해당 필드는 비어 있습니다.
- **자체 채팅 앱.** Slack의 경우 워크스페이스에서
  [api.slack.com/apps](https://api.slack.com/apps)로 이동해 앱을 만드세요.

<Tip>
  자체 워크스페이스용으로 만든 Slack 앱을 사용하고 채널 기록을 읽는 대신 Slack의
  Events API를 통해 메시지를 수신하세요. Slack은 Marketplace 외부의 다른
  워크스페이스에 배포되는 앱에 엄격한 읽기 제한을 적용합니다. 자체 워크스페이스용으로
  만든 앱에는 이러한 제한이 적용되지 않으며, 읽기 요청 없이 이벤트가 발생하는 즉시
  수신됩니다. 일반적인 봇 범위는 `chat:write`, `app_mentions:read`, `im:history`(다이렉트
  메시지), `channels:history`, `groups:history`(봇이 참여한 공개 및 비공개 채널의 스레드
  답장)입니다. 봇 이벤트 `app_mention`, `message.im`, `message.channels`, `message.groups`를
  구독하고, 사용자가 봇에 DM을 보낼 수 있도록 App Home 아래의 Messages 탭을 켜세요.
</Tip>

## 1. 메시지에서 통화 시작

봇이 메시지(다이렉트 메시지 또는 @멘션)를 받으면 Slack의 요청을 즉시 확인합니다(Slack은 3초 이내에 확인되지 않은 요청을 재시도합니다). 나머지 작업은 백그라운드에서 처리합니다. 발신자가 통화를 시작할 권한이 있는지 확인한 다음, 메시지를 `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"
  }'
```

반환된 `call_id`를 Slack 스레드(`channel`과 메시지 `ts`)에 저장하고 스레드에 응답합니다("전화 연결 중…"). `idempotency_key`는 채널과 메시지 `ts`로 구성합니다(`ts`는 해당 채널 내에서만 고유합니다). 이렇게 하면 재시도된 Slack 이벤트가 두 번째 통화를 시작하지 않습니다. 요청에서 번호 대신 사람 이름을 지정하면 봇이 먼저 번호를 조회합니다. ThunderPhone은 전송한 `to_number`로만 전화를 겁니다.

## 2. 스레드에서 통화 추적

각 `telephony.turn` 웹훅에는 `call_id`, 발화자(`role`: 에이전트는 `assistant`, 상대방은 `user`), `text`, 그리고 발화의 `position`이 포함됩니다. `call_id`로 스레드를 조회하고 해당 줄을 게시합니다.

- 작업하기 전에 **모든 웹훅을 검증합니다.** [웹훅 서명 검증](/ko/guides/verify-webhook-signatures)을 참조합니다.
- **엔벌로프의 `event_id`를 기준으로 중복을 제거하고 `position` 순으로 정렬합니다.** 최소 한 번 이상 전달되며, 발화는 순서가 바뀐 상태로 도착할 수 있습니다.
- 통화가 바빠서 스레드가 과도하게 늘어날 경우 **줄을 묶어서 게시합니다.** 줄마다 하나의 메시지를 게시하는 것보다 몇 초마다 게시하는 편이 읽기 쉽습니다.

`telephony.complete`가 도착하면 통화 종료 방식(`status` 및 `end_reason`), `summary`, 추출된 데이터를 게시하고 스레드를 마무리합니다. 필드는 [통화 완료](/ko/webhooks/call-complete)를 참조합니다.

## 3. 스레드에서 통화 유도

누군가 진행 중인 통화의 스레드에 답글을 달면, 에이전트가 질문에 대한 답변을 기다리는 경우(4단계)가 아닌 한 답글을 속삭임으로 전송합니다. 에이전트가 답변을 기다리는 경우에는 해당 답글이 답변입니다.

```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."}'
```

에이전트는 이를 비공개로 듣고 다음 발화에 반영합니다. 상대방은 속삭임 자체를 듣지 못합니다. 속삭임은 1~1000자입니다. `409`는 통화가 더 이상 진행 중이 아님을 의미합니다. 스레드에 통화가 종료되었음을 알립니다.

## 4. 에이전트가 질문하도록 설정합니다

에이전트에 서버를 호출하는 `question` 매개변수 하나가 있는 `ask_owner` 같은 도구를 제공합니다. 이를
[API 연결](/ko/guides/build-tool-integration)로 생성하고 에이전트에 연결합니다.
모든 도구 요청은 `X-ThunderPhone-Call-ID` 헤더에 통화 정보를 담습니다.

답변을 다시 받는 방법은 세 가지입니다.

**통화를 보류합니다(최대 10분).** 도구를 보류 모드로 설정합니다: `spec.wait_mode`
`"hold"` 및 `spec.timeout`을 최대 600초로 설정합니다(시간 제한이 없으면 보류는
20초간 지속됩니다). [API](/api-reference/integrations#timeout-and-wait-mode)를 통해 설정하거나 Zeus에게
설정을 요청합니다(앱 편집기에는 아직 두 필드가 없습니다). 엔드포인트는 질문을 통화의 스레드에 게시하고 즉시
대기 중 결과로 응답합니다:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

상대방은 에이전트의 한 문장을 들은 뒤 보류 음악을 듣습니다. 전화 메뉴나 음성사서함에서는
에이전트가 대신 음성 업데이트를 사용하며, 전이중 에이전트는 보류하지 않고 대기 중 응답을
결과로 받습니다. 스레드에 답변이 도착하면
[`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."}}'
```

음악이 서서히 사라지고 에이전트는 답변을 바탕으로 대화를 계속합니다. `timeout` 전에 아무도
답변하지 않으면 에이전트는 답변이 오지 않았다고 안내하고 상대방에게 다음 단계를 제안합니다.
통화에 대한 질문이 대기 중인 동안 스레드의 다음 답변은 해당 질문에 대한 답변입니다. 이를
도구 결과로 전달하고 속삭임으로도 보내지 마십시오(속삭임은 도구가 반환된 후에만 에이전트에
도달합니다).
[긴 대기](/ko/tools/overview)를 참조하십시오.

**요청에서 대기합니다(최대 3분).** 엔드포인트가 질문을 게시하고 답변을 기다린 뒤 반환합니다.
예: `{"answer": "Yes, book Tuesday at 10."}`. API를 통해 도구의 `spec.timeout`을 최대
180초로 설정합니다(기본값은 20초입니다). 아무도 답변하지 않을 때에도 에이전트가 처리할 수
있는 내용을 반환하도록 엔드포인트 자체의 마감 시간은 몇 초 더 짧게 설정합니다(예: 170초).
예: `{"answer": null, "note": "No reply yet. Offer to take a message."}`. `timeout`에
도달한 도구는 오류로 에이전트에 전달되며, 호스트는 그만큼 오랫동안 요청을 열어 두어야 합니다.
대기하는 동안 에이전트는 상대방에게 확인 중이라고 알리고, 약 12초 후에도 계속 처리 중이라고
말한 다음 약 15초마다 짧은 업데이트를 제공합니다. 여기에서도 보류 모드를 사용할 수 있습니다.
`spec.wait_mode`를 `"hold"`로 설정하면 상대방은 업데이트 대신 음악을 듣습니다.

**속삭임으로 답변합니다.** 엔드포인트가 질문을 게시하고 즉시 반환합니다. 예:
`{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
답변이 도착하면 이를 속삭임으로 전송하고(3단계), 에이전트가 즉시 응답하도록 합니다. 10분보다
오래 걸릴 수 있는 답변에는 이 방식을 사용합니다. 통화는 보류되지 않으므로, 그동안 무엇을 해야
하는지 프롬프트에서 에이전트에게 알려야 합니다. 예를 들어 상대방의 말동무가 되어 주거나
나중에 다시 전화하겠다고 제안하도록 합니다.

모든 경우에 에이전트 프롬프트에서 도구를 언제 사용해야 하는지와 기다리는 동안 상대방에게
무엇을 말해야 하는지 지정합니다.

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

## 계획 시 고려할 제한 사항

- 엔드포인트는 도구의 `timeout` 내에, 최대 **180초** 이내에 응답해야 합니다. 대기 모드의 도구는 결과가 대기 중인 상태로 통화를 최대 **600초** 동안 보류할 수 있습니다.
- 도구가 대기하는 동안 에이전트는 상대방에게 응답하지 않습니다. 대기 모드에서는 음악이 들리고, 그 외에는 짧은 음성 안내가 제공됩니다.
- 속삭임은 최대 **1000자**입니다.
- `telephony.turn` 전송은 최소 한 번 이루어지며 순서가 뒤바뀔 수 있습니다.

## 보안 체크리스트

- API 키는 서버에 보관합니다.
- 웹훅 및 도구 요청에서는 ThunderPhone의 서명을 확인하고, Slack 요청에서는 Slack의 서명 시크릿을 확인합니다. 두 ThunderPhone 서명은 서로 다른 시크릿을 사용합니다. 웹훅 전송에는 웹훅 엔드포인트 자체의 시크릿을 사용하고, 도구 요청에는 [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)의 조직 웹훅 시크릿을 사용합니다.
- 통화를 시작할 수 있는 사용자를 결정합니다. 통화를 연결하기 전에 Slack 사용자 ID를 확인합니다.
- 발신 통화에는 다른 모든 발신 통화와 동일한 규칙이 적용됩니다. [발신 통화 관련 법률](/ko/guides/outbound-calling-laws)을 참조합니다.

## 코딩 에이전트로 구축하기

코딩 에이전트에 [문서 MCP 서버](/ko/guides/docs-mcp)와 이 페이지를 제공하고,
"이 가이드를 따르는 내 ThunderPhone 에이전트용 Slack 봇"을 만들어 달라고 요청합니다. ThunderPhone 앱의 어시스턴트인 Zeus는 에이전트 측 설정(웹훅 엔드포인트, 도구, 프롬프트 줄)을 구성하고 채팅에서 봇용 시작 코드를 작성할 수 있습니다.
