> ## 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. # 채널 생성 > 메신저 채널 하나를 만듭니다. `channel`로 채널 종류를 고르고 `params`에 그 채널의 연결 정보를 넣습니다. - 카카오(인증번호로 등록)와 인스타그램은 먼저 `POST /v3/chat-channels/verification`으로 인증을 신청합니다. - 카카오 채널은 활성화된 채로 만들어집니다. 다른 채널은 비활성화된 채로 만들어지므로 `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화합니다. - 네이버톡톡은 응답 `verification`의 확인 코드를 네이버톡톡 대화창에서 보내야 연결이 확인됩니다. - SMS 채널은 전화번호 API에서 만들며 이 API로 만들지 않습니다. `channel`이 `sms`이면 400 `CHAT_CHANNEL_OPERATION_UNSUPPORTED`로 거절합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /chat-channels openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 워크스페이스 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 대량 발신 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /chat-channels: post: tags: - Chat channels summary: 채널 생성 description: >- 메신저 채널 하나를 만듭니다. `channel`로 채널 종류를 고르고 `params`에 그 채널의 연결 정보를 넣습니다. - 카카오(인증번호로 등록)와 인스타그램은 먼저 `POST /v3/chat-channels/verification`으로 인증을 신청합니다. - 카카오 채널은 활성화된 채로 만들어집니다. 다른 채널은 비활성화된 채로 만들어지므로 `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화합니다. - 네이버톡톡은 응답 `verification`의 확인 코드를 네이버톡톡 대화창에서 보내야 연결이 확인됩니다. - SMS 채널은 전화번호 API에서 만들며 이 API로 만들지 않습니다. `channel`이 `sms`이면 400 `CHAT_CHANNEL_OPERATION_UNSUPPORTED`로 거절합니다. operationId: createChatChannel requestBody: required: true content: application/json: schema: title: Body oneOf: - $ref: '#/components/schemas/KakaoCreateRequest' - $ref: '#/components/schemas/NavertalkCreateRequest' - $ref: '#/components/schemas/InstagramCreateRequest' - $ref: '#/components/schemas/LineCreateRequest' - $ref: '#/components/schemas/WechatCreateRequest' - $ref: '#/components/schemas/ChannelTalkCreateRequest' discriminator: propertyName: channel mapping: kakao: '#/components/schemas/KakaoCreateRequest' navertalk: '#/components/schemas/NavertalkCreateRequest' instagram: '#/components/schemas/InstagramCreateRequest' line: '#/components/schemas/LineCreateRequest' wechat: '#/components/schemas/WechatCreateRequest' channeltalk: '#/components/schemas/ChannelTalkCreateRequest' examples: 카카오 인증번호로 등록: summary: 카카오 · 인증번호로 등록 description: >- 먼저 `POST /v3/chat-channels/verification`에 `channel=kakao`로 요청해 채널 관리자 휴대폰으로 인증번호를 받습니다. value: 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' 카카오 발신프로필 키로 등록: summary: 카카오 · 발신프로필 키로 등록 value: channel: kakao name: 고객지원 카카오 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production params: sender_key: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa 네이버톡톡: summary: 네이버톡톡 description: 응답 `verification`의 확인 코드를 네이버톡톡 대화창에서 보내면 연결이 확인됩니다. value: channel: navertalk name: 고객지원 네이버톡톡 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production params: partner_id: wexample access_token: EXAMPLE_NAVERTALK_ACCESS_TOKEN 인스타그램: summary: 인스타그램 description: >- `POST /v3/chat-channels/verification`에 `channel=instagram`으로 요청해 받은 `authorize_url`에서 인증한 뒤, 받은 `state`와 `code`를 보냅니다. value: channel: instagram name: 고객지원 인스타그램 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production params: state: EXAMPLE_SIGNED_STATE code: EXAMPLE_META_AUTHORIZATION_CODE 라인: summary: 라인 value: channel: line name: 고객지원 라인 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production params: channel_id: '2000000000' channel_secret: EXAMPLE_LINE_CHANNEL_SECRET 위챗: summary: 위챗 value: channel: wechat name: 고객지원 위챗 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production params: app_id: wx00000000example0 original_id: gh_000000example message_mode: safe app_secret: EXAMPLE_WECHAT_APP_SECRET token: EXAMPLE_WECHAT_TOKEN encoding_aes_key: EXAMPLE000000000000000000000000000000000000 채널톡: summary: 채널톡 description: '`name`을 생략하면 채널톡 채널 이름을 씁니다.' value: channel: channeltalk agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production initial_responder_type: external allow_agent_response: false params: access_key: EXAMPLE_CHANNELTALK_ACCESS_KEY access_secret: EXAMPLE_CHANNELTALK_ACCESS_SECRET description: 만들 채널의 종류와 그 채널의 연결 정보입니다. responses: '201': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/ChannelSetupResult' examples: 카카오: summary: 카카오 value: 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 네이버톡톡: summary: 네이버톡톡 value: chat_channel: id: 22222222-2222-4222-8222-222222222222 organization_id: 55555555-5555-4555-8555-555555555555 status: provider_pending status_detail: verify operation_enabled: false 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: navertalk details: partner_id: wexample webhook_url: >- https://client-api.tryvox.co/navertalk/9a9a9a9a-0000-4000-8000-000000000001/events verified_at: null last_received_at: null last_error_code: null last_error: null verification: channel: navertalk chat_channel_id: 22222222-2222-4222-8222-222222222222 next_action: send_code_in_navertalk details: verification_code: EXAMPLE0000 expires_at: 1794352500000 webhook_url: >- https://client-api.tryvox.co/navertalk/9a9a9a9a-0000-4000-8000-000000000001/events 인스타그램: summary: 인스타그램 value: chat_channel: id: 33333333-3333-4333-8333-333333333333 organization_id: 55555555-5555-4555-8555-555555555555 status: disabled status_detail: null operation_enabled: false 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: instagram details: last_received_at: null last_error_code: null last_error: null instagram_account_id: '17840000000000000' instagram_username: vox_example verification: null 라인: summary: 라인 value: chat_channel: id: 66666666-6666-4666-8666-666666666666 organization_id: 55555555-5555-4555-8555-555555555555 status: disabled status_detail: null operation_enabled: false 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: line details: last_received_at: null last_error_code: null last_error: null channel_id: '2000000000' bot_basic_id: '@000example' bot_display_name: vox.ai 고객지원 webhook_url: >- https://client-api.tryvox.co/line/9a9a9a9a-0000-4000-8000-000000000002/events verified_at: 1794351600000 verification: null 위챗: summary: 위챗 value: chat_channel: id: 77777777-7777-4777-8777-777777777777 organization_id: 55555555-5555-4555-8555-555555555555 status: disabled status_detail: null operation_enabled: false 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: wechat details: last_received_at: null last_error_code: null last_error: null app_id: wx00000000example0 original_id: gh_000000example message_mode: safe webhook_url: >- https://client-api.tryvox.co/wechat/9a9a9a9a-0000-4000-8000-000000000003/events verified_at: 1794351600000 verification: null 채널톡: summary: 채널톡 value: chat_channel: id: 88888888-8888-4888-8888-888888888888 organization_id: 55555555-5555-4555-8555-555555555555 status: disabled status_detail: null operation_enabled: false name: vox.ai 고객지원 display_name: vox.ai 고객지원 agent: agent_id: 44444444-4444-4444-8444-444444444444 agent_version: production initial_responder_type: external created_at: 1794351600000 updated_at: 1794351600000 allow_agent_response: false channel: channeltalk details: channel_id: '200000' channel_name: vox.ai 고객지원 bot_name: null verified_at: 1794351600000 webhook_ok: null last_received_at: null last_error_code: null last_error: null verification: null '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: >- 요청 한도를 초과했습니다. API 키 트래픽은 기본값으로 워크스페이스당 초당 5회·분당 120회, Supabase JWT 트래픽은 기본값으로 사용자당 초당 10회·분당 240회로 제한되며, 워크스페이스 대시보드에는 기본 분당 2,400회의 백스톱 한도가 적용됩니다. 한도는 운영자가 조정할 수 있고, 초과한 버킷의 실제 한도와 윈도우는 429 응답의 X-RateLimit-Limit·X-RateLimit-Window 헤더로 알려 줍니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. headers: Retry-After: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우가 초기화될 때까지 남은 시간입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 최대 요청 수입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 X-RateLimit-Window: description: >- 초과한 공용 v3 인증 주체(auth-principal) 리미터 윈도우의 길이입니다. 단위는 초입니다. 개별 경로 자체 리미터가 만든 429 응답에는 이 헤더가 없을 수 있습니다. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 10 window_seconds: 1 scope: user '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: KakaoCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: 대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: kakao title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: anyOf: - $ref: '#/components/schemas/KakaoCodeParams' - $ref: '#/components/schemas/KakaoKeyParams' title: Params description: >- 「인증번호로 등록」의 값(`search_id`, `channel_url`, `category_code`, `phone_number`, `verification_code`) 또는 「발신프로필 키로 등록」의 값(`sender_key`) 중 하나입니다. additionalProperties: false type: object required: - name - agent - channel - params title: 카카오 NavertalkCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: 대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: navertalk title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: $ref: '#/components/schemas/NaverCreateParams' description: 네이버톡톡 연결 정보입니다. additionalProperties: false type: object required: - name - agent - channel - params title: 네이버톡톡 InstagramCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: 대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: instagram title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: $ref: '#/components/schemas/InstagramCompleteParams' description: 인스타그램 인증을 마친 뒤 받은 `state`와 `code`입니다. additionalProperties: false type: object required: - name - agent - channel - params title: 인스타그램 LineCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: 대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: line title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: $ref: '#/components/schemas/LineCreateParams' description: 라인 연결 정보입니다. additionalProperties: false type: object required: - name - agent - channel - params title: 라인 WechatCreateRequest: properties: name: type: string maxLength: 255 minLength: 1 title: Name description: 대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: wechat title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: $ref: '#/components/schemas/WechatCreateParams' description: 위챗 연결 정보입니다. additionalProperties: false type: object required: - name - agent - channel - params title: 위챗 ChannelTalkCreateRequest: properties: name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Name description: >- 대시보드에 표시할 채널 이름입니다. 생략하면 채널톡 채널 이름을 씁니다. 채널을 활성화할 때 앞 30자가 채널톡 봇 이름이 됩니다. display_name: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Display Name description: >- 지원 종료 예정입니다. `name`을 쓰세요. `name`과 함께 보내면 두 값이 같아야 하며, 다르면 400 `VALIDATION_ERROR`로 거절합니다. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: anyOf: - type: string enum: - agent - desk - external - type: 'null' title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 `agent`이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. allow_agent_response: anyOf: - type: boolean - type: 'null' title: Allow Agent Response description: >- AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 `agent`가 아니어야 합니다. channel: type: string const: channeltalk title: Channel description: >- 만들 채널의 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk` 중 하나이며, 이 값에 따라 `params` 형식이 정해집니다. params: $ref: '#/components/schemas/ChannelTalkCreateParams' description: 채널톡 인증 키입니다. additionalProperties: false type: object required: - agent - channel - params title: 채널톡 ChannelSetupResult: properties: chat_channel: oneOf: - $ref: '#/components/schemas/KakaoChannel' - $ref: '#/components/schemas/NavertalkChannel' - $ref: '#/components/schemas/InstagramChannel' - $ref: '#/components/schemas/LineChannel' - $ref: '#/components/schemas/WechatChannel' - $ref: '#/components/schemas/ChannelTalkChannel' - $ref: '#/components/schemas/SmsChannel' title: Chat Channel description: 만든 채널입니다. discriminator: propertyName: channel mapping: kakao: '#/components/schemas/KakaoChannel' navertalk: '#/components/schemas/NavertalkChannel' instagram: '#/components/schemas/InstagramChannel' line: '#/components/schemas/LineChannel' wechat: '#/components/schemas/WechatChannel' channeltalk: '#/components/schemas/ChannelTalkChannel' sms: '#/components/schemas/SmsChannel' verification: anyOf: - $ref: '#/components/schemas/NaverVerificationResult' - type: 'null' description: 네이버톡톡 채널을 만들었으면 확인 코드 정보이고, 다른 채널은 null입니다. type: object required: - chat_channel - verification title: ChannelSetupResult ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. AgentMapping: additionalProperties: false description: >- `agent_id`와 `agent_version` 매핑입니다. 요청·응답 모두에서 에이전트 매핑이 필요한 경우 이 타입을 사용합니다. version 지정이 필요 없는 엔드포인트는 flat `agent_id: UUID`를 직접 받고 `AgentMapping`을 사용하지 않습니다. properties: agent_id: description: 에이전트 UUID입니다. format: uuid title: Agent Id type: string x-vox-effect: wiring agent_version: default: current description: >- 에이전트 버전입니다. 허용값은 "current", "production", "v{n}"(n≥1)입니다. 보내지 않으면 "current"로 처리합니다. null 전송은 거부합니다. title: Agent Version type: string x-vox-effect: wiring pattern: ^(current|production|v[1-9][0-9]*)$ examples: - current - production - v1 required: - agent_id title: AgentMapping type: object KakaoCodeParams: properties: search_id: type: string maxLength: 65 minLength: 1 title: Search Id description: 카카오톡 채널 검색용 아이디입니다. 앞의 `@`를 빼고 보내도 됩니다. channel_url: type: string maxLength: 200 minLength: 2 title: Channel Url description: '`pf.kakao.com` 채널 URL 또는 채널 키입니다.' category_code: type: string pattern: ^[0-9]{11}$ title: Category Code description: >- 발신프로필 카테고리 코드입니다(11자리). `GET /v3/chat-channels/business-categories` 응답의 `code`를 사용합니다. phone_number: type: string maxLength: 20 title: Phone Number description: 채널 관리자 휴대폰 번호입니다. 저장하지 않으며 응답에 반환하지 않습니다. verification_code: type: string pattern: ^[0-9A-Za-z]{4,12}$ title: Verification Code description: 문자로 받은 인증번호입니다. additionalProperties: false type: object required: - search_id - channel_url - category_code - phone_number - verification_code title: 인증번호로 등록 KakaoKeyParams: properties: sender_key: type: string maxLength: 64 title: Sender Key description: 기존 발신프로필 키입니다(40자리). 소문자로 바꿔 저장합니다. additionalProperties: false type: object required: - sender_key title: 발신프로필 키로 등록 NaverCreateParams: properties: partner_id: type: string maxLength: 255 minLength: 1 title: Partner Id description: 네이버톡톡 파트너 ID입니다. 계정 소유를 증명하는 값은 아닙니다. access_token: type: string maxLength: 4096 minLength: 1 format: password title: Access Token description: 네이버톡톡 Authorization 토큰입니다. 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true additionalProperties: false type: object required: - partner_id - access_token title: NaverCreateParams InstagramCompleteParams: properties: state: type: string maxLength: 2048 minLength: 1 format: password title: State description: >- `POST /v3/chat-channels/verification` 응답으로 받은 서명된 `state`입니다. 10분 동안 유효하며, 워크스페이스, 사용자, 에이전트, 대상 채널을 확인하는 데 씁니다. writeOnly: true code: type: string maxLength: 4096 minLength: 1 format: password title: Code description: 인스타그램 인증 뒤 돌려받은 일회용 `code`입니다. writeOnly: true additionalProperties: false type: object required: - state - code title: InstagramCompleteParams LineCreateParams: properties: channel_id: type: string maxLength: 32 minLength: 1 title: Channel Id description: 라인 Messaging API의 Channel ID입니다. channel_secret: type: string maxLength: 256 minLength: 1 format: password title: Channel Secret description: 라인 Channel secret입니다. 자격을 확인한 뒤 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true additionalProperties: false type: object required: - channel_id - channel_secret title: LineCreateParams WechatCreateParams: properties: app_id: type: string pattern: ^[A-Za-z0-9_-]{1,64}$ title: App Id description: 서비스 계정 AppID입니다. original_id: type: string pattern: ^gh_[A-Za-z0-9_-]{1,61}$ title: Original Id description: 원시 ID입니다(`gh_`로 시작). message_mode: type: string enum: - plaintext - safe title: Message Mode description: 위챗 서버 설정의 메시지 암호화 모드입니다. `plaintext` 또는 `safe`입니다. app_secret: type: string maxLength: 256 minLength: 1 format: password title: App Secret description: 서비스 계정 AppSecret입니다. 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true token: type: string maxLength: 128 minLength: 1 format: password title: Token description: 위챗 서버 설정에 넣는 웹훅 서명용 Token입니다. 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true encoding_aes_key: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Encoding Aes Key description: >- `safe` 모드에 필요한 EncodingAESKey입니다(영문·숫자 43자). 암호화해 저장하며 응답에 반환하지 않습니다. additionalProperties: false type: object required: - app_id - original_id - message_mode - app_secret - token title: WechatCreateParams ChannelTalkCreateParams: properties: access_key: type: string maxLength: 256 minLength: 1 format: password title: Access Key description: >- 채널톡 「채널 설정 > 보안 및 개발 > API」에서 만든 인증 키의 Access Key입니다. 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true access_secret: type: string maxLength: 256 minLength: 1 format: password title: Access Secret description: 같은 화면의 Access Secret입니다. 암호화해 저장하며 응답에 반환하지 않습니다. writeOnly: true additionalProperties: false type: object required: - access_key - access_secret title: ChannelTalkCreateParams KakaoChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: kakao title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/KakaoDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 카카오 NavertalkChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: navertalk title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/NaverDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 네이버톡톡 InstagramChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: instagram title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/InstagramDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 인스타그램 LineChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: line title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/LineDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 라인 WechatChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: wechat title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/WechatDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 위챗 ChannelTalkChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: channeltalk title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/ChannelTalkDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: 채널톡 SmsChannel: properties: id: type: string format: uuid title: Id description: 채널 ID입니다. UUID이며 경로 파라미터 `chat_channel_id`에 사용합니다. organization_id: type: string format: uuid title: Organization Id description: 채널을 소유한 워크스페이스 ID입니다. status: type: string enum: - provider_pending - active - disabled - failed - disconnected title: Status description: >- 채널의 현재 상태입니다. `active`는 문의를 받아 응대하는 중, `disabled`는 채널을 비활성화한 상태, `provider_pending`은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), `failed`는 이 API에 다시 요청해야 풀리는 상태, `disconnected`는 연결을 해제한 상태입니다. status_detail: anyOf: - type: string enum: - verify - reconnect - retry_operation - check_provider - type: 'null' title: Status Detail description: >- 다음에 할 일입니다. 없으면 null입니다. `verify`는 `POST /v3/chat-channels/verification`으로 인증을 신청합니다(채널별 단계는 그 응답의 `next_action`). `reconnect`는 `POST /v3/chat-channels/{chat_channel_id}/reconnect`를 호출합니다. `retry_operation`은 `operation_enabled`가 true이면 `POST /v3/chat-channels/{chat_channel_id}/enable`을, false이면 `POST /v3/chat-channels/{chat_channel_id}/disable`을 다시 호출합니다. `check_provider`는 공급자 쪽에서 해결할 일이 있다는 뜻이며 내용은 `details`에 있습니다. operation_enabled: type: boolean title: Operation Enabled description: >- 채널을 활성화해 두었는지입니다. `POST /v3/chat-channels/{chat_channel_id}/enable`로 활성화하면 true, `POST /v3/chat-channels/{chat_channel_id}/disable`로 비활성화하면 false입니다. 실제로 운영 중인지는 `status`로 확인합니다. 연결을 해제한 채널은 false입니다. name: anyOf: - type: string - type: 'null' title: Name description: 대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다. display_name: anyOf: - type: string - type: 'null' title: Display Name description: 지원 종료 예정입니다. `name`과 같은 값이므로 `name`을 쓰세요. deprecated: true agent: $ref: '#/components/schemas/AgentMapping' description: '`agent_id`와 `agent_version`으로 구성된 에이전트 매핑 객체입니다.' initial_responder_type: type: string enum: - agent - desk - external title: Initial Responder Type description: >- 새 채팅의 최초 응답 담당입니다. `agent`는 AI 에이전트, `external`은 고객사 시스템입니다. `desk`는 vox.ai 상담 화면용 값입니다. created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. allow_agent_response: type: boolean title: Allow Agent Response description: >- 현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다. channel: type: string const: sms title: Channel description: >- 채널 종류입니다. `kakao`, `navertalk`, `instagram`, `line`, `wechat`, `channeltalk`, `sms` 중 하나이며, 이 값에 따라 `details` 형식이 정해집니다. details: $ref: '#/components/schemas/SmsDetails' description: 채널별 연결 정보입니다. type: object required: - id - organization_id - status - status_detail - operation_enabled - name - display_name - agent - initial_responder_type - created_at - updated_at - allow_agent_response - channel - details title: SMS NaverVerificationResult: properties: channel: type: string const: navertalk title: Channel description: 인증을 신청한 채널입니다. 이 값에 따라 `next_action`과 `details` 형식이 정해집니다. chat_channel_id: type: string format: uuid title: Chat Channel Id description: 확인 코드를 발급한 채널 ID입니다. next_action: type: string const: send_code_in_navertalk title: Next Action description: >- 다음에 할 일입니다. `send_code_in_navertalk`는 `details.verification_code`를 네이버톡톡 대화창에서 보냅니다. details: $ref: '#/components/schemas/NaverVerificationDetails' description: 확인 코드 정보입니다. type: object required: - channel - chat_channel_id - next_action - details title: 네이버톡톡 ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. KakaoDetails: properties: search_id: anyOf: - type: string - type: 'null' title: Search Id description: 카카오톡 채널 검색용 아이디입니다(`@`로 시작). channel_key: anyOf: - type: string - type: 'null' title: Channel Key description: 카카오톡 채널 키입니다(`pf.kakao.com/` 뒤의 `_`로 시작하는 값). sender_key: anyOf: - type: string - type: 'null' title: Sender Key description: 발신프로필 키입니다. 인증 토큰은 반환하지 않습니다. category_code: anyOf: - type: string - type: 'null' title: Category Code description: 발신프로필 카테고리 코드입니다(11자리). kakao_status: type: string enum: - normal - dormant - blocked - counsel_off - unknown title: Kakao Status description: >- 카카오 쪽 채널 상태입니다. `normal`은 정상, `dormant`는 휴면, `blocked`는 차단, `counsel_off`는 상담톡 꺼짐, `unknown`은 확인 전입니다. 하루 한 번 확인하고, 채널 조회 때도 다시 읽습니다(실패하면 저장된 값). last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. link_url: anyOf: - type: string - type: 'null' title: Link Url description: 기본 카카오 상담 연결 URL입니다. type: object required: - search_id - channel_key - sender_key - category_code - kakao_status - last_received_at - last_error - link_url title: KakaoDetails NaverDetails: properties: partner_id: type: string title: Partner Id description: 네이버톡톡 파트너 ID입니다. webhook_url: type: string title: Webhook Url description: 공급자 화면에 넣는 전체 웹훅 주소입니다. `https://client-api.tryvox.co`로 시작합니다. verified_at: anyOf: - type: integer - type: 'null' title: Verified At description: 확인 코드 검증이 끝난 시각입니다(unix ms). null이면 아직 검증 전입니다. last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error_code: anyOf: - type: string - type: 'null' title: Last Error Code description: >- 지원 종료 예정입니다. `last_error.code`와 같은 값이므로 `last_error`를 쓰세요. 최근 연결·운영 오류 코드이며, 없으면 null입니다. deprecated: true last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. type: object required: - partner_id - webhook_url - verified_at - last_received_at - last_error_code - last_error title: NaverDetails InstagramDetails: properties: last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error_code: anyOf: - type: string - type: 'null' title: Last Error Code description: >- 지원 종료 예정입니다. `last_error.code`와 같은 값이므로 `last_error`를 쓰세요. 최근 연결·운영 오류 코드이며, 없으면 null입니다. deprecated: true last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. instagram_account_id: type: string title: Instagram Account Id description: 연결한 인스타그램 프로페셔널 계정 ID입니다. instagram_username: anyOf: - type: string - type: 'null' title: Instagram Username description: 인스타그램 사용자 이름입니다. 채널 이름(`name`)과는 따로 둡니다. type: object required: - last_received_at - last_error_code - last_error - instagram_account_id - instagram_username title: InstagramDetails LineDetails: properties: last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error_code: anyOf: - type: string - type: 'null' title: Last Error Code description: >- 지원 종료 예정입니다. `last_error.code`와 같은 값이므로 `last_error`를 쓰세요. 최근 연결·운영 오류 코드이며, 없으면 null입니다. deprecated: true last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. channel_id: type: string title: Channel Id description: 라인 Messaging API의 Channel ID입니다. bot_basic_id: anyOf: - type: string - type: 'null' title: Bot Basic Id description: 라인 공식 계정 Basic ID입니다(`@`로 시작). bot_display_name: anyOf: - type: string - type: 'null' title: Bot Display Name description: 라인 공식 계정의 봇 이름입니다. 채널 이름(`name`)과는 따로 둡니다. webhook_url: type: string title: Webhook Url description: 공급자 화면에 넣는 전체 웹훅 주소입니다. `https://client-api.tryvox.co`로 시작합니다. verified_at: anyOf: - type: integer - type: 'null' title: Verified At description: 마지막으로 자격 확인에 성공한 시각입니다(unix ms). 웹훅이 도달했는지를 뜻하지는 않습니다. type: object required: - last_received_at - last_error_code - last_error - channel_id - bot_basic_id - bot_display_name - webhook_url - verified_at title: LineDetails WechatDetails: properties: last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error_code: anyOf: - type: string - type: 'null' title: Last Error Code description: >- 지원 종료 예정입니다. `last_error.code`와 같은 값이므로 `last_error`를 쓰세요. 최근 연결·운영 오류 코드이며, 없으면 null입니다. deprecated: true last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. app_id: type: string title: App Id description: 서비스 계정 AppID입니다. original_id: type: string title: Original Id description: 원시 ID입니다(`gh_`로 시작). message_mode: type: string enum: - plaintext - safe title: Message Mode description: 위챗 서버 설정의 메시지 암호화 모드입니다. `plaintext` 또는 `safe`입니다. webhook_url: type: string title: Webhook Url description: 공급자 화면에 넣는 전체 웹훅 주소입니다. `https://client-api.tryvox.co`로 시작합니다. verified_at: anyOf: - type: integer - type: 'null' title: Verified At description: >- AppID와 AppSecret으로 위챗 액세스 토큰 발급에 마지막으로 성공한 시각입니다(unix ms). 웹훅이 도달했는지를 뜻하지는 않습니다. type: object required: - last_received_at - last_error_code - last_error - app_id - original_id - message_mode - webhook_url - verified_at title: WechatDetails ChannelTalkDetails: properties: channel_id: type: string title: Channel Id description: 채널톡(Channel.io) 채널 ID입니다. 인증 키로 조회한 값입니다. channel_name: anyOf: - type: string - type: 'null' title: Channel Name description: 채널톡 채널 이름입니다. bot_name: anyOf: - type: string - type: 'null' title: Bot Name description: vox.ai가 답할 때 쓰는 채널톡 봇 이름입니다. 채널을 활성화할 때 정해집니다. verified_at: anyOf: - type: integer - type: 'null' title: Verified At description: 마지막으로 키 확인에 성공한 시각입니다(unix ms). null이면 다시 확인해야 합니다. webhook_ok: anyOf: - type: boolean - type: 'null' title: Webhook Ok description: 채널을 활성화할 때 등록한 웹훅의 상태입니다. 메시지가 들어오면 true가 됩니다. 비활성화한 채널은 null입니다. last_received_at: anyOf: - type: integer - type: 'null' title: Last Received At description: 이 채널로 고객 메시지를 마지막으로 받은 시각입니다(unix ms). 받은 적이 없으면 null입니다. last_error_code: anyOf: - type: string - type: 'null' title: Last Error Code description: >- 지원 종료 예정입니다. `last_error.code`와 같은 값이므로 `last_error`를 쓰세요. 최근 연결·운영 오류 코드이며, 없으면 null입니다. deprecated: true last_error: anyOf: - $ref: '#/components/schemas/LastError' - type: 'null' description: >- 최근 연결·운영 오류입니다. 없으면 null입니다. 모든 채널이 같은 구조로 반환합니다. `message`는 카카오만 채우고 다른 채널은 null입니다. type: object required: - channel_id - channel_name - bot_name - verified_at - webhook_ok - last_received_at - last_error_code - last_error title: ChannelTalkDetails SmsDetails: properties: number: type: string title: Number description: 워크스페이스가 지금 보유한 문자 상담 번호입니다. 번호 등록과 에이전트 지정은 전화번호 API에서 합니다. type: object required: - number title: SmsDetails NaverVerificationDetails: properties: verification_code: type: string title: Verification Code description: 생성과 재발급 응답에서만 반환하는 일회용 확인 코드입니다. 15분 동안 유효합니다. expires_at: type: integer title: Expires At description: 확인 코드 만료 시각입니다(unix ms). webhook_url: type: string title: Webhook Url description: 공급자 화면에 넣는 전체 웹훅 주소입니다. `https://client-api.tryvox.co`로 시작합니다. type: object required: - verification_code - expires_at - webhook_url title: NaverVerificationDetails LastError: properties: code: type: string title: Code description: 최근 연결·운영 오류 코드입니다. message: anyOf: - type: string - type: 'null' title: Message description: 최근 오류 설명입니다. type: object required: - code - message title: LastError securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '워크스페이스 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.