2026.09업데이트

9월 개발자센터 문서·기능 업데이트

카카오 브랜드메시지 카탈로그(FG) 타입이 문서·샌드박스 전반에 반영되고, 상담톡 규격과 파일 업로드 공통 파트가 채워졌습니다.

26.09.11 9월 개발자센터 문서·기능 업데이트

카카오 브랜드메시지 카탈로그(FG) 타입이 문서·샌드박스 전반에 반영되고, 상담톡 규격과 파일 업로드 공통 파트가 채워졌습니다.

카탈로그(FG)가 브랜드메시지 타입에 추가되어, 규격 문서뿐 아니라 카탈로그를 다루는 화면 전체에 함께 반영되었습니다.

카카오 비즈메시지 이미지 업로드 문서와 대조해 어긋나 있던 규격값을 바로잡았습니다.

default: 비율 0.5 고정·최대 500KB → 비율 0.5~1.333·최대 5MB (기존 값은 알림톡 template 규격이었습니다)
wide: 권장 사이즈를 800x600 단일로 정리
wideItemList: 가로 하한 500px → 200px
카탈로그 2종 규격 확정 — catalog 권장 800x800·비율 1, catalog/oddFirst 권장 800x400·가로 500px 이상·비율 0.5, 둘 다 최대 5MB

파일 업로드는 채널과 무관하게 같은 핸들러를 쓰는데 문서에는 file 하나만 적혀 있었습니다. 실제로 받는 선택 파트와 공통 제약을 채웠습니다.

fileKey(최대 64자, 생략 시 서버 자동 생성)와 imageName(생략 시 확장자를 제외한 파일명)을 MMS·RCS·알림톡·브랜드메시지·상담톡 전 채널에 추가
파일명 40자 초과 시 A201이 반환되므로 file 필드 제약에 40자 이하를 명시

요청·수신·조회 3단계 중 일부만 문서화되어 있던 항목들을 채웠습니다.

카카오톡 본인인증: rich 말풍선 타입 KAKAO_CERT와 certExpiry, 수신 웹훅 cert_result 추가
Rich 메시지: 쿠폰 제목 허용 형식 5종, message·description의 줄바꿈 허용 횟수, 버튼 타입별 제약(AL·BF·AC) 정정
웹훅 수신: attachment는 본문이 4,000자를 넘을 때 전체 본문을 담은 txt 파일 URL이라는 점, content는 하위 호환 필드이므로 본문은 contents를 사용해야 한다는 점, 읽음 정보 수신 조건과 수신 순서 미보장 안내 추가

상담톡 요금제 신설: 요금제 선택 시 옴니키가 발급되며 커뮤니케이션 상품 요금제와 함께 보유할 수 있고, 과금은 채널 수와 채팅방 건수 기준이라는 점을 콘솔 가이드에 추가했습니다.
공용템플릿: 콘솔 템플릿 선택 화면에서 제외되어 조회 API만 남았습니다. 변수 치환 결과가 정의된 글자 수를 넘으면 잘라내거나 대체발송으로 넘기지 않고 발송이 실패한다는 점을 경고로 명시했고, 신규 연동은 템플릿 등록을 사용하도록 안내합니다.

080 수신 거부: 080으로 차단된 번호는 콘솔 발송에만 자동 제외되고 API 연동 발송에는 적용되지 않습니다. 목록을 내려받아 발송 시스템에 직접 반영해야 한다는 조치까지 함께 적었습니다.
브랜드메시지 M·N 타겟팅: 고객사 회원 대상 발송에는 브랜드메시지 사용 전환 신청 → 080 무료수신거부 번호 등록 → 발송 대상 확장 신청(카카오 심사) 세 단계가 순서대로 완료되어야 합니다. 콘솔에서 M·N이 비활성인 것과 API가 628을 돌려주는 것은 같은 원인(세 번째 단계 미승인)입니다.

멀티파트 업로드 API에서 파일 행만 보이고 나머지 본문 필드가 렌더되지 않던 문제를 수정했습니다. 상담톡 이미지·파일 업로드는 필수인 senderKey를 보낼 방법이 없어 항상 A502로 실패했습니다.
래퍼 객체를 요구하는 API에 평평한 본문을 보내던 오류를 수정했습니다.

카탈로그(FG)는 규격 페이지에만 있으면 화면마다 타입 목록이 어긋납니다. 가이드·샌드박스·리포트까지 함께 맞춰 어느 경로로 들어와도 같은 타입 목록을 보게 됩니다.
이미지 업로드 규격과 파일 업로드 공통 파트는 값이 어긋나 있으면 발송 직전에 실패로 이어집니다. 실제 서버가 받는 값으로 맞춰 사전 검증이 가능해졌습니다.
080 수신거부와 M·N 타겟팅은 같은 문의가 반복되던 항목입니다. 조건과 조치를 문서에 적어 연동 단계에서 확인할 수 있습니다.

카탈로그(FG)를 발송하려면 아이템 이미지를 catalog 또는 catalog/oddFirst 업로드 API로 먼저 등록하고, 받은 URL을 catalog.list[].imgUrl에 넣으세요. 아이템이 홀수(3·5·7)면 첫 아이템만 2:1, 짝수(4·6)면 전부 1:1입니다.
파일 업로드 시 fileKey를 직접 지정하면 이후 조회·관리가 쉬워집니다. 생략하면 서버가 자동 생성합니다.
API로 발송한다면 080 수신거부 목록을 주기적으로 내려받아 발송 대상에서 직접 제외하세요.
브랜드메시지 M·N 타겟팅이 필요하면 세 단계 신청이 모두 승인되었는지 먼저 확인하세요.