채널 수정

PATCH

chat-channels

{chat_channel_id}

curl --request PATCH \
  --url https://client-api.tryvox.co/v3/chat-channels/{chat_channel_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "initial_responder_type": "external",
  "allow_agent_response": false
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provider_pending",
  "status_detail": "verify",
  "operation_enabled": true,
  "name": "<string>",
  "display_name": "<string>",
  "agent": {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_version": "current"
  },
  "initial_responder_type": "agent",
  "created_at": 123,
  "updated_at": 123,
  "allow_agent_response": true,
  "channel": "kakao",
  "details": {
    "search_id": "<string>",
    "channel_key": "<string>",
    "sender_key": "<string>",
    "category_code": "<string>",
    "kakao_status": "normal",
    "last_received_at": 123,
    "last_error": {
      "code": "<string>",
      "message": "<string>"
    },
    "link_url": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Path Parameters

chat_channel_id

string<uuid>

required

채널 ID입니다. GET /v3/chat-channels 응답의 id를 사용합니다.

Body

application/json

바꿀 필드만 보냅니다.

경로의 채널 ID로 대상 채널을 정합니다. params는 그 채널에 맞는 형식만 받습니다(네이버톡톡, 라인, 위챗, 채널톡). 생략한 필드는 그대로 둡니다.

name

string | null

채널 이름입니다. SMS 채널은 바꿀 수 없습니다.

Required string length: 1 - 255

display_name

string | null

deprecated

지원 종료 예정입니다. name을 쓰세요. name과 함께 보내면 두 값이 같아야 하며, 다르면 400 VALIDATION_ERROR로 거절합니다.

Required string length: 1 - 255

agent

AgentMapping · object | null

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

Show child attributes

initial_responder_type

enum<string> | null

새 채팅의 최초 응답 담당입니다. agent는 AI 에이전트, external은 고객사 시스템입니다. desk는 vox.ai 상담 화면용 값입니다. 생성에서 생략하면 agent이고(같은 워크스페이스가 다시 만드는 카카오 채널은 저장된 값을 유지), 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다.

Available options:

agent,

desk,

external

allow_agent_response

boolean | null

AI 사용 허용 여부입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남으며, 꺼 둔 동안 들어온 입력과 끌 때 AI를 기다리던 입력은 다시 켜도 AI가 처리하지 않습니다. 생성에서 생략하면 true이고, 수정에서 생략하면 저장된 값을 유지합니다. null은 거절합니다. false이면 최초 응답 담당이 agent가 아니어야 합니다.

params

네이버톡톡 · object

채널별 연결 설정입니다. 경로의 채널에 맞는 형식만 받습니다. 네이버톡톡은 partner_id, access_token을, 라인은 channel_secret을, 위챗은 app_id, original_id, message_mode, app_secret, token, encoding_aes_key를, 채널톡은 access_key와 access_secret을 함께 받습니다. 카카오, 인스타그램, SMS 채널은 params를 받지 않습니다.

네이버톡톡
라인
위챗
채널톡

Show child attributes

Response

성공 응답

string<uuid>

required

채널 ID입니다. UUID이며 경로 파라미터 chat_channel_id에 사용합니다.

organization_id

string<uuid>

required

채널을 소유한 워크스페이스 ID입니다.

status

enum<string>

required

채널의 현재 상태입니다. active는 문의를 받아 응대하는 중, disabled는 채널을 비활성화한 상태, provider_pending은 공급자 쪽 처리를 기다리는 상태(끝나면 저절로 바뀜), failed는 이 API에 다시 요청해야 풀리는 상태, disconnected는 연결을 해제한 상태입니다.

Available options:

provider_pending,

active,

disabled,

failed,

disconnected

status_detail

enum<string> | null

required

다음에 할 일입니다. 없으면 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에 있습니다.

Available options:

verify,

reconnect,

retry_operation,

check_provider

operation_enabled

boolean

required

채널을 활성화해 두었는지입니다. POST /v3/chat-channels/{chat_channel_id}/enable로 활성화하면 true, POST /v3/chat-channels/{chat_channel_id}/disable로 비활성화하면 false입니다. 실제로 운영 중인지는 status로 확인합니다. 연결을 해제한 채널은 false입니다.

name

string | null

required

대시보드에 표시할 채널 이름입니다. 오래된 채널은 null일 수 있습니다.

display_name

string | null

required

deprecated

지원 종료 예정입니다. name과 같은 값이므로 name을 쓰세요.

agent

AgentMapping · object

required

agent_id와 agent_version으로 구성된 에이전트 매핑 객체입니다.

Show child attributes

initial_responder_type

enum<string>

required

새 채팅의 최초 응답 담당입니다. agent는 AI 에이전트, external은 고객사 시스템입니다. desk는 vox.ai 상담 화면용 값입니다.

Available options:

agent,

desk,

external

created_at

integer

required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

updated_at

integer

required

리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다.

allow_agent_response

boolean

required

현재 적용되는 AI 사용 허용 값입니다. false이면 새 채팅을 AI가 맡지 않고, AI가 맡고 있던 채팅도 이후 고객 입력에 AI가 답하지 않습니다. 고객 입력은 기록에 남고 사람은 답할 수 있습니다.

channel

string

required

채널 종류입니다. kakao, navertalk, instagram, line, wechat, channeltalk, sms 중 하나이며, 이 값에 따라 details 형식이 정해집니다.

Allowed value: "kakao"

details

KakaoDetails · object

required

채널별 연결 정보입니다.

Show child attributes

curl --request PATCH \
  --url https://client-api.tryvox.co/v3/chat-channels/{chat_channel_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "initial_responder_type": "external",
  "allow_agent_response": false
}
'

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "provider_pending",
  "status_detail": "verify",
  "operation_enabled": true,
  "name": "<string>",
  "display_name": "<string>",
  "agent": {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "agent_version": "current"
  },
  "initial_responder_type": "agent",
  "created_at": 123,
  "updated_at": 123,
  "allow_agent_response": true,
  "channel": "kakao",
  "details": {
    "search_id": "<string>",
    "channel_key": "<string>",
    "sender_key": "<string>",
    "category_code": "<string>",
    "kakao_status": "normal",
    "last_received_at": 123,
    "last_error": {
      "code": "<string>",
      "message": "<string>"
    },
    "link_url": "<string>"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "field": "name",
      "reason": "must not be blank"
    }
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "details": {}
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Permission denied.",
    "details": {}
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Resource not found.",
    "details": {
      "resource": "agent"
    }
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "The requested operation conflicts with current state.",
    "details": {
      "current_status": "draft"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests.",
    "details": {
      "limit": 10,
      "window_seconds": 1,
      "scope": "user"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error.",
    "details": {}
  }
}

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable.",
    "details": {}
  }
}

통화

상담사 통화

에이전트

에이전트 버전

도구

지식 베이스

메뉴얼

평가

모델

스키마

보유 전화번호

전화번호 자원

발신표기번호

차단 번호

대량 발신

시트

위젯

문자

대량 문자 발신

파일

고객

고객 속성 정의

메모리

알림

워크스페이스

워크스페이스 API 키

워크스페이스 인증

Authorizations

Path Parameters

Body

Response