페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 친구그룹 관리

카카오모먼트

친구그룹 관리

이 문서는 친구그룹 관리 API 사용 방법을 안내합니다.

친구그룹 목록 조회

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

친구그룹 목록을 조회합니다. 다수의 광고 집행 및 브랜드(서비스) 운영을 위한 고객 식별자(전화번호/앱유저아이디)를 직접 업로드할 수 있습니다. 등록한 친구그룹은 카카오톡 채널 X 도달 캠페인에서만 사용할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 성공 시 각 친구그룹 상세 정보를 담은 목록을 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O

응답

본문
이름 타입 설명
- TalkChannelGroupFile[] 친구그룹 목록
TalkChannelGroupFile
이름 타입 설명
id Long 친구그룹 ID
profileId String 카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법
talkChannelProfileName String 카카오톡 채널 프로필 이름
fileType String 파일 유형, 아래 중 하나
APP_USER_ID(앱유저아이디),
PHONE_NUMBER(전화번호)
MESSAGE_RETARGET(메시지 발송 대상자)
groupKey String 친구그룹 파일의 그룹 키
name String 친구그룹 이름
friendCount Long 친구 수
talkChannelGroupFileStatus String 상태
WAITING (친구그룹 생성 대기중),
COMPLETE (친구그룹 생성 완료),
DELETE (삭제 또는 삭제중인 상태),
ERROR (그 외 비정상적인 경우) 중 하나
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": 1,
        "profileId": 1,
        "name": "첫번째_친구",
        "talkChannelGroupFileStatus": "COMPLETE",
        "talkChannelProfileName": "첫번째_친구",
        "fileType": "APP_USER_ID",
        "groupKey": "${GROUP_KEY}",
        "createdDate": "2020-01-01 00:00:00"
    }
]

친구그룹 등록

기본 정보
메서드 URL 인증 방식
POST https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

광고 집행과 운영으로 확보한 고객 식별자 또는 먼저 집행한 메시지 발송 대상자를 친구그룹으로 등록할 수 있습니다. 친구그룹은 '카카오톡 채널 X 도달 캠페인'에서만 사용 가능하며 광고계정당 최대 50개 친구그룹을 등록할 수 있습니다.

고객 식별자 유형(전화번호, 앱유저아이디)의 경우, 10개 이하의 총합 200MB 이하의 CSV 파일을 업로드하여 친구그룹을 등록할 수 있습니다. 친구그룹 파일 내용 형식은 가이드 및 예제를 참고합니다.

메시지 발송 대상자 유형의 경우, 동일 광고 계정에서 발송한지 30일 이내의 삭제되지 않은 메시지 광고그룹 ID를 등록하여 친구그룹을 등록할 수 있습니다.

이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.

주의: 개인정보 처리에 따른 의무사항

카카오 광고 통합서비스 이용을 위해 이용자의 개인 정보를 카카오에 위탁하는 경우 광고주는 이 사실을 이용자에게 안내해야 합니다. 또한, 광고주는 관련된 법률에 따라 이용자에게 동의 받은 목적으로만 개인 정보를 이용해야 합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청하며, 등록할 친구그룹 정보를 필수 파라미터로 전달해야 합니다.

성공 시, 등록된 친구그룹 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
name String 친구그룹 이름
한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음		 O
profileId String 카카오톡 채널 프로필 ID
카카오톡 채널 프로필 목록 조회 API로 조회한 ID 값

참고: 카카오톡 채널 프로필 ID 확인 방법		 O
fileType String 친구그룹 유형, 아래 중 하나
APP_USER_ID(앱유저아이디)
PHONE_NUMBER(전화번호), MESSAGE_RETARGET(메시지 발송 대상자)		 O
files Multipart File[] 친구그룹 파일
fileType이 APP_USER_ID, PHONE_NUMBER인 경우 필수		 O*
adGroupIds Long[] 메시지 광고그룹 ID
fileType이 MESSAGE_RETARGET인 경우 필수		 O*

응답

본문
이름 타입 설명
adAccountId Long 광고계정 번호
id Long 친구그룹 ID
name String 친구그룹 이름
fileType String 친구그룹 유형, 아래 중 하나
APP_USER_ID(앱유저아이디)
PHONE_NUMBER(전화번호)
MESSAGE_RETARGET(메시지 발송 대상자)
adGroupIds Long 메시지 광고그룹 ID
successCount Integer 업로드 파일 중 성공 식별자수
failedFileUrl String 업로드 파일 중 실패한 식별자 모음 파일 URL
failedCount Integer 업로드 파일 중 실패한 식별자 수
status String 상태, 아래 중 하나
WAITING(대기중)
COMPLETE(완료)
DELETE(삭제)
ERROR(생성 실패)
createdDate String 생성일시 yyyy-MM-dd'T'HH:mm:ss

예제

요청
curl -X POST "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \      
    -F "name=친구그룹타겟이름" \ 
    -F "profileId=12345" \  
    -F "fileType=APP_USER_ID" \ 
    -F "adGroupIds=12345" \  
    -F "files=@local/친구그룹파일.csv"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId" : ${AD_ACCOUNT_ID},
    "id" : 645645,
    "name" : "친구그룹타겟이름",
    "fileType" : "APP_USER_ID",
    "adGroupIds" : 12345,
    "successCount" : 20,
    "failedCount" : 1,
    "failedFileUrl" : "${FILE_URL}",
    "status" : "WAITING",
    "createdDate" : "2022-01-01 00:00:00"
}

친구그룹 이름 수정

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/name 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

친구그룹 이름을 수정할 수 있습니다. 친구그룹은 카카오톡 채널 X 도달 캠페인에서만 사용 가능합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하며, 대상 친구그룹과 수정할 친구그룹 이름을 필수 파라미터로 전달해야 합니다. 성공 시 수정된 친구그룹 정보를 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
본문
이름 타입 설명 필수
id Long 친구그룹 ID O
name String 친구그룹 이름
한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음		 O

응답

본문
이름 타입 설명
id Long 친구그룹 ID
name String 친구그룹 이름
fileType String 친구그룹 유형, 아래 중 하나
APP_USER_ID(앱유저아이디),
PHONE_NUMBER(전화번호)
MESSAGE_RETARGET(메시지 발송 대상자)
groupKey String 친구그룹 파일의 그룹 키
profileId String 카카오톡 채널 프로필 ID

참고: 카카오톡 채널 프로필 ID 확인 방법
talkChannelProfileName String 카카오톡 채널 프로필 이름
talkChannelGroupFileStatus String 상태, 아래 중 하나
WAITING (대기중)
COMPLETE (완료)
DELETE (삭제)
ERROR(생성 실패)
createdDate String 생성일시
yyyy-MM-dd'T'HH:mm:ss 형식
lastModifiedDate String 마지막 수정일시
yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/name" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \
    -d '{
            "id": 1234,
            "name": "첫번째_친구그룹_이름수정"
        }'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "profileId": 1,
    "name": "첫번째_친구그룹_이름수정",
    "talkChannelGroupFileStatus": "COMPLETE",
    "talkChannelProfileName": "첫번째_친구그룹_이름수정",
    "fileType": "APP_USER_ID",
    "groupKey": "${GROUP_KEY}",
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 15:00:00"
}

친구그룹 삭제

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

친구그룹을 삭제할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 친구그룹 ID O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

친구그룹 여러 개 삭제

기본 정보
메서드 URL 인증 방식
DELETE https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

복수의 친구그룹을 한 번에 삭제할 삭제할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
쿼리 파라미터
이름 타입 설명 필수
ids String 친구그룹 ID
여러 개의 친구그룹 ID를 쉼표(,)로 구분한 하나의 문자열로 전달		 O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles?ids=${ID},${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

친구그룹 사용 현황 조회

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/${ID} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 리다이렉트 URI 등록
비즈니스 동의항목		 필요 필요

친구그룹을 사용 중인 광고 그룹을 조회할 수 있습니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 광고 계정 번호 및 친구그룹 번호를 필수 파라미터로 전달해야 합니다. 성공 시 친구그룹을 사용 중인 광고 그룹 및 메시지 정보의 목록을 받습니다. 실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
광고계정 ID		 O
경로 변수
이름 타입 설명 필수
ID Long 친구그룹 ID O

응답

본문
이름 타입 설명
- AdgroupAndCampaign[] 친구그룹을 사용 중인 광고 그룹
AdgroupAndCampaign
이름 타입 설명
campaign Campaign 캠페인
adGroup AdGroup 광고그룹
messageAd MessageAd 메시지

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/${ID}" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "adGroup": {
            "id": 105488,
            "name": "first_ad_group",
            "adGroupStatus": ["LIVE"],
            "adGroupType": "DISPLAY"
        },
        "campaign": {
            "id": 62286,
            "name": "first_campaign",
            "campaignTypeGoal": {
                "campaignType": "DISPLAY",
                "goal": "VISITING"
            }
        }
    },
    {
        "messageAd": {
            "id": "msg-ad-1362737813386051585",
            "name": "first_message",
            "opStatus": ["READY"]
        }
    }
]

더 보기

카카오모먼트> 친구그룹 관리