# 연결음 (/docs/ringback)

## 연결음

연결음은 전화를 받기 전까지 발신자가 듣는 소리입니다.
번호마다 음원을 정하면 통신사의 기본 연결음 대신 그 음원이 들립니다.
받기 전에는 통화 요금이 청구되지 않습니다.

설정은 세 가지이고 서로 독립입니다.

| 설정 | 동작 | 비워 두면 |
| --- | --- | --- |
| 시그니처 | 맨 앞에 한 번 재생합니다. | 시그니처 없이 연결음부터 나옵니다. |
| 연결음 | 전화를 받을 때까지 반복합니다. | 기본 연결음이 나옵니다. |
| 받는 시점 | 정한 시간만큼 들려준 뒤 전화를 받습니다. | 준비되는 대로 받습니다. |

세 설정을 모두 비워 두면 통신사의 기본 연결음이 나옵니다.

## 설정할 수 있는 번호

070 번호, 대표번호, 080 수신자부담에서 설정할 수 있습니다.

- 휴대폰 회선으로 받는 번호에는 설정할 수 없습니다.
- 미디어 우회를 쓰는 계정의 번호에는 설정할 수 없습니다.

연결음은 착신 방식이 Webhook, 에이전트, 콜 플로우인 번호에서 나옵니다.
SIP, 소프트폰 착신에서는 설정이 저장되지만 나오지 않습니다.

### 전환하는 번호

다른 번호로 전환하는 번호에 건 전화에는 그 번호에 설정한 연결음이 나옵니다.
그 번호에 설정이 없으면 전환받는 번호의 연결음이 나옵니다.
전환받는 번호의 착신 방식이 Webhook, 에이전트, 콜 플로우일 때 나옵니다.

## 음원 올리기

콘솔 **전화번호 › 음원 관리**에서 음원을 올립니다.
올린 음원은 계정의 모든 번호에서 고를 수 있습니다.

- mp3, wav, m4a 파일을 올릴 수 있습니다.
- 파일 크기는 10MB 까지입니다.
- 음원은 전화 음질에 맞게 바뀌어 저장됩니다.
- 3분을 넘는 음원은 앞의 3분만 저장됩니다.
- 음원은 계정당 50개까지 보관할 수 있습니다.

API 로는 세 단계로 올립니다.

1. [업로드 주소 발급](/docs/api/ringbackaudios/createRingbackAudioUpload)으로 `uploadUrl`, `uploadHeaders`, `uploadUri` 를 받습니다.
2. `uploadUrl` 에 `uploadHeaders` 를 실어 파일을 `PUT` 합니다.
3. [음원 등록](/docs/api/ringbackaudios/createRingbackAudio)에 `name` 과 `uploadUri` 를 보냅니다.

업로드 주소는 10분 동안 쓸 수 있습니다.

## 번호에 설정하기

콘솔에서는 번호 상세의 **연결음** 카드에서 설정합니다.
API 로는 [번호 수정](/docs/api/numbers/updateNumber)의 `ringback` 에 넣습니다.

```json
{
  "ringback": {
    "signatureAudioId": "cm3f1k2ab0001xy9z8w7v6u5t",
    "audioId": "cm3f1k9cd0002xy9z1a2b3c4d",
    "minSeconds": 5
  }
}
```

| 필드 | 값 |
| --- | --- |
| `signatureAudioId` | 시그니처로 쓸 음원의 id. `null` 이면 지웁니다. |
| `audioId` | 연결음으로 쓸 음원의 id. `null` 이면 기본 연결음으로 돌아갑니다. |
| `minSeconds` | 받기 전에 들려줄 시간(초). 1 에서 30 까지. `null` 이나 `0` 이면 준비되는 대로 받습니다. |

보내지 않은 필드는 그대로 둡니다.
시그니처로는 10초 이하의 음원만 고를 수 있습니다.

## 받는 시점

`minSeconds` 는 받기 전에 들려줄 최소 시간입니다.
에이전트 준비가 더 오래 걸리면 준비될 때 받습니다.

시그니처만 정하고 연결음을 비워 두면, 시그니처 뒤에 기본 연결음과 같은 소리가 이어집니다.

## 음원 삭제

음원을 쓰는 번호가 있으면 삭제할 수 없습니다.
이때 응답의 `numbers` 에 그 음원을 쓰는 번호가 실립니다.
번호의 연결음 설정을 바꾼 뒤 삭제합니다.

## API

| 작업 | API |
| --- | --- |
| 업로드 주소 발급 | [업로드 주소 발급](/docs/api/ringbackaudios/createRingbackAudioUpload) |
| 음원 등록 | [음원 등록](/docs/api/ringbackaudios/createRingbackAudio) |
| 음원 목록 조회 | [음원 목록 조회](/docs/api/ringbackaudios/listRingbackAudios) |
| 음원 삭제 | [음원 삭제](/docs/api/ringbackaudios/deleteRingbackAudio) |
| 번호에 설정 | [번호 수정](/docs/api/numbers/updateNumber) 의 `ringback` |
