카카오 비즈메시지(공통)

카카오 비즈메시지 공통 API는 알림톡, 브랜드메시지, 상담톡에서 함께 사용하는 발신프로필과 운영 상태를 조회하거나 관리하는 API입니다.

채널 인증 및 발신프로필 등록

API 키로 카카오 채널 인증 토큰을 요청하고, 인증된 토큰으로 발신프로필을 등록하거나 uuid·senderKey로 채널 정보를 조회합니다.

카카오 채널 인증 토큰 요청

발신프로필 등록을 위한 카카오톡 채널 인증 토큰을 요청하는 API입니다. 입력한 전화번호에 연결된 카카오톡이 카카오톡 채널을 차단하지 않은 경우 인증 토큰이 발송되며, 발송된 토큰은 발신프로필 등록 시 사용됩니다. 인증받은 토큰은 7일 동안 비즈메시지 센터 서버에 보관됩니다.

POST/api/comm/v1/account/kakao/sender/token

발신프로필 등록을 위한 카카오톡 채널 인증 토큰을 요청합니다. 입력한 전화번호에 연결된 카카오톡이 채널을 차단하지 않은 경우 인증 토큰이 발송되며, 발송된 토큰은 발신프로필 등록 시 사용됩니다. 인증받은 토큰은 7일 동안 비즈메시지 센터 서버에 보관됩니다.

Body Parameters

yellowId

필수String

카카오톡 채널 아이디입니다. (ex: @bizgo).

phoneNumber

필수String

카카오톡 채널 알림받는 관리자 전화번호입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/account/kakao/sender/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: {ApiKey}" \
  -d '{
  "yellowId": "{yellowId}",
  "phoneNumber": "{phoneNumber}"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "infobankTrId":"M-260724133159324PRD25892",
    "authResult":"SUCCESS"
  },
  "data": {
    "code":"A000",
    "result":"SUCCESS",
    "resultMsg":"요청 성공"
  }
}

인증 토큰으로 발신프로필 등록

카카오톡 채널을 발신프로필로 신규 등록합니다.

카카오비즈니스 파트너센터에서 비즈니스 인증을 받은 카카오톡 채널이 필요하며, 프로필이 activated 상태이고 운영자에 의해 차단되지 않은 상태여야 합니다. 카카오톡 채널 인증 토큰 요청으로 받은 토큰과 토큰을 요청했던 전화번호로 발신프로필 등록을 요청합니다. 사용할 수 있는 카테고리 코드는 발신프로필 카테고리 전체 조회로 확인할 수 있습니다.

요청하는 카카오톡 채널이 다른 허브파트너의 요청으로 이미 등록되어 있는 경우, 이전에 등록된 발신프로필의 카테고리 코드로 등록됩니다. 브랜드메시지를 이용하는 발신프로필은 무료수신거부용 전화번호(인증번호)를 설정할 수 있습니다. (메시지 발송의 타겟팅 M, N 사용 시 필수)

POST/api/comm/v1/account/kakao/sender

카카오톡 채널을 발신프로필로 신규 등록합니다. 카카오비즈니스 파트너센터에서 비즈니스 인증을 받고, 프로필이 activated 상태이며 운영자에 의해 차단되지 않은 채널이 필요합니다. 인증 토큰 요청으로 받은 토큰과 요청했던 전화번호로 등록을 요청합니다.

Header Parameters

token

필수String

채널 인증 토큰 값입니다.

phoneNumber

필수String

관리자 전화번호입니다.

Body Parameters

yellowId

필수String

등록할 카카오톡 채널입니다.

categoryCode

필수String

카테고리 코드(11자리 숫자)입니다.

unsubscribePhoneNumber

String

무료수신거부 전화번호입니다.

unsubscribeAuthNumber

String

무료수신거부 인증번호입니다. (ex: 12345).

bizchat

Boolean

(상담톡 전용) 상담톡 사용 여부입니다.

committalCompanyName

String

(상담톡 전용) 상담 내용 위탁사명입니다.

channelKey

String

메시지 발송 결과 수신 채널입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

kakao

Object

카카오 응답 영역입니다.

senderProfile

Object

발신프로필 정보입니다.

profileStatus

String

카카오톡 채널 상태입니다.

brandMessage

Boolean

브랜드 메시지 타겟팅 사용 여부입니다.

profileSpamLevel

String

카카오톡 채널 스팸 상태입니다.

profileMessageSpamLevel

String

카카오톡 메시지 스팸 상태입니다.

요청 예시

curl -X POST "https://mars.ibapi.kr/api/comm/v1/account/kakao/sender" \
  -H "token: {token}" \
  -H "phoneNumber: {phoneNumber}" \
  -H "Content-Type: application/json" \
  -H "Authorization: {ApiKey}" \
  -d '{
  "yellowId": "{yellowId}",
  "categoryCode": "{categoryCode}",
  "unsubscribePhoneNumber": "{unsubscribePhoneNumber}",
  "unsubscribeAuthNumber": "{unsubscribeAuthNumber}",
  "bizchat": "{bizchat}",
  "committalCompanyName": "{committalCompanyName}",
  "channelKey": "{channelKey}"
}'

응답 예시

{
  "common": {
    "authCode":"A000",
    "infobankTrId":"M-260724133217180PRD26415",
    "authResult":"SUCCESS"
  },
  "data": {
    "code":"A000",
    "result":"SUCCESS",
    "resultMsg":"요청 성공",
    "kakao": {
      "senderProfile": {
        "senderKey":"{senderKey}",
        "uuid":"@bizgo",
        "name":"비즈고",
        "status":"A",
        "block": false,
        "dormant": false,
        "profileStatus":"A",
        "createdAt":"2026-07-24 13:32:17",
        "modifiedAt":"2026-07-24 13:32:18",
        "categoryCode":"00000000001",
        "brandtalk": false,
        "brandMessage": false,
        "channelKey":"base",
        "businessProfile": true,
        "businessType":"BUSINESS",
        "unsubscribePhoneNumber":"080-1111-2222",
        "unsubscribeAuthNumber":"12345",
        "profileSpamLevel":"정상",
        "profileMessageSpamLevel":"정상",
        "clearBlockUrl":"https://bzm.kakao.com/a/bb/ccc"
      }
    }
  }
}

발신프로필 키 또는 uuid로 조회

발신프로필 키(senderKey) 또는 uuid에 해당하는 발신프로필을 조회합니다. senderKey와 uuid 중 하나는 반드시 입력해야 합니다.

GET/api/comm/v1/account/kakao/sender

발신프로필 키(senderKey) 또는 uuid에 해당하는 발신프로필을 조회합니다. senderKey와 uuid 중 하나는 반드시 입력해야 합니다.

Query Parameters

uuid

String

조회할 카카오톡 채널의 uuid입니다.

senderKey

String

조회할 발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

kakao

Object

카카오 응답 영역입니다.

senderProfile

Object

발신프로필 정보입니다.

profileStatus

String

카카오톡 채널 상태입니다.

brandMessage

Boolean

브랜드 메시지 타겟팅 사용 여부입니다.

profileSpamLevel

String

카카오톡 채널 스팸 상태입니다.

profileMessageSpamLevel

String

카카오톡 메시지 스팸 상태입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/account/kakao/sender?uuid={uuid}&senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "infobankTrId":"M-260724105147428PRD87100",
    "authResult":"SUCCESS"
  },
  "data": {
    "code":"A000",
    "result":"SUCCESS",
    "resultMsg":"요청 성공",
    "kakao": {
      "senderProfile": {
        "senderKey":"{senderKey}",
        "uuid":"@bizgo",
        "name":"비즈고",
        "status":"A",
        "block": false,
        "dormant": false,
        "profileStatus":"A",
        "createdAt":"2026-07-21 14:43:28",
        "modifiedAt":"2026-07-22 17:04:34",
        "categoryCode":"01800010001",
        "bizchat": true,
        "brandtalk": false,
        "brandMessage": false,
        "committalCompanyName":"",
        "channelKey":"base",
        "businessProfile": true,
        "businessType":"BUSINESS",
        "unsubscribePhoneNumber":"080-1111-2222",
        "unsubscribeAuthNumber":"12345",
        "profileSpamLevel":"정상",
        "profileMessageSpamLevel":"정상",
        "clearBlockUrl":"https://bzm.kakao.com/a/bb/ccc"
      }
    }
  }
}

발신프로필 관리

발신프로필은 카카오 비즈메시지 발송의 기준 정보입니다. 발신프로필 키를 기준으로 상태를 확인하거나 휴면 상태를 해제할 때 사용합니다.

발신프로필 키로 조회

GET/api/comm/v1/center/kakao/sender

샌드박스로 테스트하기

발신프로필 키를 기준으로 카카오 발신프로필 정보를 조회합니다. 알림톡, 브랜드메시지, 상담톡에서 사용하는 senderKey 상태를 확인할 때 사용합니다.

Query Parameters

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

senderProfile

Object

발신프로필 정보입니다.

status

String

상태값입니다.

profileStatus

String

카카오톡 채널 상태입니다.

profileSpamLevel

String

카카오톡 채널 스팸 상태입니다.

profileMessageSpamLevel

String

카카오톡 메시지 스팸 상태입니다.

요청 예시

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

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "kakao": {
        "senderProfile": {
          "senderKey":"{senderKey}",
          "uuid":"b1a2c3d4-e5f6-7890-abcd-ef1234567890",
          "name":"비즈고",
          "status":"A",
          "block": false,
          "dormant": false,
          "profileStatus":"A",
          "createdAt":"2026-04-24T11:18:45+09:00",
          "modifiedAt":"2026-04-24T11:18:45+09:00",
          "categoryCode":"001",
          "bizchat": true,
          "brandMessage": true,
          "committalCompanyName":"비즈고",
          "channelKey":"_X1x2x3x4x5x6x7x8x9x0",
          "businessProfile": true,
          "unsubscribePhoneNumber":"0801234567",
          "unsubscribeAuthNumber":"0801234",
          "profileSpamLevel":"정상",
          "profileMessageSpamLevel":"정상",
          "clearBlockUrl":"https://pf.kakao.com/_X1x2x3/unblock"
        }
      }
    }
  }
}

발신프로필 휴면 해제

POST/api/comm/v1/center/kakao/sender/recover

샌드박스로 테스트하기

휴면 상태의 발신프로필을 해제합니다. 카카오 비즈메시지 발송 전 발신프로필 상태 복구가 필요한 경우 사용합니다.

Body Parameters

{} JSON

senderKey

필수String

휴면 해제할 발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

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

응답 예시

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

발신프로필 카테고리 관리

카카오 비즈메시지에서 사용하는 발신프로필 카테고리 정보를 조회하는 API입니다. 발신프로필 등록이나 운영 정책 확인 시 함께 참고합니다.

카테고리 전체조회

GET/api/comm/v1/center/kakao/sender/category/list

샌드박스로 테스트하기

발신프로필 등록 시 사용할 수 있는 카카오 비즈메시지 카테고리 목록을 조회합니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

카테고리 상세조회

GET/api/comm/v1/center/kakao/sender/category

샌드박스로 테스트하기

카테고리 코드를 기준으로 카카오 비즈메시지 카테고리 상세 정보를 조회합니다.

Query Parameters

code

필수String

조회할 카테고리 코드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

발신프로필 그룹 관리

발신프로필 그룹은 여러 발신프로필을 묶어서 운영할 때 사용하는 관리 단위입니다. 그룹 소속을 조회하거나 그룹에 발신프로필을 등록·제외할 때 사용합니다.

발신프로필키로 그룹 조회

GET/api/comm/v1/center/kakao/group

샌드박스로 테스트하기

발신프로필 키를 기준으로 연결된 그룹 정보를 조회합니다. senderKey를 생략하면 조회 가능한 그룹 정보를 기준으로 응답합니다.

Query Parameters

senderKey

String

조회 기준 발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

groups

Object Array

발신프로필 그룹 목록입니다.

요청 예시

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

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "kakao": {
        "groups": [
          {
            "groupKey":"{groupKey}",
            "groupName":"기본 그룹"
          }
        ]
      }
    }
  }
}

그룹에 발신프로필 등록

POST/api/comm/v1/center/kakao/group

샌드박스로 테스트하기

발신프로필 그룹에 발신프로필을 등록합니다. 그룹 키와 등록할 발신프로필 키를 함께 전달합니다.

Body Parameters

{} JSON

groupKey

필수String

발신프로필을 등록할 그룹 키입니다.

senderKey

필수String

등록할 발신프로필 키입니다. max: 40

groupName

String

그룹 이름입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

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

응답 예시

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

그룹에 발신프로필 삭제

DELETE/api/comm/v1/center/kakao/group/groupKey/{groupKey}/senderKey/{senderKey}

샌드박스로 테스트하기

발신프로필 그룹에서 특정 발신프로필을 삭제합니다.

Path Parameters

groupKey

필수String

그룹 키입니다.

senderKey

필수String

삭제할 발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

요청 예시

curl -X DELETE "https://mars.ibapi.kr/api/comm/v1/center/kakao/group/groupKey/{groupKey}/senderKey/{senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

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

제재 관리

제재는 카카오 비즈메시지 운영정책 위반, 스팸·어뷰징 의심, 카카오톡 채널 상태 등에 따라 발신프로필이나 템플릿 단위로 메시지 발송이 제한되는 상태입니다. 제재가 적용되면 메시지 발송이 불가하거나 일부 발송 기능이 제한될 수 있으므로, 발송 전 운영 상태를 확인할 때 제재 조회 API를 사용합니다.

발신프로필 제재 조회: 특정 발신프로필에 적용된 제재 정보를 확인합니다.
그룹템플릿 발신프로필 제외 조회: 그룹템플릿에서 특정 발신프로필이 제외 또는 제한된 정보를 확인합니다.
템플릿 제재 조회: 특정 템플릿에 적용된 제재 정보를 확인합니다.

발신프로필 제재 조회

GET/api/comm/v1/center/kakao/abusing/block/sender

샌드박스로 테스트하기

특정 일자의 발신프로필 제재 정보를 조회합니다.

Query Parameters

date

필수String

조회 기준 날짜입니다.

senderKey

필수String

발신프로필 키입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

abusing

Object

제재 정보입니다.

senderKeyType

String

발신프로필 키 타입입니다.

reasonType

String

제재 사유입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/kakao/abusing/block/sender?date={date}&senderKey={senderKey}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "kakao": {
        "abusing": {
          "restrictedAt":"2026-03-05 16:33:17",
          "senderKey":"{senderKey}",
          "templateCode":"{templateCode}",
          "groupKey":"{groupKey}",
          "senderKeyType":"S",
          "reasonType":"BZM"
        }
      }
    }
  }
}

그룹템플릿 발신프로필 제외 조회

GET/api/comm/v1/center/kakao/abusing/block/senderGroup

샌드박스로 테스트하기

그룹템플릿에서 특정 발신프로필이 제외된 제재 정보를 조회합니다.

Query Parameters

date

필수String

조회 기준 날짜입니다.

senderKey

필수String

발신프로필 키입니다.

groupKey

필수String

그룹 발신프로필 키입니다.

templateCode

필수String

템플릿 코드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

abusing

Object

제재 정보입니다.

senderKeyType

String

발신프로필 키 타입입니다.

reasonType

String

제재 사유입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/kakao/abusing/block/senderGroup?date={date}&senderKey={senderKey}&groupKey={groupKey}&templateCode={templateCode}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "kakao": {
        "abusing": {
          "restrictedAt":"2026-03-05 16:33:17",
          "senderKey":"{senderKey}",
          "templateCode":"{templateCode}",
          "groupKey":"{groupKey}",
          "senderKeyType":"S",
          "reasonType":"BZM"
        }
      }
    }
  }
}

템플릿 제재 조회

GET/api/comm/v1/center/kakao/abusing/block/template

샌드박스로 테스트하기

특정 템플릿의 제재 정보를 조회합니다.

Query Parameters

date

필수String

조회 기준 날짜입니다.

senderKey

필수String

발신프로필 키입니다.

templateCode

필수String

템플릿 코드입니다.

Returns

common

Object

공통 응답 영역입니다.

data

Object

서비스 응답 영역입니다.

data

Object

실제 응답 데이터입니다.

kakao

Object

카카오 비즈메시지 응답 데이터입니다.

abusing

Object

제재 정보입니다.

senderKeyType

String

발신프로필 키 타입입니다.

reasonType

String

제재 사유입니다.

요청 예시

curl -X GET "https://mars.ibapi.kr/api/comm/v1/center/kakao/abusing/block/template?date={date}&senderKey={senderKey}&templateCode={templateCode}" \
  -H "Authorization: {ApiKey}"

응답 예시

{
  "common": {
    "authCode":"A000",
    "authResult":"Success",
    "infobankTrId":"Infobank-Tracking-Id"
  },
  "data": {
    "code":"A000",
    "result":"Success",
    "data": {
      "kakao": {
        "abusing": {
          "restrictedAt":"2026-03-05 16:33:17",
          "senderKey":"{senderKey}",
          "templateCode":"{templateCode}",
          "groupKey":"{groupKey}",
          "senderKeyType":"S",
          "reasonType":"CHANNEL"
        }
      }
    }
  }
}