# 수신 통화 차단 (/docs/call-blocking)

## 수신 통화 차단

받고 싶지 않은 수신 통화를 **받지 않고 거절**하는 방법입니다. 어느 방법이든 통화를 받기 전에 끊으므로
**거절한 통화에는 요금이 청구되지 않고, 월 수신 한도도 차감되지 않습니다.**

| 방법 | 범위 | 설정하는 곳 | 이럴 때 |
| --- | --- | --- | --- |
| [수신 통화 차단 목록](#수신-통화-차단-목록) | 계정의 모든 번호 | 콘솔 「전화번호 › 수신 통화 차단」, API | 특정 번호(장난 전화·스팸)를 막을 때 |
| [번호 표시제한 통화 거절](#번호-표시제한-통화-거절) | 번호별 | 콘솔 번호 상세 「수신 통화 차단」 카드, API | 번호를 숨기고 건 통화를 받지 않을 때 |
| [VoiceML `<Reject>`](/docs/build/voiceml) | 웹훅으로 받는 번호 | 여러분의 웹훅 응답 | 시간대·고객 정보 등 조건으로 직접 판단할 때 |
| [SDK `on_incoming`](/docs/voice-agent#받기-전에-거절하기-on_incoming) | SDK 에이전트로 받는 번호 | 여러분의 에이전트 코드 | 에이전트에서 조건으로 직접 판단할 때 |

차단 목록과 번호 표시제한 거절은 **번호의 라우팅과 관계없이** 적용됩니다 — 웹훅·AI 에이전트·SDK 에이전트·
SIP·전환 어느 쪽으로 받는 번호든 같습니다. 이 두 설정에 걸린 통화는 웹훅을 호출하지 않고 에이전트에도 전달되지
않습니다.

AI 에이전트가 이미 받은 통화를 **같은 계정의 다른 번호로 전환**한 경우에는 그 번호의 설정이 켜져 있어도 거절하지 않습니다.
여러분이 넘긴 통화이기 때문입니다. 단 SIP REFER 나 VoiceML `<Dial>` 로 넘긴 통화는 통신망을 거쳐 다시 들어오므로
외부에서 걸려 온 통화와 같게 취급되어 거절될 수 있습니다.

**발신 쪽 「수신거부」와는 별개입니다.** 수신 통화 차단 목록에 넣은 번호로 **전화를 거는 것은 막지 않습니다.**
광고 전화·문자를 받지 않겠다는 번호는 [수신거부](/docs/api/blockedrecipients/listBlockedRecipients) 명단에서
관리하세요. 반대로 수신거부 명단은 수신 통화를 막지 않습니다.

## 수신 통화 차단 목록

등록한 번호에서 걸려 오는 통화를, 계정의 어느 번호로 걸든 받지 않고 거절합니다.

- 번호는 하이픈·`+82` 형식 모두 입력할 수 있습니다. 같은 번호로 저장됩니다.
- 이미 차단 중인 번호를 다시 등록해도 오류가 나지 않습니다(기존 항목을 돌려줍니다).
- 해제하면 바로 다음 통화부터 다시 받습니다. 해제해도 언제 차단하고 언제 풀었는지는 남습니다.
- 계정당 차단 중인 번호는 10,000개까지입니다.
- 발신자가 번호 표시제한을 걸었더라도 통신사가 번호를 전달해 주면 목록과 대조됩니다.
  번호 자체가 전달되지 않은 통화는 목록으로 막을 수 없으니 아래 번호 표시제한 통화 거절을 쓰세요.

## 번호 표시제한 통화 거절

번호마다 켜고 끕니다. 켜면 발신자가 번호 표시제한(`*23#` 등)을 걸고 건 통화를 받지 않고 거절합니다.
기본값은 꺼짐이라, 켜지 않으면 지금처럼 받습니다.

- 판정 기준은 통화 기록·웹훅의 [`callerIdRestricted` / `CallerIdRestricted`](/docs/build/voiceml) 와 같습니다.
  `true` 로 판정된 통화만 거절합니다.
- 일부 통신 경로에서는 표시제한 여부가 전달되지 않아 거절되지 않을 수 있습니다.
- 이미 받은 통화를 같은 계정의 다른 번호로 전환할 때는 적용하지 않습니다 — 전환 중인 상담이 끊기지 않습니다.

## 거절된 통화는 이렇게 남습니다

거절된 통화도 통화 기록에 남고, 번호에 [Status Callback](/docs/webhooks/status) 을 설정했다면 종료 통지가
한 번 발송됩니다(`CallStatus=rejected`, `Duration=0`). 벨이 울렸다는 `ringing` 통지는 보내지 않습니다.

| 거절한 곳 | `status` | `hangupCause` | `hangupSource` |
| --- | --- | --- | --- |
| 수신 통화 차단 목록 | `rejected` | `caller_blocked` | `callee` |
| 번호 표시제한 통화 거절 | `rejected` | `caller_id_restricted_rejected` | `callee` |
| VoiceML `<Reject>` (기본) | `rejected` | `call_rejected` | `callee` |
| VoiceML `<Reject reason="busy">` | `busy` | `user_busy` | `callee` |

차단 목록·표시제한 거절은 벨을 울리지 않고 SIP `403 Forbidden` 으로 응답합니다. 이 값은 [통화 단건 조회](/docs/api/calls/getCall)의 `sipResponseCode` 에도 남습니다.
발신자는 벨 소리 없이 통신사 안내 멘트를 듣습니다. 안내 문구는 발신자 쪽 통신사가 정합니다.

Twilio 는 `<Reject>` 로 거절한 통화를 `no-answer` 로 기록하지만, 한국AI통신은 `rejected` 로 기록합니다.
Twilio 에서 옮겨 온 통계 쿼리는 `rejected` 를 함께 집계하세요.

## API

| 작업 | API |
| --- | --- |
| 차단 목록 조회·등록·해제 | [수신 통화 차단 목록](/docs/api/blockedcallers/listBlockedCallers) |
| 번호 표시제한 통화 거절 켜기 | [번호 수정](/docs/api/numbers/updateNumber) 의 `rejectCallerIdRestricted: true` |
| 거절된 통화만 보기 | [통화 목록 조회](/docs/api/calls/listCalls) `?hangupCause=caller_blocked&hangupCause=caller_id_restricted_rejected` |