> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 카카오 채널

> 카카오 채널을 API로 만들 때 넣는 값, 쓸 수 있는 작업, 응답 필드를 볼 수 있어요.

`channel`이 `kakao`인 채널의 API 계약이에요. 연결 절차는 [카카오 상담톡 연결과 운영](https://docs.tryvox.co/docs/operate/deploy/integrations/kakao/overview.md)에 있어요.

## 생성 요청

[채널 생성](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-생성.md)의 `params`에 아래 값을 넣어요. `name`, `agent` 같은 공통 필드는 채널 생성 페이지에 있어요.

### 인증번호로 등록

| 필드 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `search_id` | string | 필수 | 카카오톡 채널 검색용 아이디입니다. 앞의 `@`를 빼고 보내도 됩니다. |
| `channel_url` | string | 필수 | `pf.kakao.com` 채널 URL 또는 채널 키입니다. |
| `category_code` | string | 필수 | 발신프로필 카테고리 코드입니다(11자리). `GET /v3/chat-channels/business-categories` 응답의 `code`를 사용합니다. |
| `phone_number` | string | 필수 | 채널 관리자 휴대폰 번호입니다. 저장하지 않으며 응답에 반환하지 않습니다. |
| `verification_code` | string | 필수 | 문자로 받은 인증번호입니다. |

### 발신프로필 키로 등록

| 필드 | 타입 | 필수 | 설명 |
| - | - | - | - |
| `sender_key` | string | 필수 | 기존 발신프로필 키입니다(40자리). 소문자로 바꿔 저장합니다. |

```json 요청: 카카오 인증번호로 등록 theme={null}
{
  "channel": "kakao",
  "name": "고객지원 카카오",
  "agent": {
    "agent_id": "44444444-4444-4444-8444-444444444444",
    "agent_version": "production"
  },
  "params": {
    "search_id": "@voxexample",
    "channel_url": "https://pf.kakao.com/_xExample",
    "category_code": "01300010001",
    "phone_number": "01000000000",
    "verification_code": "000000"
  }
}
```

```json 요청: 카카오 발신프로필 키로 등록 theme={null}
{
  "channel": "kakao",
  "name": "고객지원 카카오",
  "agent": {
    "agent_id": "44444444-4444-4444-8444-444444444444",
    "agent_version": "production"
  },
  "params": {
    "sender_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

```json 201 응답 theme={null}
{
  "chat_channel": {
    "id": "11111111-1111-4111-8111-111111111111",
    "organization_id": "55555555-5555-4555-8555-555555555555",
    "status": "active",
    "status_detail": null,
    "operation_enabled": true,
    "name": "고객지원 카카오",
    "display_name": "고객지원 카카오",
    "agent": {
      "agent_id": "44444444-4444-4444-8444-444444444444",
      "agent_version": "production"
    },
    "initial_responder_type": "agent",
    "created_at": 1794351600000,
    "updated_at": 1794351600000,
    "allow_agent_response": true,
    "channel": "kakao",
    "details": {
      "search_id": "@voxexample",
      "channel_key": "_xExample",
      "sender_key": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "category_code": "01300010001",
      "kakao_status": "normal",
      "last_received_at": null,
      "last_error": null,
      "link_url": "https://bizmessage.kakao.com/chat/open/@voxexample"
    }
  },
  "verification": null
}
```

## 쓸 수 있는 작업

* [채널 생성](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-생성.md)
* [채널 목록 조회](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-목록-조회.md)
* [채널 조회](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-조회.md)
* [채널 수정](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-수정.md)
* [채널 삭제](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-삭제.md)
* [채널 인증 신청](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-인증-신청.md)
* [채널 활성화](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-활성화.md)
* [채널 비활성화](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-비활성화.md)
* [채널 연결 해제](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-연결-해제.md)
* [채널 재연결](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-재연결.md)
* [카카오 카테고리 목록 조회](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-카테고리-목록-조회.md)
* [카카오 상담 연결 링크 생성](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-상담-연결-링크-생성.md)
* [카카오 상담시간 조회](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-상담시간-조회.md)
* [카카오 상담시간 수정](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-상담시간-수정.md)
* [카카오 이용자 차단](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-이용자-차단.md)
* [카카오 이용자 차단 해제](https://docs.tryvox.co/api-reference/v3/chat-channels/카카오-이용자-차단-해제.md)

## 수정할 수 있는 값

[채널 수정](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-수정.md)에서 `params`를 받지 않아요. 이름, 에이전트, 최초 응답 담당, AI 사용 허용만 수정할 수 있어요.

## 응답의 `details`

[채널 조회](https://docs.tryvox.co/api-reference/v3/chat-channels/채널-조회.md) 응답의 `details`에 아래 값이 있어요.

| 필드 | 타입 | 설명 |
| - | - | - |
| `search_id` | string \| null | 카카오톡 채널 검색용 아이디입니다(`@`로 시작). |
| `channel_key` | string \| null | 카카오톡 채널 키입니다(`pf.kakao.com/` 뒤의 `_`로 시작하는 값). |
| `sender_key` | string \| null | 발신프로필 키입니다. 인증 토큰은 반환하지 않습니다. |
| `category_code` | string \| null | 발신프로필 카테고리 코드입니다(11자리). |
| `kakao_status` | string | 카카오 쪽 채널 상태입니다. `normal`은 정상, `dormant`는 휴면, `blocked`는 차단, `counsel_off`는 상담톡 꺼짐, `unknown`은 확인 전입니다. 하루 한 번 확인하고, 채널 조회 때도 다시 읽습니다(실패하면 저장된 값). |
| `last_received_at` | integer \| null | 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. |
| `last_error` | LastError \| null | 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. |
| `link_url` | string \| null | 기본 카카오 상담 연결 URL입니다. |

## 받는 메시지

글자와 이미지를 읽어요. 이미지는 메시지마다 3장까지예요. 읽지 않는 메시지의 처리는 [카카오 상담톡 연결과 운영](https://docs.tryvox.co/docs/operate/deploy/integrations/kakao/overview.md#지원하는-메시지)에 있어요.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.