상담톡

상담톡은 카카오톡 채널을 통해 고객과 1:1 상담 메시지를 송수신하고, 상담 세션과 운영 설정을 함께 관리할 수 있는 카카오 비즈메시지 채널입니다.

상담하기

Plain 메시지 발송

POST/api/comm/v1/cstalk/plain

샌드박스로 테스트하기

상담톡 Plain 메시지를 발송합니다. msgType에 따라 TEXT, IMAGE, VIDEO, AUDIO, FILE을 발송할 수 있습니다.

Body Parameters

{}JSON

userKey

필수String

사용자 키입니다.

senderKey

필수String

발신프로필 키입니다.

msgType

필수String

메시지 타입입니다.

message

필수String

사용자에게 전달할 메시지입니다. 최대 1,000자입니다.

attachment

Object

첨부 메시지 객체입니다. IMAGE, VIDEO, AUDIO, FILE 타입에서 사용합니다.

image

Object

이미지 첨부 정보입니다.

imgUrl

필수String

파일 업로드 API로 등록한 이미지 URL입니다.

imgLink

String

이미지 클릭 시 이동할 URL입니다.

file

Object

파일 첨부 정보입니다.

fileUrl

필수String

파일 업로드 API로 등록한 파일 URL입니다.

fileName

String

파일명입니다. FILE 타입 발송 시 필수입니다.

fileSize

String

파일 크기입니다. FILE 타입 발송 시 필수입니다.

ref

String

참조 필드입니다. 최대 200자이며 전송 요청 결과 Webhook에서 함께 반환됩니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/cstalk/plain" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "msgType":"TEXT",
  "message":"상담 안내 메시지입니다.",
  "ref":"client-ref-001"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "msgKey":"20260424104234546POM101182450000",
    "ref":"client-ref-001"
  }
}

Rich 메시지 발송

POST/api/comm/v1/cstalk/rich

샌드박스로 테스트하기

상담톡 Rich 메시지를 발송합니다. TEXT, IMAGE, WIDE, ITEM_LIST, WIDE_ITEM_LIST, CAROUSEL_FEED, PERSONAL 타입을 지원합니다.

Body Parameters

{}JSON

userKey

필수String

사용자 키입니다.

senderKey

필수String

발신프로필 키입니다.

msgType

필수String

메시지 풍선 타입입니다.

message

String

사용자에게 전달할 메시지입니다.

description

String

사용자에게 전달할 부가 메시지입니다.

header

String

헤더입니다.

attachment

Object

메시지 첨부 정보입니다.

image

Object

이미지 요소입니다. IMAGE, WIDE 타입에서 사용하며 image 필드가 필수입니다.

imgUrl

필수String

등록한 이미지 URL입니다. 이미지 업로드 API로 등록한 URL을 사용합니다.

imgLink

String

이미지 클릭 시 이동할 URL입니다. 미설정 시 카카오톡 내 이미지 뷰어를 사용합니다.

buttons

Object Array

버튼 목록입니다. TEXT, IMAGE, ITEM_LIST는 쿠폰 적용 시 최대 4개, 그 외 최대 5개이며 WIDE, WIDE_ITEM_LIST, CAROUSEL_FEED는 최대 2개입니다.

type

필수String

카카오 버튼 타입입니다.

name

필수String

버튼명입니다.

urlMobile

String

모바일 환경에서 버튼 클릭 시 이동할 URL입니다.

urlPc

String

PC 환경에서 버튼 클릭 시 이동할 URL입니다.

schemeIos

String

iOS 환경에서 버튼 클릭 시 실행할 application custom scheme입니다.

schemeAndroid

String

Android 환경에서 버튼 클릭 시 실행할 application custom scheme입니다.

urlTarget

String

WL 타입에서 외부 브라우저로 열려면 out을 입력합니다.

extra

String

봇/상담톡 전환 시 전달할 메타 정보입니다.

chatEvent

String

봇/상담톡 전환 시 연결할 이벤트명입니다.

startType

String

상담 시작 타입입니다.

bizFormKey

String

비즈폼 키입니다. BF 타입에서 사용합니다.

quickReplies

Object Array

바로연결 목록입니다. 최대 10개까지 사용할 수 있습니다.

type

필수String

카카오 바로연결 타입입니다.

name

필수String

바로연결 제목입니다. 최대 14자입니다.

urlPc

String

PC 환경에서 버튼 클릭 시 이동할 URL입니다.

urlMobile

String

모바일 환경에서 버튼 클릭 시 이동할 URL입니다.

schemeIos

String

iOS 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

schemeAndroid

String

Android 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

urlTarget

String

외부 브라우저로 열려면 out을 입력합니다.

extra

String

BK 버튼 발송 또는 상담톡/챗봇 전환 시 전달할 메타 정보입니다.

chatEvent

String

봇 전환 시 연결할 봇 이벤트명입니다.

coupon

Object

메시지 최하단에 노출되는 쿠폰 요소입니다.

title

필수String

쿠폰 이름입니다.

description

필수String

쿠폰 상세 설명입니다. WIDE, WIDE_ITEM_LIST 타입은 최대 18자, 그 외 타입은 최대 12자입니다.

urlPc

String

PC 환경에서 쿠폰 클릭 시 이동할 URL입니다.

urlMobile

String

모바일 환경에서 쿠폰 클릭 시 이동할 URL입니다.

schemeIos

String

iOS 환경에서 쿠폰 클릭 시 실행할 커스텀 스킴입니다.

schemeAndroid

String

Android 환경에서 쿠폰 클릭 시 실행할 커스텀 스킴입니다.

item

Object

아이템 리스트 요소입니다. ITEM_LIST, WIDE_ITEM_LIST 타입에서 item 필드가 필수입니다.

highlight

Object

ITEM_LIST 타입의 아이템 하이라이트 영역입니다.

title

String

하이라이트 제목입니다.

description

필수String

하이라이트 추가 설명입니다.

imgUrl

String

하이라이트 이미지 URL입니다.

list

필수Object Array

아이템 리스트입니다. ITEM_LIST는 최소 2개, 최대 10개이고 WIDE_ITEM_LIST는 최소 3개, 최대 4개입니다.

title

필수String

아이템 제목입니다.

description

String

ITEM_LIST 타입의 아이템 추가 설명입니다.

summary

Object

ITEM_LIST 타입의 아이템 요약 정보입니다.

title

String

요약 정보 제목입니다.

description

String

요약 정보 추가 설명입니다.

carousel

Object

캐러셀 정보입니다. CAROUSEL_FEED 타입에서 필수입니다.

list

Object Array

캐러셀 아이템 리스트입니다. 최소 2개, 최대 10개입니다.

header

String

캐러셀 아이템 제목입니다. CAROUSEL_FEED 타입에서 사용합니다.

message

String

캐러셀 아이템 메시지입니다. CAROUSEL_FEED 타입에서 사용합니다.

attachment

Object

캐러셀 아이템 첨부 정보입니다.

buttons

Object Array

캐러셀 아이템 버튼 목록입니다. 쿠폰을 적용할 경우 최대 4개, 그 외 최대 5개입니다.

type

필수String

카카오 버튼 타입입니다.

name

필수String

카카오 버튼명입니다.

urlMobile

String

모바일 환경에서 버튼 클릭 시 이동할 URL입니다.

urlPc

String

PC 환경에서 버튼 클릭 시 이동할 URL입니다.

schemeIos

String

iOS 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

schemeAndroid

String

Android 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

urlTarget

String

WL 타입에서 외부 브라우저로 열려면 out을 입력합니다.

extra

String

봇/상담톡 전환 시 전달할 메타 정보입니다.

chatEvent

String

봇/상담톡 전환 시 연결할 이벤트명입니다.

startType

String

상담 시작 타입입니다.

bizFormKey

String

비즈폼 키입니다.

image

필수Object

캐러셀 썸네일 이미지입니다.

imgUrl

필수String

등록한 이미지 URL입니다.

imgLink

String

이미지 클릭 시 이동할 URL입니다. 미설정 시 카카오톡 내 이미지 뷰어를 사용합니다.

coupon

Object

캐러셀 최하단에 노출되는 쿠폰 요소입니다.

title

필수String

쿠폰 이름입니다.

description

필수String

쿠폰 상세 설명입니다. WIDE, WIDE_ITEM_LIST, PREMIUM_VIDEO는 18자, 그 외 타입은 12자까지 입력합니다.

urlPc

String

PC 환경에서 쿠폰 클릭 시 이동할 URL입니다.

urlMobile

String

모바일 환경에서 쿠폰 클릭 시 이동할 URL입니다.

schemeAndroid

String

Android 환경에서 쿠폰 클릭 시 실행할 커스텀 스킴입니다.

schemeIos

String

iOS 환경에서 쿠폰 클릭 시 실행할 커스텀 스킴입니다.

tail

Object

캐러셀 더보기 버튼 정보입니다.

urlMobile

필수String

모바일 환경에서 버튼 클릭 시 이동할 URL입니다.

urlPc

String

PC 환경에서 버튼 클릭 시 이동할 URL입니다.

schemeIos

String

iOS 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

schemeAndroid

String

Android 환경에서 버튼 클릭 시 실행할 커스텀 스킴입니다.

autoAnswer

String

시스템 자동 응답 메시지입니다.

lock

Boolean

보안 메시지 여부입니다.

ref

String

참조 필드입니다. 최대 200자이며 전송 요청 결과 Webhook에서 함께 반환됩니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/cstalk/rich" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "msgType":"TEXT",
  "message":"상담 안내 메시지입니다.",
  "attachment": {
    "buttons": [{
      "type":"WL",
      "name":"바로가기",
      "urlMobile":"https://m.example.com",
      "urlPc":"https://www.example.com"
    }]
  },
  "ref":"client-ref-001"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "msgKey":"20260424104234546POM101182450000",
    "ref":"client-ref-001"
  }
}

상담 종료

POST/api/comm/v1/cstalk/end

샌드박스로 테스트하기

현재 열려 있는 상담 세션을 종료합니다.

Body Parameters

{}JSON

userKey

필수String

사용자 키입니다.

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

API 호출 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/cstalk/end" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "msgKey":"20260424104234546POM101182450000"
    },
    "ref":"client-ref-001"
  }
}

상담 종료 및 봇 전환

POST/api/comm/v1/cstalk/endWithBot

샌드박스로 테스트하기

상담 세션을 종료한 뒤 봇 이벤트 말블록을 실행합니다.

Body Parameters

{}JSON

userKey

필수String

사용자 키입니다.

senderKey

필수String

발신프로필 키입니다.

botEvent

String

실행할 봇 이벤트명입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

API 호출 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/cstalk/endWithBot" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "botEvent":"상담종료"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "msgKey":"20260424104234546POM101182450000"
    },
    "ref":"client-ref-001"
  }
}

사용자 수신 차단

POST/api/comm/v1/center/cstalk/profile/user/block

샌드박스로 테스트하기

특정 사용자의 상담톡 수신을 차단합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/profile/user/block" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "userKey":"{userKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

사용자 수신 차단 해제

POST/api/comm/v1/center/cstalk/profile/user/unblock

샌드박스로 테스트하기

차단된 사용자의 상담톡 수신 차단을 해제합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/profile/user/unblock" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "userKey":"{userKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

세션 조회

GET/api/comm/v1/center/cstalk/session

샌드박스로 테스트하기

사용자 키 기준으로 현재 상담 세션 정보를 조회합니다.

Query Parameters

QUERY

userKey

필수String

사용자 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

API 호출 결과 데이터입니다.

session

Object

세션 정보입니다.

startedType

String

세션 시작 타입입니다.

expiredType

String

세션 종료 타입입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/cstalk/session?userKey=userKeySample?userKey={userKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "session": {
        "sessionId": 1,
        "senderKey":"{senderKey}",
        "startedType":"UM",
        "startedAt":"2025-09-24T11:22:08.557",
        "expiredType":"AE",
        "expiredAt":"2025-10-25T10:00:00"
      }
    }
  }
}

상담메시지 수신하기 (Webhook)

Webhook 수신 정책

Webhook은 비즈고 API에서 고객이 등록한 URL로 변경 사항이나 수신 데이터를 전달하는 방식입니다.
상담톡, 메시지 리포트, MO Webhook은 동일하게 HTTP 200과 규격에 맞는 응답을 받아야 정상 처리됩니다.
응답이 없거나 규격과 맞지 않으면 실패로 간주하며, 실패 시 최대 3회까지 재시도합니다.
모든 재시도가 실패하면 해당 Webhook 전달은 실패 처리되며 다시 전달되지 않습니다.
Connect Timeout과 Read Timeout은 각각 5초 기준으로 처리됩니다.
Webhook 서비스 IP와 보안 요건은 방화벽 및 보안 프로토콜을 참고해 주세요.

상담 세션과 사용자 키

상담 세션은 상담원이 고객에게 메시지를 발송하기 위한 필수 조건이며, 세션이 생성된 상태에서만 상담원 메시지를 보낼 수 있습니다.
세션은 카카오톡 사용자의 마지막 메시지 수신 후 30일간 유지되고, 고객 메시지가 수신될 때마다 연장됩니다.
세션 종료 시각은 마지막 메시지 수신 시각 기준 다음 정각으로부터 30일 후로 설정됩니다.
세션은 상담원이 상담 종료/사용자 차단, 사용자의 !종료 입력/채팅방 나가기/채널 차단, 마지막 메시지 수신 후 30일 경과 시 종료됩니다.
userKey는 특정 카카오톡 사용자를 구분하는 키이며 상담톡 메시지 수신 시 함께 전달됩니다.
userKey는 카카오톡 채널별로 유효하므로 같은 사용자라도 채널이 다르면 다른 사용자 키가 사용됩니다.
userKey는 대소문자를 구분하며, 사용자가 카카오톡을 탈퇴 후 재가입하면 다른 키로 변경됩니다.

사용자 메시지 수신

POST{고객 Webhook URL}/cstalk/message

사용자 메시지 수신 Webhook입니다. 등록한 고객 Webhook URL로 사용자가 전송한 메시지 데이터를 전달합니다.

Body Parameters

{}JSON

msgKey

필수String

메시지 키입니다.

userKey

필수String

상담톡 사용자 키입니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

String

요청 타입입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

kakaoTime

String

상담톡 서버에서 메시지를 전달한 일시입니다. 실제 사용자가 입력한 시각은 아닙니다.

contents

Object Array

사용자가 전송한 메시지 데이터 배열입니다. 2026년 1월 이후 content 필드는 제공되지 않으므로 contents를 사용합니다.

url

String

이미지, 파일 등 데이터 경로입니다.

comment

String

사용자가 입력한 문구입니다.

attachment

Object

사용자 메시지가 4,000자를 초과하는 경우 전체 메시지를 txt 파일 URL로 추가 전달하는 영역입니다.

url

String

전체 메시지를 확인할 수 있는 txt 파일 URL입니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/message" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "msgKey":"20260424104234546POM101182450000",
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"TEXT",
  "requestType":"message",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "kakaoTime":"2026-04-24T10:42:35.000+09:00",
  "contents": [{
    "comment":"상담 문의 내용입니다."
  }]
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

사용자 메타 정보 수신

POST{고객 Webhook URL}/cstalk/reference

사용자가 상담 연결을 요청한 시점의 메타 정보를 등록한 고객 Webhook URL로 전달합니다.

Body Parameters

{}JSON

msgKey

필수String

메시지 키입니다.

userKey

필수String

특정 카카오톡 사용자를 구분하는 키입니다. 카카오톡 채널별로 유효하며 대소문자를 구분합니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

필수String

요청 타입입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

kakaoTime

String

상담톡 서버에서 메시지를 전달한 일시입니다. 실제 사용자가 입력한 시각은 아닙니다.

sessionId

String

상담 세션 아이디입니다. 상담 세션이 생성된 상태에서 상담원이 메시지를 발송할 수 있습니다.

reference

Object

고객사에서 설정한 현재 메타 정보입니다.

extra

String

상담 연결 버튼을 통해 전달된 메타 정보입니다.

lastReference

Object

현재 메타 정보가 없는 경우 전달되는 가장 마지막 메타 정보입니다.

extra

String

이전 상담 연결 버튼을 통해 전달된 메타 정보입니다.

bot

String

상담을 어떻게 시작했는지 나타내는 값입니다.

bot_event

String

봇으로 상담 시작 시 전달되는 봇 블록 이벤트 값입니다.

created_at

String

마지막 메타 정보 생성일입니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/reference" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "msgKey":"20260424104234546POM101182450000",
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"REFERENCE",
  "requestType":"reference",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "kakaoTime":"2026-04-24T10:42:35.000+09:00",
  "sessionId":"{sessionId}",
  "reference": {
    "extra":"orderNo=1234"
  },
  "lastReference": {
    "extra":"orderNo=1233",
    "bot":"false",
    "bot_event":" 상담시작",
    "created_at":"2026-04-23T09:30:00.000+09:00"
  }
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

세션 종료 수신

POST{고객 Webhook URL}/cstalk/expired_session

상담 세션이 종료되었을 때 등록한 고객 Webhook URL로 세션 종료 정보를 전달합니다.

Body Parameters

{}JSON

userKey

필수String

상담톡 사용자 키입니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

필수String

요청 타입입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

kakaoTime

String

상담톡 서버에서 메시지를 전달한 일시입니다. 실제 사용자가 입력한 시각은 아닙니다.

sessionId

String

종료된 상담 세션 아이디입니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/expired_session" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"SESSION",
  "requestType":"expired_session",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "kakaoTime":"2026-04-24T10:42:35.000+09:00",
  "sessionId":"{sessionId}"
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

읽음 정보 수신

POST{고객 Webhook URL}/cstalk/seen_info

사용자 읽음 정보를 등록한 고객 Webhook URL로 전달합니다.

Body Parameters

{}JSON

userKey

필수String

상담톡 사용자 키입니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

필수String

요청 타입입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

kakaoTime

String

상담톡 서버에서 메시지를 전달한 일시입니다. 실제 사용자가 입력한 시각은 아닙니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/seen_info" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"SEEN",
  "requestType":"seen_info",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "kakaoTime":"2026-04-24T10:42:35.000+09:00"
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

개인정보 수신

POST{고객 Webhook URL}/cstalk/personal_info

사용자 개인정보 수집 동의 후 전달되는 개인정보를 등록한 고객 Webhook URL로 전달합니다.

Body Parameters

{}JSON

userKey

필수String

상담톡 사용자 키입니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

필수String

요청 타입입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

kakaoTime

String

상담톡 서버에서 메시지를 전달한 일시입니다. 실제 사용자가 입력한 시각은 아닙니다.

sessionId

String

상담 세션 아이디입니다.

personalInfo

Object

사용자가 동의한 개인정보입니다.

phone_number

String

카카오 계정 전화번호입니다.

nickname

String

카카오 프로필 닉네임입니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/personal_info" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"PERSONAL",
  "requestType":"personal_info",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "kakaoTime":"2026-04-24T10:42:35.000+09:00",
  "sessionId":"{sessionId}",
  "personalInfo": {
    "phone_number":"0100000000",
    "nickname":"홍길동"
  }
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

발송 결과 수신

POST{고객 Webhook URL}/cstalk/result

상담톡 메시지 전송 요청 결과를 등록한 고객 Webhook URL로 전달합니다.

Body Parameters

{}JSON

msgKey

필수String

메시지 키입니다.

userKey

필수String

상담톡 사용자 키입니다.

senderKey

필수String

메시지를 수신한 발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

String

메시지 타입입니다.

requestType

필수String

요청 타입입니다. write, end, endwithbot 중 하나입니다.

sendTime

필수String

전송 일시입니다. ISO 8601 형식으로 전달됩니다.

reportTime

필수String

리포트 일시입니다. ISO 8601 형식으로 전달됩니다.

reportCode

String

리포트 코드입니다.

reportText

String

리포트 메시지입니다.

ref

String

요청 시 전달한 참조 필드입니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

Webhook 처리 결과 메시지입니다.

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/result" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "msgKey":"20260424104234546POM101182450000",
  "userKey":"{userKey}",
  "senderKey":"{senderKey}",
  "serviceType":"CSTALK",
  "msgType":"TEXT",
  "requestType":"write",
  "sendTime":"2026-04-24T10:42:34.546+09:00",
  "reportTime":"2026-04-24T10:42:35.120+09:00",
  "reportCode":"A000",
  "reportText":"Success",
  "ref":"client-ref-001"
}'

응답 예시

{
  "code":"A000",
  "result":"Success"
}

파일 업로드

이미지 업로드

POST/api/comm/v1/file/cstalk/image

샌드박스로 테스트하기

상담톡 이미지 파일을 업로드합니다. jpg, png, gif 형식을 지원하며 최대 5MB까지 등록할 수 있습니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 이미지 파일입니다.

senderKey

필수String

카카오 비즈메시지 발신프로필 키입니다.

imageType

String

이미지 타입입니다. Rich 메시지 이미지 업로드 시 rich를 입력합니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

이미지 업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/cstalk/image" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@sample.jpg" \
  -F "senderKey={senderKey}" \
  -F "imageType=rich"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "imgUrl":"https://mud-kage.kakao.com/.../cstalk_image.jpg"
    }
  }
}

파일 업로드

POST/api/comm/v1/file/cstalk

샌드박스로 테스트하기

상담톡 FILE·AUDIO·VIDEO 타입 첨부 파일을 업로드합니다.

Body Parameters

FORM-DATA

file

필수Binary

업로드할 파일 바이너리입니다.

senderKey

필수String

카카오 비즈메시지 발신프로필 키입니다.

fileType

String

파일 타입입니다. file: 일반 파일, audio: 오디오 파일, video: 비디오 파일입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

파일 업로드 결과 데이터입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/file/cstalk" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@sample.pdf" \
  -F "senderKey={senderKey}" \
  -F "fileType=file"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "fileUrl":"https://mud-kage.kakao.com/.../cstalk_file.pdf",
      "fileName":"sample.pdf",
      "size":"102400"
    }
  }
}

채널 관리하기

상담톡 이용 활성화

POST/api/comm/v1/center/cstalk/sender/activate

샌드박스로 테스트하기

상담톡 이용을 활성화합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/sender/activate" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "committalCompany":"비즈고"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

상담톡 이용 비활성화

POST/api/comm/v1/center/cstalk/sender/deactivate

샌드박스로 테스트하기

상담톡 이용을 비활성화합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/sender/deactivate" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "committalCompany":"비즈고"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

채팅 기능 활성화

POST/api/comm/v1/center/cstalk/sender/chat/activate

샌드박스로 테스트하기

카카오톡 채널의 채팅 기능을 활성화합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/sender/chat/activate" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

채팅 기능 비활성화

POST/api/comm/v1/center/cstalk/sender/chat/deactivate

샌드박스로 테스트하기

카카오톡 채널의 채팅 기능을 비활성화합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/sender/chat/deactivate" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

상담시간 조회

GET/api/comm/v1/center/cstalk/consult/time

샌드박스로 테스트하기

상담 운영 시간을 조회합니다.

Query Parameters

QUERY

senderKey

필수String

카카오 비즈메시지 발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

상담톡 응답 데이터입니다.

cstalk

Object

상담톡 데이터 영역입니다.

weekTimeTable

Object Array

요일별 상담 시간 목록입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/cstalk/consult/time?senderKey=%40bizgo" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "cstalk": {
        "weekTimeTable": [{
          "day":"mon",
          "startAt":"0900",
          "endAt":"1800"
        }]
      }
    }
  }
}

상담시간 저장

POST/api/comm/v1/center/cstalk/consult/time

샌드박스로 테스트하기

카카오톡 채널의 상담시간을 저장합니다. 한 번 시간이 등록되면 수정만 가능하며, 상담톡 이용 여부를 해지하면 상담 시간은 삭제됩니다. 카카오톡 채널 홈에 상담시간이 노출되며, 설정된 상담 시간을 확인하려면 채팅 기능이 활성화된 상태여야 합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/consult/time" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "weekTimeTable": [{
      "day":"mon",
      "startAt":"0900",
      "endAt":"1800"
    }]
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

시스템 메시지 조회

GET/api/comm/v1/center/cstalk/system/message

샌드박스로 테스트하기

시스템 메시지 목록을 조회합니다.

Query Parameters

QUERY

senderKey

필수String

카카오 비즈메시지 발신프로필 키입니다.

String

시스템 메시지 ID입니다. 특정 메시지만 조회할 때 입력합니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

시스템 메시지 응답 데이터입니다.

systemMessages

Object Array

시스템 메시지 목록입니다.

messages

Object Array

시스템 메시지 배열입니다.

buttons

Object Array

메시지 하단 버튼 목록입니다.

type

String

시스템 메시지 버튼 링크 타입입니다.

comments

Object Array

검수 결과 및 문의 목록입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/cstalk/system/message?senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "systemMessages": [{
        "id":"7678",
        "name":"상담 시작 안내",
        "status":"A",
        "createdAt":"2025-08-18 16:40:00",
        "modifiedAt":"2025-08-18 16:40:00",
        "inspectStatus":"REG",
        "inspectRequestAt":"2025-08-27 13:16:59",
        "inspectedAt":"",
        "messages": [{
          "messageType":"ST",
          "content":"상담을 시작합니다.",
          "buttons": [{
            "ordering": 1,
            "type":"WL",
            "name":"바로가기",
            "urlMobile":"https://m.example.com",
            "urlPc":"https://www.example.com"
          }]
        }],
        "comments": [{
          "id":"101",
          "content":"검수 요청이 등록되었습니다.",
          "userName":"비즈고",
          "createdAt":"2025-08-27 13:17:02",
          "status":"INQ"
        }]
      }]
    }
  }
}

시스템 메시지 등록

POST/api/comm/v1/center/cstalk/system/message

샌드박스로 테스트하기

시스템 메시지를 등록합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

messages

필수Object Array

시스템 메시지 배열입니다.

messageType

필수String

시스템 메시지 타입입니다.

buttons

필수Object Array

메시지 하단 버튼 목록입니다.

type

필수String

시스템 메시지 버튼 링크 타입입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

시스템 메시지 등록 결과 데이터입니다.

systemMessage

Object

생성된 시스템 메시지 정보입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/system/message" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}",
    "name":"상담 시작 안내",
    "messages": [{
      "messageType":"ST",
      "content":"상담을 시작합니다.",
      "buttons": [{
        "ordering": 1,
        "type":"WL",
        "name":"바로가기",
        "urlMobile":"https://m.example.com",
        "urlPc":"https://www.example.com"
      }]
    }]
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "systemMessage": {
        "id":"7678"
      }
    }
  }
}

시스템 메시지 삭제

DELETE/api/comm/v1/center/cstalk/system/message/senderKey/{senderKey}/id/{id}

샌드박스로 테스트하기

시스템 메시지를 삭제합니다.

Path Parameters

PATH

senderKey

필수String

발신프로필 키입니다.

필수String

삭제할 시스템 메시지 ID입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/cstalk/system/message/senderKey/%40bizgo/id/sysMsgId" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

시스템 메시지 검수 요청

POST/api/comm/v1/center/cstalk/system/message/approval/request

샌드박스로 테스트하기

시스템 메시지 검수를 요청합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/system/message/approval/request" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

시스템 메시지 검수 취소

POST/api/comm/v1/center/cstalk/system/message/approval/cancel

샌드박스로 테스트하기

시스템 메시지 검수 요청을 취소합니다.

Body Parameters

{}JSON

cstalk

필수Object

상담톡 요청 객체입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/center/cstalk/system/message/approval/cancel" \
  -H "Authorization: {ApiKey}" \
  -H "Content-Type: application/json" \
  -d '{
  "cstalk": {
    "senderKey":"{senderKey}"
  }
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success"
  }
}

상담 연결하기

PC/Mobile 페이지에서 상담 연결 버튼을 통해 상담을 요청할 수 있습니다.

PC에서 상담 연결 버튼을 통해 메타 정보를 전달하는 경우 요청 페이지는 새창 또는 팝업 형태로 호출해야 하며, 팝업의 최소 권장 사이즈는 1024 x 800입니다.

상담 연결 버튼 클릭 시 파트너사 페이지를 거쳐 카카오 로그인 페이지로 이동하는 경우, 파트너사 페이지 내에 아래 스크립트를 포함하면 권장 사이즈로 팝업창이 노출됩니다.

<script src="https://bizmessage.kakao.com/chat/includeScript"></script>

봇과 상담톡을 동시에 이용하는 프로필은 bot 파라미터를 이용해 봇 또는 상담톡으로 연결 방식을 제어할 수 있습니다.

버튼 연결 (POST)

POSThttps://bizmessage.kakao.com/chat/open

샌드박스로 테스트하기

카카오 상담 연결 URL을 POST 방식으로 직접 호출합니다. Content-Type은 application/x-www-form-urlencoded를 사용합니다.

Body Parameters

FORM-URLENCODED

uuid

필수String(40)

발신프로필키입니다. 카카오톡 채널 @아이디가 아니므로 주의해 주세요.

extra

String(1000)

상담톡 또는 봇 전환 시 사용자에게 전달할 메타 데이터입니다.

bot

String(5)

봇 연결은 true, 상담원 연결은 false(기본값), 유지 중인 세션 연결은 auto를 입력합니다.

event

String(100)

사용자가 봇으로 전환될 때 발생할 이벤트명입니다.

app_open_type

String

앱 실행 방식입니다. direct 또는 modal을 입력합니다.

Returns

redirect

Redirect

카카오톡 상담 연결 화면으로 이동합니다. 별도의 비즈고 API JSON 응답이 아닙니다.

요청 예시

curl -X POST "https://bizmessage.kakao.com/chat/open" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "uuid={uuid}&extra={extra}&bot=false&event={event}&app_open_type=direct"

응답 예시

카카오 상담 연결 URL 호출 후 카카오톡 상담 화면으로 이동합니다.
비즈고 API JSON 응답이 아니라 카카오 URL 이동/응답으로 처리됩니다.

버튼 연결 (GET)

GEThttps://bizmessage.kakao.com/chat/open/{uuid}

샌드박스로 테스트하기

카카오 상담 연결 URL을 GET 방식으로 직접 호출합니다. uuid는 경로에 포함하고 나머지 값은 Query Parameter로 전달합니다.

Query Parameters

QUERY

uuid

필수String(40)

발신프로필키입니다. Path Parameter로 전달하며, 카카오톡 채널 @아이디가 아니므로 주의해 주세요.

extra

String(50)

상담톡 또는 봇 전환 시 사용자에게 전달할 메타 데이터입니다.

bot

String(5)

봇 연결은 true, 상담원 연결은 false(기본값), 유지 중인 세션 연결은 auto를 입력합니다.

event

String(100)

사용자가 봇으로 전환될 때 발생할 이벤트명입니다.

app_open_type

String

앱 실행 방식입니다. direct 또는 modal을 입력합니다.

Returns

redirect

Redirect

카카오톡 상담 연결 화면으로 이동합니다. 별도의 비즈고 API JSON 응답이 아닙니다.

요청 예시

curl -X GET "https://bizmessage.kakao.com/chat/open/{uuid}?extra={extra}&bot=false&event={event}&app_open_type=direct"

응답 예시

카카오 상담 연결 URL 호출 후 카카오톡 상담 화면으로 이동합니다.
비즈고 API JSON 응답이 아니라 카카오 URL 이동/응답으로 처리됩니다.