채널

채널 생성

메신저 채널 하나를 만듭니다. 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로 거절합니다.

POST

chat-channels

curl --request POST \
  --url https://client-api.tryvox.co/v3/chat-channels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "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
}

Authorizations

Authorization

string

header

required

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

Body

application/json

만들 채널의 종류와 그 채널의 연결 정보입니다.

name

string

required

대시보드에 표시할 채널 이름입니다. 양끝 공백은 제거하고 제어 문자는 거절합니다.

Required string length: 1 - 255

agent

AgentMapping · object

required

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

Show child attributes

channel

string

required

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

Allowed value: "kakao"

params

인증번호로 등록 · object

required

「인증번호로 등록」의 값(search_id, channel_url, category_code, phone_number, verification_code) 또는 「발신프로필 키로 등록」의 값(sender_key) 중 하나입니다.

인증번호로 등록
발신프로필 키로 등록

Show child attributes

display_name

string | null

deprecated

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

Required string length: 1 - 255

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가 아니어야 합니다.

Response

성공 응답

chat_channel

카카오 · object

required

만든 채널입니다.

Show child attributes

verification

네이버톡톡 · object | null

required

네이버톡톡 채널을 만들었으면 확인 코드 정보이고, 다른 채널은 null입니다.

Show child attributes

curl --request POST \
  --url https://client-api.tryvox.co/v3/chat-channels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
  }
}
'

{
  "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
}

통화

상담사 통화

에이전트

에이전트 버전

도구

지식 베이스

메뉴얼

평가

모델

스키마

보유 전화번호

전화번호 자원

발신표기번호

차단 번호

대량 발신

시트

위젯

문자

대량 문자 발신

파일

고객

고객 속성 정의

메모리

알림

워크스페이스

워크스페이스 API 키

워크스페이스 인증

채널 생성

Authorizations

Body

Response