> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.claw-ops.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.claw-ops.com/_mcp/server.

# 에이전트 사람 전환 설정 교체

PUT https://api.claw-ops.com/v1/accounts/{accountId}/agents/{agentId}/transfer
Content-Type: application/json

전환 설정 전체를 교체합니다. 보내지 않은 항목은 기본값으로 돌아가므로 조회 응답을 고쳐서 보내세요.
통화가 나갈 번호가 바뀌는 설정입니다. 변경은 다음 통화부터 적용됩니다.
발신번호 범위를 지정한 API 키로는 호출할 수 없습니다.

Reference: https://docs.claw-ops.com/api-reference/claw-ops-api/agents/put-agent-transfer

## Authentication

- `Authorization` header (bearer token, required) — API Key를 Bearer 토큰으로 전달

## Request

### Path parameters

- `accountId` (string, required) — 계정 ID
- `agentId` (string, required) — 에이전트 ID

### Body (application/json)

This endpoint expects an AgentTransferInput.

- `enabled` (boolean, required) — 사람 전환 사용 여부. 끄면 번호 형식과 안내 문구 내용은 검사하지 않습니다.
- `targets` (list of AgentTransferInputTargetsItems, required)
- `callerId` (enum, optional) — 담당자 단말에 표시할 번호. 생략하면 `account` 입니다.
  - Allowed values: `account`, `original`
- `whisper` (AgentTransferInputWhisper, optional)
- `timeout` (integer, optional) — 담당자 응답 대기 시간(초). 생략하면 30입니다.
- `holdMedia` (enum, optional) — 대기 중 발신자에게 들리는 소리. 생략하면 `moh` 입니다.
  - Allowed values: `moh`, `ringback`, `silence`
- `onFailure` (AgentTransferInputOnFailure, optional)
- `activeFrom` (datetime, optional, nullable) — 전환 허용 시작 시각. 오프셋을 포함해 `2026-11-04T09:00:00+09:00` 형식으로 보내고 `activeUntil` 과 함께 지정합니다.
- `activeUntil` (datetime, optional, nullable)

## Response

### 200

저장된 전환 설정

- `enabled` (boolean, required) — 사람 전환 사용 여부
- `targets` (list of AgentTransferTargetsItems, required)
- `callerId` (enum, required) — 담당자 단말에 표시할 번호. `account` 는 계정 번호, `original` 은 걸려 온 전화의 발신자 번호입니다.
  - Allowed values: `account`, `original`
- `whisper` (AgentTransferWhisper, required) — 담당자가 받은 직후 담당자에게만 들려주는 안내
- `timeout` (integer, required) — 담당자 응답 대기 시간(초)
- `holdMedia` (enum, required) — 대기 중 발신자에게 들리는 소리
  - Allowed values: `moh`, `ringback`, `silence`
- `onFailure` (AgentTransferOnFailure, required) — 연결되지 않았을 때 발신자에게 들려주는 안내
- `activeFrom` (datetime, required, nullable) — 전환 허용 시작 시각. `activeUntil` 과 함께 지정합니다.
- `activeUntil` (datetime, required, nullable) — 전환 허용 종료 시각

## Errors

### 400 Bad Request Error

입력 오류 (VALIDATION)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.
- `processedAt` (datetime, optional) — 문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.
- `blockers` (list of CertificateBlocker, optional) — `certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.

### 401 Unauthorized Error

인증 실패

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.
- `processedAt` (datetime, optional) — 문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.
- `blockers` (list of CertificateBlocker, optional) — `certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.

### 403 Forbidden Error

접근 권한 없음 또는 발신번호 범위를 지정한 API 키 (api_key_agent_transfer_restricted)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.
- `processedAt` (datetime, optional) — 문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.
- `blockers` (list of CertificateBlocker, optional) — `certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.

### 404 Not Found Error

에이전트를 찾을 수 없음 (AGENT_NOT_FOUND)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.
- `processedAt` (datetime, optional) — 문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.
- `blockers` (list of CertificateBlocker, optional) — `certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.

### 409 Conflict Error

저장된 설정을 읽을 수 없음 (AGENT_SPEC_INVALID)

- `error` (string, optional) — 사람이 읽을 수 있는 에러 메시지
- `code` (string, optional) — 기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서 바뀔 수 있지만 코드는 계약입니다. 같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는 - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서 해제해야 발신됩니다. - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다. 전화번호 정규화 관련: - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님) - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)
- `ip` (string, optional) — `overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다. 해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔 「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.
- `processedAt` (datetime, optional) — 문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.
- `blockers` (list of CertificateBlocker, optional) — `certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.

## Types

### AgentTransferInputTargetsItems

- `label` (string, required) — 에이전트가 전환할 때 고르는 이름. 20자 이내이고 겹칠 수 없습니다.
- `number` (string, required) — 전환할 국내 번호
- `weeklySchedule` (AgentTransferWeeklySchedule, optional) — 이 대상의 주간 일정. 없으면 항상 전환할 수 있습니다.

### AgentTransferInputWhisper

- `enabled` (boolean, required)
- `template` (string, optional) — 안내 문구. `{발신번호}`, `{사유}` 를 쓸 수 있습니다. 생략하면 기본 문구입니다.

### AgentTransferInputOnFailure

- `enabled` (boolean, required)
- `message` (string, optional) — 연결되지 않았을 때 발신자에게 들려주는 안내

### AgentTransferTargetsItems

- `label` (string, required) — 에이전트가 전환할 때 고르는 이름
- `number` (string, required) — 전환할 국내 번호
- `weeklySchedule` (AgentTransferWeeklySchedule, optional) — 이 대상의 주간 일정. 없으면 항상 전환할 수 있습니다.

### AgentTransferWhisper

담당자가 받은 직후 담당자에게만 들려주는 안내

- `enabled` (boolean, required)
- `template` (string, required) — 안내 문구. `{발신번호}`, `{사유}` 를 쓸 수 있습니다.

### AgentTransferOnFailure

연결되지 않았을 때 발신자에게 들려주는 안내

- `enabled` (boolean, required)
- `message` (string, required)

### CertificateBlocker

번호 하나가 발급되지 않는(또는 안내가 필요한) 이유. | code | 뜻 | 발급 | |---|---|---| | `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 | | `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 | | `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 | | `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 | | `account_restricted` | 이용 제한 계정 | 막힘 | | `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 | | `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |

- `code` (enum, required)
  - Allowed values: `number_not_owned`, `number_not_carrier_issued`, `business_info_incomplete`, `identity_unverified`, `account_restricted`, `business_recheck_pending`, `holder_is_personal`
- `message` (string, required)
- `number` (string, optional) — 422 응답의 blockers 에만 있다

### AgentTransferWeeklySchedule

이 대상의 주간 일정. 없으면 항상 전환할 수 있습니다.

- `timezone` (enum, required)
  - Allowed values: `Asia/Seoul`
- `windows` (list of AgentTransferWeeklyScheduleWindowsItems, required) — 요일별 구간. 요일당 하나입니다.
- `excludedDates` (list of string, optional) — 전환하지 않을 날짜(YYYY-MM-DD)

### AgentTransferWeeklyScheduleWindowsItems

- `day` (integer, required) — 요일. 0이 월요일입니다.
- `start` (string, required) — 시작 시각(HH:MM)
- `end` (string, required) — 종료 시각(HH:MM). 시작보다 뒤여야 합니다.

## Examples

**Request**

```json
{
  "enabled": true,
  "targets": [
    {
      "label": "상담팀",
      "number": "010-1234-5678"
    }
  ]
}
```

**Response**

```json
{
  "enabled": true,
  "targets": [
    {
      "label": "상담팀",
      "number": "01012345678",
      "weeklySchedule": {
        "timezone": "Asia/Seoul",
        "windows": [
          {
            "day": 0,
            "start": "13:00",
            "end": "18:00"
          }
        ],
        "excludedDates": [
          "2026-12-25"
        ]
      }
    }
  ],
  "callerId": "account",
  "whisper": {
    "enabled": true,
    "template": "{발신번호} 고객님, {사유} 문의입니다"
  },
  "timeout": 30,
  "holdMedia": "moh",
  "onFailure": {
    "enabled": true,
    "message": "지금은 상담원 연결이 어렵습니다."
  },
  "activeFrom": "2024-01-15T09:30:00Z",
  "activeUntil": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python Agents_putAgentTransfer_example
import requests

url = "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer"

payload = {
    "enabled": True,
    "targets": [
        {
            "label": "상담팀",
            "number": "010-1234-5678"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript Agents_putAgentTransfer_example
const url = 'https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"enabled":true,"targets":[{"label":"상담팀","number":"010-1234-5678"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Agents_putAgentTransfer_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer"

	payload := strings.NewReader("{\n  \"enabled\": true,\n  \"targets\": [\n    {\n      \"label\": \"상담팀\",\n      \"number\": \"010-1234-5678\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Agents_putAgentTransfer_example
require 'uri'
require 'net/http'

url = URI("https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"enabled\": true,\n  \"targets\": [\n    {\n      \"label\": \"상담팀\",\n      \"number\": \"010-1234-5678\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Agents_putAgentTransfer_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"enabled\": true,\n  \"targets\": [\n    {\n      \"label\": \"상담팀\",\n      \"number\": \"010-1234-5678\"\n    }\n  ]\n}")
  .asString();
```

```php Agents_putAgentTransfer_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer', [
  'body' => '{
  "enabled": true,
  "targets": [
    {
      "label": "상담팀",
      "number": "010-1234-5678"
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Agents_putAgentTransfer_example
using RestSharp;

var client = new RestClient("https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"enabled\": true,\n  \"targets\": [\n    {\n      \"label\": \"상담팀\",\n      \"number\": \"010-1234-5678\"\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Agents_putAgentTransfer_example
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "enabled": true,
  "targets": [
    [
      "label": "상담팀",
      "number": "010-1234-5678"
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.claw-ops.com/v1/accounts/AC1a2b3c4d/agents/agentId/transfer")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```