카카오모먼트

친구그룹 관리

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

친구그룹 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

친구그룹 목록을 반환합니다.

친구그룹 활용

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

요청

헤더

이름	설명	필수
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초에 한 번씩 요청 가능하도록 제한되어 있습니다.

요청

헤더

이름	설명	필수
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": 123456789, // ${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 도달 캠페인에서만 사용 가능합니다.

요청

헤더

이름	설명	필수
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 비즈니스 동의항목	필요	필요

친구그룹을 삭제합니다.

요청

헤더

이름	설명	필수
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 비즈니스 동의항목	필요	필요

친구그룹을 사용 중인 광고 그룹을 반환합니다.

요청

헤더

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

예제

요청

응답

더 보기

도움이 되었나요?

친구그룹 관리