이 문서는 제휴 친구 피커를 이용해 서비스에 가입하지 않은 사용자에게 초대 메시지를 발송하는 방법을 안내합니다.

이 기능을 사용하려면 Kakao SDK의 제휴 전용 모듈을 사용해야 합니다.

이 문서의 핵심 개념은 다음과 같이 정의해 사용합니다.

제휴 친구 피커는 사용자가 특정 기능이나 콘텐츠를 카카오톡 친구에게 공유할 수 있도록 제공하는 친구 목록 화면입니다.

제휴 친구 피커를 이용해 서비스에 가입하지 않은 사용자에게 초대 메시지를 발송할 수도 있습니다. 서비스의 이용 목적과 시나리오에 대해 카카오의 심사를 마친 서비스만 이용 가능합니다.

오픈 API로 제공되는 친구 피커와의 차이점은 FAQ를 참고합니다.

제휴 친구 피커

제휴 친구 피커를 이용해 서비스에 가입하지 않은 사용자에게 초대 메시지를 발송하는 과정을 설명합니다.

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

• 카카오 로그인 사용 설정
• 리다이렉트 URI 설정
• 서비스에게 접근을 허용할 개인정보 동의항목가 있다면 동의항목 설정(선택)

친구 피커 화면에서 선택한 대상에게 메시지까지 보내려면 동의항목 설정이 필요합니다. 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 아래 동의항목을 설정합니다.

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

친구 피커를 호출할 사용자는 카카오 로그인 시 위 동의항목에 모두 동의해야 합니다. 사용자가 이미 카카오 로그인으로 서비스에 로그인 및 가입한 경우에는 동의항목 추가 동의 요청으로 필요한 동의항목의 동의를 요청할 수 있습니다.

초대 친구는 위 동의항목에 동의하지 않아도 됩니다.

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

아래 개발 문서를 참고해 서비스에 가입하지 않은 친구에게 카카오톡 메시지 를 발송하는 기능을 구현합니다.

1. 친구 피커 호출
2. 초대 메시지 발송

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

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

• 제휴 친구 피커는 사전에 정해진 목적과 사용 시나리오에 따라 제한적으로 제공됩니다.
• 제휴 서비스는 허용된 목적과 범위 내에서만 해당 기능을 사용할 수 있으며, 협의되지 않은 방식의 사용은 제한됩니다.
• 제휴 친구 피커의 친구 노출 조건은 아래와 같습니다.
  • 친구의 프로필 공개 설정이 공개 상태여야 함
  • 친구가 숨김 또는 차단 친구가 아니어야 함
• 친구 피커에 노출되지 않는 친구에게는 카카오톡 메시지를 보낼 수 없습니다.
• 친구 피커를 호출하는 사용자는 아래 조건을 만족해야 제휴 친구 피커가 정상 동작합니다.
  • 서비스 앱에 연결된 상태여야 합니다.
  • [카카오 서비스 내 친구 목록 제공] 동의항목에 동의한 상태여야 합니다.
  • 참고: 사용자의 카카오톡 친구는 서비스에 연결되지 않았거나 위 동의항목에 동의하지 않아도 제휴 친구 피커에 노출될 수 있습니다.
• 초대 친구의 프로필 닉네임은 개인 정보 보호를 위해 마스킹(Masking) 처리 후 서비스에 제공됩니다. (참고: 초대 친구 마스킹 규칙)
• 친구 피커는 초대 메시지 발송에 필요한 친구의 고유 ID만 전달하며, 친구의 개인 정보나 카카오톡 친구 목록 전체는 서비스에 제공하지 않습니다.
• 쿼터 정책에 따라 이미 초대 메시지를 보낸 초대 친구에게는 한 달간 다시 초대 메시지를 보낼 수 없습니다.

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

selectFriend()를 호출해 친구 피커를 표시합니다.

친구 선택 유형과 선택 가능한 대상 수는 SelectParams로 지정합니다. Android SDK에서는 SelectParams를 헬퍼 메서드인 SelectParams.friend()로 생성해야 합니다. 반환된 객체를 PickerFriendRequestParams의 selectParams에 전달합니다. 예제를 참고합니다.

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

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

val pickerFriendRequestParams = PickerFriendRequestParams(
    friendFilter = PickerFriendFilter.REGISTERED, // 친구 목록 필터링 설정
    viewAppearance = ViewAppearance.AUTO, // 피커 화면 모드
    orientation = PickerOrientation.PORTRAIT, // 피커 화면 방향
    selectParams = SelectParams.friend(
        mode = SelectionMode.SINGLE
SINGLE: 싱글 피커, MULTIPLE: 멀티 피커
    )
)

PickerClient.instance.selectFriend(
    context = context!!,
    params = pickerFriendRequestParams,
    viewType = ViewType.FULL,
FULL: 전체 화면, POPUP: 팝업 뷰
) { selectedUsers, error ->
    if (error != null) {
        Log.e(TAG, "친구 선택 실패", error)
    } else {
        Log.d(TAG, "친구 선택 성공 $selectedUsers")
    }
}

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

selectFriend()를 호출해 친구 피커를 표시합니다.

친구 선택 유형과 선택 가능한 대상 수는 SelectParams로 지정합니다. iOS SDK에서는 SelectParams를 직접 생성하거나 헬퍼 메서드인 SelectParams.friend()로 생성할 수 있습니다. 생성한 값을 PickerFriendRequestParams의 selectParams에 전달합니다. 예제를 참고합니다.

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

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

let pickerFriendRequestParams = PickerFriendRequestParams(
    friendFilter: PickerFriendFilter.registered, // 친구 목록 필터링 설정
    viewAppearance: .auto, // 피커 화면 모드
    orientation: .auto, // 피커 화면 방향
    selectParams: .friend(
        selectionMode: .single
.single: 싱글 피커, .multiple: 멀티 피커
    )
)

PickerApi.shared.selectFriend(
    params: pickerFriendRequestParams,
    viewType: .full
.full: 전체 화면, .popup: 팝업 뷰
) { [weak self] selectedUsers, error in
    if let error = error {
        print(error)
    } else {
        print("selectFriend(params:) success.")

        // 성공 시 동작 구현
        _ = selectedUsers
    }
}

카카오톡 메시지 API를 사용해 서비스에 가입하지 않은 친구에게 초대 메시지를 발송할 수 있습니다.

초대 메시지를 보내려면 제휴 친구 피커로 초대 친구의 고유 ID(uuid)를 제공받아야 합니다. 사용자가 서비스에서 초대 메시지를 보려는 시점에 친구 피커를 호출합니다. 사용자가 친구 피커에서 초대 메시지를 보낼 초대 친구를 선택하면, 선택된 초대 친구의 고유 ID가 응답으로 전달됩니다.

카카오톡 메시지 API 호출 시, 친구 피커로 제공 받은 친구의 고유 ID(uuid)를 receiverUuids 파라미터로 전달합니다.

서비스 신규 가입 사용자가 초대 메시지를 받고 가입했는지 고유 ID로 확인할 수 있습니다. 사용자 정보 조회 API 응답의 고유 ID를 초대 친구의 고유 ID와 비교해 초대 메시지 수신 여부를 확인할 수 있습니다.

2024년 8월 28일 이후 배포된 Kakao SDK에서만 사용자 정보 조회 API 응답에 고유 ID가 제공됩니다.

카카오톡 메시지 API로 메시지를 보낼 때는 아래 메시지 형태를 사용할 수 있습니다. (참고: 구성 방식 비교)

• 기본 템플릿
• 사용자 정의 템플릿: 서비스 가입 여부에 따라 다르게 메시지를 구성 가능, 가입 여부에 따른 메시지 구성 참고
• 스크랩 메시지

초대 메시지 구성 시, [도구] > [메시지 템플릿]에서 메시지 템플릿을 생성해 메시지를 보낼 수 있습니다.

제휴 친구 피커 사용 권한을 얻은 제휴 서비스는 [사용 목적]에서 아래 옵션을 선택할 수 있습니다. 이 외 옵션은 모두 동일하므로 사용자 정의 템플릿을 참고합니다.

• 가입자에게만 전송: 앱과 연결된 사용자에게만 카카오톡 메시지 API로 메시지 전송시 선택
• 미가입자에게만 전송: 앱과 연결되지 않은 사용자에게만 카카오톡 메시지 API로 메시지 전송시 선택

메시지 템플릿

선택한 사용 목적에 따라 프로필 공개 설정이 다르게 동작합니다. 앱에 가입하지 않은 사용자에게는 설정을 변경하라는 안내 메시지가 표시되며, 앱에 가입된 사용자에게는 프로필 공개 여부 설정 화면이 출력됩니다.

아래 개발 문서를 참고해 초대 메시지를 발송합니다.

제휴 친구 피커 버튼의 디자인 가이드와 표준 디자인 리소스는 디자인 가이드에서 제공합니다.

오픈 API로 제공되는 친구 피커에는 서비스 앱에 연결된 사용자의 카카오톡 친구만 표시됩니다.

사용 협의가 완료된 제휴사에게만 제공되는 제휴 친구 피커는 초대 친구도 함께 표시됩니다. 초대 친구를 대상으로 서비스 가입이나 이벤트 참여를 유도하는 초대 메시지를 발송할 수 있습니다.

사용자가 친구 피커에서 특정 친구를 선택하면, 사용자 식별을 위해 고유 ID(uuid)가 전달됩니다. 이 값은 친구의 이름, 사용자의 개인정보가 아니며, 개인이 직접 식별할 수 없는 난수 형태의 값입니다.

이 외에 선택한 친구의 개인정보나 사용자의 친구 목록 전체 모두 제휴 서비스에게 제공되지 않습니다. 카카오톡 친구 목록은 카카오가 제공하는 화면에만 표시되며, 사용자 정보는 카카오가 안전하게 보관합니다. 친구 피커 화면에 보이는 닉네임이나 프로필 사진 또한 대상을 구분하기 위한 요소일 뿐 제휴 서비스에 제공하지 않습니다. 또한 서비스 미가입자인 친구인 경우에도 개인 식별을 위한 식별값과 마스킹된 닉네임 정도만 제한적으로 전달될 수 있습니다. (예: 홍*동)

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