카카오모먼트

친구그룹 관리

이 문서는 친구그룹 관리 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 비즈니스 동의항목	필요	필요

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

요청

헤더

이름	설명	필수
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"]
        }
    }
]

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

친구그룹 관리

친구그룹 목록 조회

기본 정보

요청

헤더

응답

본문

TalkChannelGroupFile

예제

요청

응답

친구그룹 등록

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

친구그룹 이름 수정

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

친구그룹 삭제

기본 정보

요청

헤더

경로 변수

예제

요청

응답

친구그룹 여러 개 삭제

기본 정보

요청

헤더

쿼리 파라미터

예제

요청

응답

친구그룹 사용 현황 조회

기본 정보

요청

헤더

경로 변수

응답

본문

AdgroupAndCampaign

예제

요청

응답

더 보기

도움이 되었나요?

친구그룹 관리