이 문서는 제휴사 전용 카카오톡 소셜 API 사용 방법을 안내합니다.

제휴사에 한해 초대 친구 정보와 초대 메시지 기능의 사용 권한, Kakao SDK의 제휴 전용 모듈을 제공합니다.

초대 친구는 서비스의 앱에 카카오 로그인 및 연결되지 않은 카카오톡 친구를 의미합니다. 카카오톡 소셜 API는 기본적으로 서비스 앱에 연결된 카카오톡 친구의 정보만 제공하지만, 제휴사에 한해 초대 친구 정보를 추가 제공합니다.

초대 메시지는 초대 친구에게 카카오톡 메시지를 보내는 기능입니다. 카카오톡 메시지는 서비스 앱의 바로가기를 포함해 다양한 콘텐츠로 구성할 수 있습니다. 예를 들어, 초대 친구에게 서비스 가입이나 상품 구매를 유도할 수 있습니다. 자세한 정보는 메시지 템플릿을 참고합니다.

초대 메시지를 발송하려면 초대 친구의 고유 ID(uuid)가 필요합니다. 제휴 전용 모듈은 친구 피커로 고유 ID를 포함한 초대 친구 정보를 제공합니다. 사용자는 초대 메시지를 보낼 대상을 친구 피커에서 직접 선택할 수 있습니다. 사용자 선택 과정 없이 모든 초대 친구의 정보를 제공하는 API는 제공하지 않습니다.

초대 메시지 발송에 필요한 카카오 API를 호출하려면, 사용자가 서비스 앱에 카카오 로그인하고 발급받은 액세스 토큰이 필요합니다. 카카오 로그인을 사용하고 있지 않은 서비스인 경우, 사용자가 카카오 로그인으로 로그인 및 가입하는 기능을 먼저 구현해야 합니다. 카카오 로그인에 대한 자세한 안내는 이해하기를 참고합니다.

카카오 로그인 시 사용자가 필요한 동의항목에 모두 동의해야 합니다.

초대 메시지를 보내려면 제휴 전용 모듈의 친구 피커로 초대 친구의 고유 ID를 제공받아야 합니다. 친구 피커는 자체적으로 친구 목록 UI를 제공하므로 별도 UI 구현 없이도 편리하게 사용할 수 있습니다.

사용자가 서비스에서 초대 메시지 기능을 사용하려고 할 때 친구 피커를 호출합니다. 사용자가 친구 피커에서 초대 메시지를 보낼 초대 친구를 선택하면, 선택된 초대 친구의 고유 ID가 응답으로 전달됩니다.

제휴 전용 모듈과 친구 피커 사용 방법에 대한 자세한 안내는 아래 문서를 참고합니다.

• Android
• iOS

카카오톡 메시지 API를 사용해 초대 친구의 고유 ID로 초대 메시지를 발송합니다. 자세한 안내는 아래 문서를 참고합니다.

• Android
• iOS

초대 메시지를 보내려면 사용자가 카카오 로그인 시 아래 동의항목에 모두 동의해야 합니다.

• [카카오 서비스 내 친구목록(프로필사진, 닉네임, 즐겨찾기 포함)]
• [카카오톡 메시지 전송]

해당 동의항목을 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 [선택 동의]로 설정합니다. 자세한 안내는 동의항목을 참고합니다.

사용자가 이미 카카오 로그인으로 서비스에 로그인 및 가입한 경우에는 동의항목 추가 동의 요청으로 필요한 동의항목의 동의를 요청할 수 있습니다.

초대 메시지는 카카오톡 사용자의 사용성 보호를 위한 쿼터(Quota)를 적용받습니다. 쿼터는 앱별로 적용됩니다. 현재 적용된 쿼터 정보는 아래와 같습니다.

• 발신자당 일 50회
  • 사용자 A는 하루에 50명의 초대 친구에게 1회씩 초대 메시지 발송 가능
• 동일 수신자에 대해 일 6회, 월 30회
  • 초대 친구 B는 서로 다른 발신자로부터 일 6회, 월 30회의 초대 메시지 수신 가능
• 동일 발신자와 동일 수신자로 구성된 한 쌍에 대해 월 1회
  • 사용자 A가 초대 친구 B에게 1월 1일에 초대 메시지를 발송했다면, 2월 1일 이후 다시 초대 메시지 발송 가능

초대 친구의 프로필 닉네임은 마스킹(Masking) 처리 후 서비스에 제공됩니다. 마스킹 규칙은 아래와 같습니다.

사용자의 일부 친구가 프로필 공개 설정으로 인해 친구 피커에 노출되지 않을 수 있습니다. 친구 피커에 노출되지 않는 친구에게는 카카오톡 메시지를 보낼 수 없습니다.

시작하기를 참고해 Android SDK(Kakao SDK for Android)와 제휴 전용 모듈을 설치합니다. 모듈 추가 시 아래 코드를 포함하면 제휴 전용 모듈을 설치할 수 있습니다.

dependencies {
    // 초대 메시지 제휴 전용 모듈 설치
    implementation "com.kakao.sdk:partnership-social:1.0.0"
}

Android SDK 신규 설치 시, 제휴 전용 모듈만 설치하더라도 초대 메시지 발송 기능 구현에 필요한 모듈이 함께 설치됩니다.

제휴 전용 모듈을 사용하려면 Android SDK를 초기화해야 합니다. 카카오 로그인과 초대 메시지 발송에 필요한 API 호출 시 Android SDK 초기화 시 입력된 앱 키가 사용됩니다.

초대 메시지를 발송하려면 먼저 서비스 앱에 카카오 로그인 기능을 구현해야 합니다. 자세한 안내는 초대 메시지 발송 과정을 참고합니다.

초대 메시지 발송에 필요한 초대 친구의 고유 ID를 제공받기 위해 제휴 전용 모듈의 친구 피커를 호출합니다.

원하는 화면 표시 형태와 선택 유형의 친구 피커를 호출합니다.

친구 피커에 초대 친구만 노출하려면 friendFilter 파라미터 값을 PickerFriendFilter.INVITABLE로 설정해야 합니다. friendFilter 파라미터는 제휴 전용 모듈이 설치돼 있고, 사용 권한이 있어야만 사용 가능합니다.

쿼터에 따라 이미 초대 메시지를 보낸 초대 친구에게는 1달간 다시 초대 메시지를 보낼 수 없습니다. disableSelectOptions 파라미터를 사용하면 특정 친구를 친구 피커에서 선택할 수 없도록 설정할 수 있습니다.

이밖에 피커의 화면 모드와 방향, 밝기 등을 설정하는 파라미터를 제공합니다. 예제를 참고합니다.

사용자가 선택한 친구 정보는 SelectedUsers 객체로 전달됩니다. 응답은 선택한 사용자 수, 선택한 사용자 정보를 담은 목록을 포함합니다.

각각의 선택된 친구 정보는 SelectedUser 객체로 마스킹 처리된 친구의 프로필, 초대 메시지 발송에 필요한 고유 ID(uuid)를 포함합니다. 고유 ID를 사용해 초대 메시지 발송을 요청할 수 있습니다.

val pickerFriendRequestParams = PickerFriendRequestParams(
    title = "초대하기", // 피커 이름
    friendFilter = PickerFriendFilter.INVITABLE, // 친구 목록 필터링 설정, 초대 친구만 노출
    viewAppearance = ViewAppearance.AUTO, // 피커 화면 모드, 시스템 디스플레이 설정에 따라 자동 전환
    orientation = PickerOrientation.AUTO, // 피커 화면 방향, 시스템 설정에 따라 자동 전환
    enableSearch = true, // 검색 기능 사용 여부
    enableIndex = true, // 인덱스뷰 사용 여부
    showMyProfile = false, // 내 프로필 표시 여부
    showFavorite = true, // 즐겨찾기 친구 표시 여부
    // 선택 불가 설정
    disableSelectOptions = listOf(
        DisableSelectOption(
            // 선택 불가 원인
            // .REGISTERED: 앱과 이미 연결되어 있음
            // .CUSTOM: 서비스에서 직접 설정한 이유
            reason = DisableSelectReason.CUSTOM,
            // 친구 피커에 출력할 선택 불가 원인 문구
            message = "초대 완료",
            // 선택 불가로 설정할 사용자 UUID 목록
            uuids = listOf("${USER_UUID_1}", "${USER_UUID_2}")
        )
    )
)

PickerClient.instance.selectFriend(
    context = context!!,
    params = pickerFriendRequestParams
) { selectedUsers, error ->
    if (error != null) {
        Log.e(TAG, "친구 선택 실패", error)
    } else {
        Log.d(TAG, "친구 선택 성공 $selectedUsers")
    }
}

카카오톡 메시지 API를 사용해 초대 메시지를 발송합니다.

초대 친구의 고유 ID(uuid)를 담은 List<String> 값을 receiverUuids 파라미터로 전달합니다.

자세한 안내와 예제는 아래 문서를 참고합니다.

• 기본 템플릿으로 메시지 발송
• 사용자 정의 템플릿으로 메시지 발송
• 스크랩 메시지 발송

시작하기를 참고해 iOS SDK(Kakao SDK for iOS)와 제휴 전용 모듈을 설치합니다. 제휴 전용 모듈을 설치하려면 설치를 참고해 아래 레포지토리의 master 브랜치에서 KakaoPartnershipSDKSocial을 설치합니다.

iOS SDK 신규 설치 시, 제휴 전용 모듈만 설치하더라도 초대 메시지 발송 기능 구현에 필요한 모듈이 함께 설치됩니다.

리소스 번들 설정이 필요합니다. Package Dependencies > KakaoOpenSDK > Sources > KakaoSDKFriendCore > KakaoSDKFriendResources.bundle 파일을 [Build Phase] > [Copy Bundle Resources]에 [+] 클릭 또는 드래그앤드롭하여 추가합니다.

설치 후, 초대 메시지 기능을 구현할 파일에 아래와 같이 필요한 모듈을 설정합니다.

import KakaoSDKCommon
import KakaoSDKAuth
import KakaoSDKUser
import KakaoSDKTalk
import KakaoSDKFriend
import KakaoPartnershipSDKSocial

제휴 전용 모듈을 사용하려면 iOS SDK를 초기화해야 합니다. 카카오 로그인과 초대 메시지 발송에 필요한 API 호출 시 iOS SDK 초기화 시 입력된 앱 키가 사용됩니다.

초대 메시지를 발송하려면 먼저 서비스 앱에 카카오 로그인 기능을 구현해야 합니다. 자세한 안내는 초대 메시지 발송 과정을 참고합니다.

초대 메시지 발송에 필요한 초대 친구의 고유 ID를 제공받기 위해 제휴 전용 모듈의 친구 피커를 호출합니다.

원하는 화면 표시 형태와 선택 유형의 친구 피커를 호출합니다.

친구 피커에 초대 친구만 노출하려면 friendFilter 파라미터 값을 .invitable로 설정해야 합니다. friendFilter 파라미터는 제휴 전용 모듈이 설치돼 있고, 사용 권한이 있어야만 사용 가능합니다.

쿼터에 따라 이미 초대 메시지를 보낸 초대 친구에게는 1달간 다시 초대 메시지를 보낼 수 없습니다. disableSelectOptions 파라미터를 사용하면 특정 친구를 친구 피커에서 선택할 수 없도록 설정할 수 있습니다.

이밖에 피커의 화면 모드와 방향, 밝기 등을 설정하는 파라미터를 제공합니다. 예제를 참고합니다.

사용자가 선택한 친구 정보는 SelectedUsers 객체로 전달됩니다. 응답은 선택한 사용자 수, 선택한 사용자 정보를 담은 목록을 포함합니다.

각각의 선택된 친구 정보는 SelectedUser 객체로 마스킹 처리된 친구의 프로필, 초대 메시지 발송에 필요한 고유 ID(uuid)를 포함합니다. 고유 ID를 사용해 초대 메시지 발송을 요청할 수 있습니다.

// 선택 불가로 설정할 사용자 UUID 목록
    let uuids = ["${USER_UUID_1}", "${USER_UUID_2}"]

// 선택 불가 설정
let disableSelectOptions = [
    DisableSelectOption(
        // 선택 불가 원인
        // .registered: 앱과 이미 연결되어 있음
        // .custom: 서비스에서 직접 설정한 이유
        reason :.custom,
        // 친구 피커에 출력할 선택 불가 원인 문구
        message : "초대 완료",
        // 선택 불가로 설정할 사용자 UUID 목록
        uuids : uuids
    )
]

let pickerFriendRequestParams = PickerFriendRequestParams(
    title: "초대하기", // 피커 이름
    friendFilter: .invitable, // 친구 목록 필터링 설정, 초대 친구만 노출
    viewAppearance: .auto, // 피커 화면 모드, 시스템 디스플레이 설정에 따라 자동 전환
    orientation: .auto, // 피커 화면 방향, 시스템 설정에 따라 자동 전환
    enableSearch: true, // 검색 기능 사용 여부
    enableIndex: true, // 인덱스뷰 사용 여부
    showMyProfile: false, // 내 프로필 표시 여부
    showFavorite: true, // 즐겨찾기 친구 표시 여부
    disableSelectOptions : disableSelectOptions // 선택 불가 설정
)

PickerApi.shared.selectFriend(param: pickerFriendRequestParams) { selectedUsers, error in
    if let error = error {
        print(error)
    }
    else {
        print("selectFriend(param:) success.")

        //do something
        _ = selectedUsers
    }
}

카카오톡 메시지 API를 사용해 초대 메시지를 발송합니다.

초대 친구의 고유 ID(uuid)를 담은 [String] 값을 receiverUuids 파라미터로 전달합니다.

자세한 안내와 예제는 아래 문서를 참고합니다.

• 기본 템플릿으로 메시지 발송
• 사용자 정의 템플릿으로 메시지 발송
• 스크랩 메시지 발송

친구 피커 호출 시 발생하는 주요 에러는 에러 코드에서 확인할 수 있습니다. 이 외 에러는 아래 내용을 참고합니다.