상담톡

상담톡은 카카오톡 채널을 통해 고객과 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

상품 응답 영역입니다.

msgKey

String

메시지 키입니다.

요청 예시

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

샌드박스로 테스트하기

KAKAO_CERT(본인인증)는 채널 화이트리스트 신청이 필요합니다

msgType을 KAKAO_CERT로 발송하려면 해당 카카오톡 채널이 본인인증 화이트리스트에 사전 등록되어 있어야 합니다.
신청은 이용문의 또는 영업 담당자를 통해 진행합니다.
신청 시 CI(연계정보) 활용 여부에 대한 증적 자료와 채널 정보를 함께 제출해야 합니다.

상담톡 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

쿠폰 이름입니다. 아래 5가지 형식 중 하나여야 합니다.

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

보안 메시지 여부입니다.

certExpiry

Integer

본인인증 유효 시간(분)입니다. msgType이 KAKAO_CERT일 때 필수입니다.

ref

String

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

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

msgKey

String

메시지 키입니다.

요청 예시

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 호출 결과 데이터입니다.

msgKey

String

메시지 키입니다.

요청 예시

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 호출 결과 데이터입니다.

msgKey

String

메시지 키입니다.

요청 예시

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

카카오톡 인증 상태 조회

GET/api/comm/v1/center/cstalk/cert/status

샌드박스로 테스트하기

인증 트랜잭션 ID로 고객의 카카오톡 인증(전자서명) 진행 상태를 조회합니다.

Query Parameters

QUERY

certTxId

필수String

인증 트랜잭션 ID입니다. 카카오가 인증 요청 시 발급합니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

상품 응답 영역입니다.

data

Object

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

cert

Object

카카오톡 인증 정보입니다.

signStatus

String

서명 상태입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/cstalk/cert/status?certTxId=certTxIdSample" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"header-value-X-Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "cert": {
        "txId":"{certTxId}",
        "sessionId": 1,
        "signStatus":"COMPLETED",
        "createdAt":"2026-09-10T10:00:00",
        "viewedAt":"2026-09-10T10:00:30",
        "completedAt":"2026-09-10T10:01:12",
        "expiredAt":"2026-09-10T10:10:00"
      }
    }
  }
}

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

Webhook 수신 정책

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

Webhook 공통 필드

msgKey는 7종 모두에 실리지만 의미가 다릅니다. result의 msgKey는 발송 API 응답으로 받은 그 값이고, 수신 6종의 msgKey는 이벤트마다 새로 발급된 값이라 발송 건과 대응하지 않습니다.
세션 연결은 sessionId로, 발송 건 대조는 result의 msgKey·ref로 하세요.
sendTime은 비즈고가 이벤트를 수신한 시각, reportTime은 비즈고가 Webhook을 전송한 시각입니다.
kakaoTime은 카카오가 전달한 시각으로, 상담톡 서버 기준이며 사용자가 메시지를 입력한 시각이 아닙니다.
시각 형식은 yyyy-MM-dd'T'HH:mm:ss.SSS+09:00(KST)이며, 원본 값이 없으면 빈 문자열로 전달됩니다.
값이 없는 필드는 본문에서 아예 빠지므로 requestType마다 전달되는 키 집합이 다릅니다.
재시도 시 같은 이벤트가 다시 전달될 수 있으므로 msgKey 기준으로 멱등 처리해 주세요.
수신 순서는 보장되지 않습니다. 네트워크 상황이나 데이터 크기에 따라 이벤트가 발생 순서와 다르게 도착할 수 있습니다.

상담 세션과 사용자 키

상담 세션은 상담원이 고객에게 메시지를 발송하기 위한 필수 조건이며, 세션이 생성된 상태에서만 상담원 메시지를 보낼 수 있습니다.
세션은 카카오톡 사용자의 마지막 메시지 수신 후 30일간 유지되고, 고객 메시지가 수신될 때마다 연장됩니다.
세션 종료 시각은 마지막 메시지 수신 시각 기준 다음 정각으로부터 30일 후로 설정됩니다.
세션은 상담원이 상담 종료/사용자 차단, 사용자의 !종료 입력/채팅방 나가기/채널 차단, 마지막 메시지 수신 후 30일 경과 시 종료됩니다.
userKey는 특정 카카오톡 사용자를 구분하는 키이며 상담톡 메시지 수신 시 함께 전달됩니다.
userKey는 1~20자여야 하며, 비어 있거나 20자를 넘으면 A507이 반환됩니다.
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

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

sessionId

String

상담 세션 ID입니다.

content

String

하위 호환을 위해 유지되는 본문 필드입니다.

extra

String

카카오가 전달한 부가 정보입니다.

contents

Object Array

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

url

String

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

comment

String

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

attachment

String

사용자 메시지가 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

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

appUserId

Number

카카오톡 앱 사용자 ID입니다.

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

msgKey

필수String

메시지 키입니다.

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 '{
  "msgKey":"20260424104234546POM101182450000",
  "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

읽음 정보 수신 조건

상담 세션이 연결된 상태에서만 수신되며, 발송 후 최대 24시간까지만 확인할 수 있습니다.
실시간이 아니라 지연이 있을 수 있습니다.
이 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

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

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 '{
  "msgKey":"20260424104234546POM101182450000",
  "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

msgKey

필수String

메시지 키입니다.

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 '{
  "msgKey":"20260424104234546POM101182450000",
  "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/cert_result

certResult는 저장하지 마세요

certResult는 AES256/CTR/NoPadding + Base64로 암호화된 본인인증 결과이며, 복호화하면 이름·전화번호·생년월일·성별·내외국인·CI가 들어 있습니다.
카카오 정책상 인증정보는 시스템에 저장하지 않고 사용자를 식별한 즉시 파기해야 합니다.
로그·APM·에러 리포트에 본문이 남지 않도록 수신 측에서도 마스킹 처리해 주세요.
복호화 키는 카카오가 이메일로 별도 전달합니다. 인증정보와 복호화 키 모두 Base64로 인코딩되어 있습니다.
인증 결과는 상담 세션 상태와 관계없이 전달되며, ci는 취급 검증을 마친 발신프로필에만 제공됩니다.

본인인증 결과 수신 Webhook입니다. KAKAO_CERT 말풍선으로 요청한 카카오톡 본인인증(전자서명)이 완료되면 등록된 Webhook URL로 결과가 전달됩니다.

Body Parameters

{}JSON

msgKey

필수String

메시지 키입니다.

userKey

필수String

사용자 키입니다.

senderKey

필수String

발신프로필 키입니다.

serviceType

필수String

서비스 타입입니다.

msgType

필수String

메시지 타입입니다.

requestType

필수String

요청 타입입니다. cert_result로 전달됩니다.

sendTime

필수String

수신 일시입니다. (ISO 8601, yyyy-MM-dd'T'HH:mm:ss.SSS).

reportTime

필수String

리포트 일시입니다. (ISO 8601, yyyy-MM-dd'T'HH:mm:ss.SSS).

kakaoTime

String

카카오 서버 수신 일시입니다.

sessionId

String

상담 세션 ID입니다.

certTxId

필수String

인증 트랜잭션 ID입니다. 인증 상태 조회 API의 certTxId와 같은 값입니다.

certResult

필수String

암호화된 본인인증 결과입니다. 복호화하면 이름·전화번호·생년월일·성별·내외국인·CI가 들어 있습니다.

Returns

code

String

Webhook 처리 결과 코드입니다.

result

String

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

요청 예시

curl -X POST "{고객 Webhook URL}/cstalk/cert_result" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "msgKey":"20260424104234546POM101182450000",
    "userKey":"{userKey}",
    "senderKey":"{senderKey}",
    "serviceType":"CSTALK",
    "msgType":"KAKAO_CERT",
    "requestType":"cert_result",
    "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}",
    "certTxId":"{certTxId}",
    "certResult":"amI1a0dQTVVRSm1YTk9BNW9tYWpXdz09"
  }'

응답 예시

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

리포트 메시지입니다.

kakaoResCreatedAt

String

카카오 응답 생성 일시입니다. (ISO 8601).

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

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

fileKey

String

업로드 파일을 식별하는 키입니다. 생략하면 서버가 자동으로 생성합니다.

imageName

String

업로드 파일의 이름입니다. 생략하면 확장자를 제외한 파일명을 사용합니다.

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

샌드박스로 테스트하기

환경에 따라 업로드 용량 상한이 다릅니다

운영 환경은 최대 300MB 까지 업로드할 수 있지만, 샌드박스 환경은 10MB 까지만 가능합니다.
10MB 를 넘는 파일은 샌드박스에서 테스트할 수 없으므로 운영 환경에서 확인하세요.

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

Body Parameters

FORM-DATA

file

필수Binary

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

fileKey

String

업로드 파일을 식별하는 키입니다. 생략하면 서버가 자동으로 생성합니다.

imageName

String

업로드 파일의 이름입니다. 생략하면 확장자를 제외한 파일명을 사용합니다.

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={senderKey}" \
  -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입니다.

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

HTML

<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 이동/응답으로 처리됩니다.