이해하기

이 문서는 카카오톡 채널 API를 소개합니다.

기능 소개

카카오톡 채널 API는 카카오톡의 비즈니스 홈인 카카오톡 채널을 보다 잘 활용할 수 있도록 지원합니다. 사용자가 서비스에서 간편하게 카카오톡 채널 추가 페이지로 이동하거나 1:1 채팅을 시작할 수 있도록 연결 페이지를 제공합니다.

카카오톡 채널 API는 아래 기능을 제공합니다.

• 카카오톡 채널 추가: Kakao SDK를 활용한 간편한 채널 추가 요청
• 카카오톡 채널 고객 관리: 채널 관리자의 편리한 고객 그룹 관리 지원
• 카카오톡 채널 관계 관리: 채널 친구 관계 확인 및 알림 수신

카카오톡 채널 API를 사용하려면 앱에 카카오톡 채널이 연결되어 있어야 하고, 사용자의 [카카오톡 채널 추가 상태] 동의항목에 대한 동의가 필요합니다. 카카오톡 채널 연결방법은 앱에 카카오톡 채널 연결을, 동의항목 설정 방법은 카카오톡 채널 동의항목 설정을 참고합니다.

친구 그룹 생성 및 메시지 발송 과정

참고: 카카오톡 채널 프로필 ID 확인 방법

[카카오톡 채널 관리자센터] > [관리] > [상세설정]에서 카카오톡 채널의 채널 URL을 확인할 수 있습니다. 채널 URL에서 https://pf.kakao.com/ 부분을 제외한 뒷자리 값이 해당 카카오톡 채널의 프로필 ID입니다. 아래 예시를 참고합니다.

• 채널 URL: https://pf.kakao.com/_ZeUTxl
• 카카오톡 채널 프로필 ID: _ZeUTxl

카카오톡 채널 추가

Kakao SDK를 활용한 카카오톡 채널 추가 요청 방법에 대해 안내합니다. 사용자가 서비스의 카카오톡 채널을 추가하면, 서비스는 이를 다양한 소식과 기능을 제공하는 창구로 활용할 수 있습니다.

지원하는 방식

Kakao SDK는 서비스 환경에 따라 선택 가능한 두 가지 카카오톡 채널 추가 방식을 제공합니다. 아래 각 항목에서 방식별 자세한 내용을 확인할 수 있습니다.

구현 방식	메서드명	서비스 페이지 유지	결과 확인
카카오톡 채널 간편 추가(권장)	followChannel()	서비스 페이지에서 채널 추가 화면을 바로 노출	결과를 요청의 응답으로 확인 가능
카카오톡 채널 추가	addChannel()	연결 페이지로 카카오톡 내 채널 페이지 이동 여부 확인, 사용자 동의 시 페이지 이탈 후 채널 추가	카카오톡 채널 관계 조회 요청으로 별도 확인 필요

카카오톡 채널 간편 추가

카카오톡 채널 간편 추가(followChannel())는 서비스 페이지에서 바로 카카오톡 채널 추가를 요청하고, 응답으로 결과를 확인할 수 있는 기능입니다. 서비스는 사용자의 카카오톡 채널 추가 결과를 응답으로 제공받아 상황에 맞는 기능을 간편하게 제공할 수 있습니다.

만약 카카오톡 채널 추가 불가능 상태의 사용자에게 요청한 경우, 각 상태에 따른 안내 화면이 표시됩니다.

아래 주요 표시 화면과 카카오 로그인 사용 여부에 따른 카카오톡 채널 추가 요청 방법을 참고합니다.

카카오 로그인 사용 서비스

카카오 로그인을 사용하는 서비스 화면에서 사용자가 카카오톡 채널 추가 버튼 또는 배너 선택 시, 사용자의 카카오 로그인 여부에 따라 카카오톡 채널 추가 요청을 처리해야 합니다.

로그인한 사용자

1. 서비스에서 followChannel() 요청
2. 카카오톡 채널 추가 화면 표시됨
3. 사용자의 카카오톡 채널 추가 여부를 응답으로 수신

로그인하지 않은 사용자

1. 서비스에서 카카오 로그인 요청
2. 카카오 로그인 동의 화면 표시됨
   • 사용자는 카카오 로그인 동의 화면에서 카카오톡 채널 추가 가능
3. 사용자 로그인 후 카카오톡 채널 관계 조회로 사용자의 카카오톡 채널 추가 정보 확인
   • 추가한 경우: 상황에 맞는 기능 제공(예: 카카오톡 채널 추가 사용자를 위한 서비스 화면 제공 등)
   • 추가하지 않은 경우: 로그인한 사용자 과정으로 카카오톡 채널 추가 요청

카카오 로그인 미사용 서비스

카카오 로그인을 사용하지 않는 서비스 화면에서 사용자가 카카오톡 채널 추가 버튼 또는 배너 선택 시, 아래 과정으로 카카오톡 채널 추가 요청을 처리합니다.

1. 서비스에서 followChannel() 요청
2. 카카오계정 로그인 화면 표시됨
3. 사용자 로그인 후 카카오톡 채널 추가 화면 표시됨
4. 사용자의 카카오톡 채널 추가 여부를 응답으로 수신

카카오톡 채널 추가

카카오톡 채널 추가(addChannel())는 카카오톡 채널 추가 버튼이 포함된 연결 페이지(Bridge page)를 제공하는 기능입니다. 연결 페이지에서 사용자가 [채널 추가]를 선택하면 커스텀 URL 스킴(Custom URL Scheme)으로 카카오톡을 실행하고, 해당 카카오톡 채널 화면으로 이동합니다. 사용자의 카카오톡 채널 추가 여부를 확인하려면 카카오톡 채널 관계 조회를 별도로 요청해 확인해야 합니다.

서비스 페이지 내에서 바로 카카오톡 채널 추가를 요청할 수 있고, 별도의 확인 절차 없이 응답으로 결과를 확인할 수 있는 카카오톡 채널 간편 추가(followChannel()) 사용을 권장합니다.

앱에 카카오톡 채널 연결

카카오디벨로퍼스 앱과 카카오톡 채널을 서로 연결하는 방법에 대해 안내합니다. 연결 해제 방법은 연결된 카카오톡 채널을 참고합니다.

카카오톡 채널은 같은 사업자가 소유한 앱만 연결 가능합니다. 동일한 사업자 정보를 앱과 카카오톡 채널에 등록해 비즈 앱과 비즈니스 채널로 각각 전환해야 합니다. 비즈 앱과 비즈니스 채널 전환 후, 추가 기능 신청으로 앱에 카카오톡 채널을 연결할 수 있습니다. 아래 단계별 내용을 확인합니다.

1. 신청 자격 확인

앱의 오너(Owner) 또는 에디터(Editor) 멤버 계정으로 로그인 후, 앱 관리 페이지의 [앱] > [추가 기능 신청]에서 [신청 자격 확인]을 누릅니다. 신청 자격의 내용을 확인한 뒤 동의해야 합니다.

2. 카카오톡 채널 연결 신청

[앱] > [추가 기능 신청] > [추가 기능]에서 [카카오톡 채널 연결] 항목의 [신청]을 선택하면 연결 가능 카카오톡 채널 목록이 표시됩니다. 원하는 채널을 선택하면 앱과 카카오톡 채널이 연결됩니다.

연결한 채널은 연결된 카카오톡 채널에서 확인하고 필요한 경우 연결 해제할 수 있습니다.

참고: 연결 가능 카카오톡 채널

아래 조건을 만족하는 카카오톡 채널을 앱과 연결할 수 있습니다.

• 마스터 또는 매니저 권한을 갖고 있는 채널
• 사업자 정보를 등록해 비즈니스 채널로 전환된 채널
  • 톡스토어 등 카카오 서비스를 사용하고 있어 사업자 정보가 등록되어 있지 않은 비즈니스 채널의 경우 카카오톡 채널 관리자센터의 [관리] > [비즈니스 채널 신청]에서 등록 필요
• 앱과 동일한 사업자 정보가 등록된 채널
• 앱과 연결되지 않은 채널

참고: 비즈니스 채널 신청 방법

비즈니스 채널은 서비스를 소유한 사업자 정보를 등록한 카카오톡 채널입니다. 카카오톡 채널을 비즈니스 채널로 전환 신청하는 방법은 아래 안내를 참고합니다.

1. 카카오톡 채널 관리자센터에서 서비스의 카카오톡 채널 관리자인 카카오계정으로 로그인합니다. 서비스의 카카오톡 채널이 없다면 카카오톡 채널 관리자 센터에서 생성할 수 있습니다.
2. 비즈니스 채널로 전환할 카카오톡 채널을 선택한 후, [관리] > [비즈니스 채널 신청]에서 [신청하기]를 눌러 비즈니스 채널 전환을 신청합니다. 업종에 따라 신청 가이드가 상이하므로 비즈니스 채널 심사 가이드를 반드시 확인하고 신청해야 합니다. 비즈니스 채널 심사는 영업일 기준 약 3~5일이 소요됩니다. 문의 사항은 고객센터로 문의합니다.

참고: 개발자용 카카오톡 채널

서비스에 영향을 미치지 않는 테스트용 카카오톡 채널이 필요한 경우, 카카오톡 채널 관리자센터에서 [개발자용 채널 만들기]를 눌러 개발자용 채널을 생성할 수 있습니다. 최소 1개의 비즈니스 채널이 있어야 해당 버튼이 노출됩니다. 개발자용 채널은 테스트 앱에 연결하고 대표 채널로 설정하여 사용합니다.

참고: 카카오톡 채널 동의항목 설정

앱에 카카오톡 채널 연결 후, 카카오톡 채널 관계 조회 API를 사용하려면 동의항목을 설정하고 사용자의 동의를 받아야 합니다. 앱 관리 페이지의 [앱] > [카카오 로그인] > [동의항목]에서 [카카오톡 채널 추가 상태 및 내역(plusfriends)]을 [필수 동의] 또는 [선택 동의] 동의 단계로 설정합니다. 해당 동의항목은 앱과 연결된 카카오톡 채널이 있는 경우에만 설정 가능합니다.

카카오톡 채널 고객 관리

카카오톡 채널 관리자센터에서 제공하는 카카오톡 채널 고객파일 등록 및 관리 기능을 아래 API로 이용할 수 있습니다.

• 고객 관리: 고객파일 등록
• 고객 관리: 고객파일 조회
• 고객 관리: 고객파일에 사용자 추가
• 고객 관리: 고객파일의 사용자 삭제

카카오톡 채널 고객 관리 API를 사용해 카카오 로그인 또는 카카오싱크 간편가입으로 확보한 사용자 정보를 기반으로 고객파일을 업로드하면, 카카오톡 채널 관리자센터에서 조건별 친구 그룹을 만들어 세분화된 타깃 메시지를 발송할 수 있습니다. 자세한 내용은 카카오톡 채널 관리자센터 공지사항을 참고합니다.

카카오톡 채널 고객 관리 API를 사용하려면 먼저 관련 정책에 동의해야 합니다. 동의 방법은 고객 관리 API 정책 동의를 확인합니다.

카카오톡 채널 고객 관리 API는 서버에서만 호출해야 합니다. 개발 문서는 REST API에서 확인할 수 있습니다.

카카오톡 채널 관계 관리

카카오톡 채널 관계 조회

카카오톡 채널 관계 조회 API로 각 사용자의 카카오톡 채널 추가 상태를 확인할 수 있습니다. 사용자의 카카오톡 채널 추가 상태에 따라 카카오톡 채널과 친구가 아닌 사용자에게 친구 추가를 유도하거나 고객파일에서 사용자를 제외할 수 있습니다. 아래 개발 가이드를 참고합니다.

• REST API
• JavaScript
• Android
• iOS

카카오톡 채널 웹훅

카카오톡 채널 웹훅을 사용하면 사용자가 서비스와 연결된 카카오톡 채널을 추가 또는 차단했을 때 알림을 받을 수 있습니다.

앱과 연결된 카카오톡 채널을 추가한 사용자들에게 카카오톡 채널 메시지를 보낼 때, 현재 해당 카카오톡 채널을 차단한 사용자나 별도로 카카오톡에서 친구 추가한 사용자는 자체적으로 파악이 어려울 수 있습니다. 이 경우에 카카오톡 채널 웹훅을 사용하면 알림으로 변동 사항을 파악할 수 있습니다.

제공 API

• 각 API의 Kakao SDK 지원 여부는 지원 범위에서 확인할 수 있습니다.

API	설명	문서
카카오톡 채널 간편 추가	사용자에게 지정된 카카오톡 채널의 친구 추가를 요청합니다.	JavaScript Android iOS Flutter
카카오톡 채널 추가	사용자가 지정된 카카오톡 채널을 친구로 추가할 수 있는 연결 페이지를 제공합니다.	JavaScript Android iOS Flutter
카카오톡 채널 채팅	사용자가 지정된 카카오톡 채널과의 1:1 채팅방으로 진입할 수 있는 연결 페이지를 제공합니다.	JavaScript Android iOS Flutter
카카오톡 채널 관계 조회	현재 로그인한 사용자와 앱에 연결된 카카오톡 채널의 친구 관계를 확인합니다.	REST API JavaScript Android iOS Flutter
여러 사용자 카카오톡 채널 관계 조회	앱에 연결된 카카오톡 채널과 여러 사용자의 친구 관계를 확인합니다.	REST API
카카오톡 채널 웹훅	사용자가 앱에 연결된 카카오톡 채널을 추가하거나 차단했을 때 서비스 서버에 알려줍니다.	웹훅
고객 관리: 고객파일 등록	새로운 고객파일을 만듭니다.	REST API
고객 관리: 고객파일 조회	카카오톡 채널에 등록된 고객파일 정보들을 확인합니다.	REST API
고객 관리: 고객파일에 사용자 추가	고객파일에 사용자 정보를 추가합니다.	REST API
고객 관리: 고객파일의 사용자 삭제	카카오톡 채널에 등록된 고객파일에서 특정 사용자를 삭제합니다.	REST API