이 문서는 카카오 또는 공동체 서비스용 카카오톡 오픈채팅 API를 소개합니다.
카카오톡 오픈채팅 API는 특정 서비스 앱과 카카오톡 오픈채팅을 연결하는 기능을 제공합니다. 누구나 참여 가능한 일반적인 오픈채팅과 달리, 카카오톡 오픈채팅 API는 특정 서비스 사용자들만이 참여 가능하도록 제한된 오픈채팅 대화방을 생성합니다. 카카오톡 오픈채팅은 하나의 서비스 앱에 여러 개 생성될 수 있습니다.
카카오톡 오픈채팅 API는 서비스 사용자 간의 커뮤니티를 오픈채팅으로 확장하는 데 사용할 수 있습니다. 서비스 사용자 간 소모임, 게임의 길드 채팅과 같은 용도로 활용 가능합니다. API로만 카카오톡 오픈채팅을 생성 및 관리할 수 있고, 서비스에서 API로 메시지를 보내는 기능도 제공해 보다 긴밀하고 강력한 커뮤니티를 구축할 수 있습니다.
카카오톡 오픈채팅은 아래 두 가지 타입으로 나뉩니다.
- 1:1 채팅방
- 그룹 채팅방
사용 신청 및 설정을 참고해 타입 설정 권한을 받으면, 카카오톡 오픈채팅 생성 시 link_type 파라미터를 사용해 타입을 지정할 수 있습니다.
현재 일부 카카오톡 오픈채팅 API는 1:1 채팅방 타입을 지원하지 않습니다. 아래 표를 참고합니다.
| API | 1:1 채팅방 지원 |
|---|---|
| 채팅방 생성 | O |
| 채팅방 정보 변경 | O |
| 채팅방 삭제 | O |
| 오픈채팅 조회 | O |
| 채팅방 입장 | O |
| 채팅방 퇴장 | X |
| 멤버 프로필 변경 | O |
| 피드 등록 | X |
| 기본 템플릿으로 메시지 발송 | X |
| 사용자 정의 템플릿으로 메시지 발송 | X |
| 스크랩 메시지 발송 | X |
카카오톡 오픈채팅 API를 사용하려면 도메인 ID를 발급받아야 합니다. 아래 순서로 도메인 발급과 API 사용 권한을 신청합니다.
- 카카오디벨로퍼스에서 서비스 앱 신규 등록 또는 기존 서비스 앱 ID 확인
- 오픈채팅 레버리지 API 문의 아지트에서 도메인 ID 발급 요청
- 카카오톡 오픈채팅 담당자가 서비스 앱에 도메인 ID 발급, 카카오톡 오픈채팅 API 사용을 위한 권한 부여 후 아지트로 안내
이 과정을 거쳐 발급받은 서비스 앱 ID와 도메인 ID는 카카오톡 오픈채팅 API 호출 시 필수 파라미터로 사용합니다. 카카오톡 오픈채팅 API 호출 시 도메인 ID를 domain_id 필수 파라미터로 전달해야 합니다.
도메인에 부여되는 상세 설정에 대한 정보는 도메인 설정에서 확인할 수 있습니다.
도메인 ID 발급 및 권한 부여 후, 앱 관리 페이지의 [카카오 로그인] > [동의항목] > [접근권한]에서 [카카오톡 오픈채팅 참여 및 관리] 동의항목을 설정해야 합니다.
카카오톡 오픈채팅 API는 사용자로부터 [카카오톡 오픈채팅 참여 및 관리]에 대한 접근권한 동의를 받아야 사용 가능합니다. 사용 신청으로 권한을 받은 후, 앱 관리 페이지의 [카카오 로그인] > [동의항목] > [접근권한]에서 해당 동의항목을 설정해야 합니다. 동의항목을 참고합니다.
카카오톡 오픈채팅 API는 카카오톡 메시지를 보내는 API를 포함합니다. 카카오톡 메시지 API는 더 나은 사용자 경험을 위해 쿼터(Quota, 제공량 제한)가 적용됩니다. 인하우스 또는 공동체 앱의 쿼터는 쿼터에서 확인할 수 있습니다.
각 오픈채팅은 채팅방 입장 API 로만 사용자가 참여할 수 있고, 카카오톡 서비스 내에서 입장은 불가능합니다. 또한 해당 서비스 가입자에 한해 참여할 수 있으므로 별도의 참여 패스코드를 지원하지 않습니다.
사용자는 채팅방 퇴장 API, 또는 카카오톡 서비스 내에서 직접 카카오톡 오픈채팅 대화방에서 나갈 수 있습니다. 방장 및 멤버가 서비스 앱에서 탈퇴(연결 해제)해도 카카오톡 오픈채팅에서 내보내기(Kick)되지 않습니다.
방장은 채팅방 삭제가 가능합니다. 방장이 카카오톡 오픈채팅을 삭제한 경우에도 대화방이 사라지지는 않으나, 더 이상 채팅방 입장 API로 방장이나 다른 사용자가 대화방에 들어올 수 없습니다.
카카오톡 오픈채팅은 가입자만 참여 가능하고 모든 멤버가 서비스 가입자라는 가정 아래, 메시지에 수신 거부 기능을 포함하지 않습니다. [도구] > [메시지 템플릿]에서 등록해 사용하는 사용자 정의 템플릿은 사용자와 채팅방 모두를 대상으로 전송 가능한 [가입여부 무관] 타입으로 생성해 보내야 합니다. 또한 메시지 전송 기능은 메시지 템플릿 v2를 사용하므로 API 버전이 v1이 아닌 v2임에 주의해야 합니다.
일반적인 오픈채팅과 달리 카카오톡 오픈채팅의 프로필은 멤버 프로필 변경 API 요청으로만 가능하고, 사용자가 카카오톡 클라이언트에서 프로필을 직접 변경할 수 없습니다.
카카오톡 오픈채팅 프로필 사진, 피드의 아이콘 이미지는 10MB 미만이어야 합니다. 메시지의 이미지는 5MB 미만이어야 합니다. 이미지 등록을 포함한 API 요청 시, 3초 안에 KAGE에 덤프 생성이 불가능한 경우 해당 API 요청이 실패하게 됩니다. 이미지 용량 제한은 아래 API의 모든 이미지 관련 파라미터에 적용됩니다.
사용자의 앱 연결 상태에 따른 호출 제한, SDK 지원 여부, 권한 요구 사항은 지원 범위를 참고합니다.
| API | 설명 | 문서 | |
|---|---|---|---|
| 채팅방 생성 | 방장이 될 사용자가 카카오톡 오픈채팅을 생성합니다. | REST API | |
| 채팅방 정보 변경 | 방장인 사용자가 카카오톡 오픈채팅의 기본 정보를 변경합니다. | REST API | |
| 채팅방 삭제 | 카카오톡 오픈채팅을 삭제합니다. | REST API | |
| 오픈채팅 조회 | 특정 도메인 ID 하위에 생성된 오픈채팅 또는 지정한 오픈채팅 ID에 대한 정보를 조회합니다. | REST API | |
| 채팅방 입장 | 사용자가 카카오톡 오픈채팅에 참여합니다. | REST API | |
| 채팅방 퇴장 | 사용자가 카카오톡 오픈채팅에서 나갑니다. | REST API | |
| 멤버 프로필 변경 | 카카오톡 오픈채팅 멤버의 프로필을 변경합니다. | REST API | |
| 방장 변경 | 카카오톡 오픈채팅 방장을 변경합니다. | REST API | |
| 부방장 설정 | 카카오톡 오픈채팅 부방장을 지정 또는 해제합니다. | REST API | |
| 피드 등록 | 서비스 관리자가 오픈채팅 링크에 피드(Feed)를 보냅니다. | REST API | |
| 기본 템플릿으로 메시지 발송 | 미리 정의돼 있는 구조의 기본 템플릿을 사용해 카카오톡 오픈채팅에 메시지를 발송합니다. | REST API | |
| 사용자 정의 템플릿으로 메시지 발송 | 카카오디벨로퍼스의 [도구] > [메시지 템플릿]에서 등록한 사용자 정의 템플릿으로 오픈채팅 링크에 메시지를 발송합니다. | REST API | |
| 스크랩 메시지 발송 | 웹 페이지를 스크랩하고, 스크랩한 정보를 기반으로 오픈채팅 링크에 메시지를 발송합니다. | REST API | |
| 사용처 제한 API | 카카오페이: 오픈채팅 사용자 검증 | 특정 사용자의 카카오톡 오픈채팅 v_id와 카카오계정 ID(account_id)가 동일한 카카오계정에 해당하는지 검증합니다. | REST API |
| 카카오페이: 오픈채팅 멤버 여부 조회 | 카카오톡 오픈채팅에서 카카오페이 송금 시, 송금자와 수신자가 같은 오픈채팅방에 참여 중인지 확인합니다. | REST API | |