페이지 이동경로
- 문서>
- 카카오모먼트>
- 친구그룹 관리
카카오모먼트
친구그룹 관리
이 문서는 친구그룹 관리 API 사용 방법을 안내합니다.
친구그룹 목록 보기
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
친구그룹 목록을 조회합니다. 다수의 광고 집행 및 브랜드(서비스) 운영을 통하여 고객 식별자(전화번호/앱유저아이디)를 직접 업로드할 수 있습니다. 등록한 친구그룹은 카카오톡 채널 X 도달 캠페인에서만 사용할 수 있습니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 성공 시 각 친구그룹 상세 정보를 담은 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${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 형식 |
| lastModifiedDate | String |
마지막 수정일시yyyy-MM-dd'T'HH:mm:ss 형식 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
-H "Authorization: Bearer ${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",
"lastModifiedDate": "2020-01-01 00:00:00"
}
]
친구그룹 등록하기
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
광고 집행 및 운영을 통해 확보한 고객 식별자 또는 먼저 집행한 메시지 발송 대상자를 친구그룹으로 등록할 수 있습니다. 친구그룹은 '카카오톡 채널 X 도달 캠페인'에서만 사용 가능하며 광고계정당 최대 50개 친구그룹을 등록할 수 있습니다.
고객 식별자 유형(전화번호, 앱유저아이디)의 경우, 10개 이하의 총합 200MB 이하의 CSV 파일을 업로드하여 친구그룹을 등록할 수 있습니다. 친구그룹 파일 내용 형식은 가이드 및 예제를 참고합니다.
메시지 발송 대상자 유형의 경우, 동일 광고 계정에서 발송한지 30일 이내의 삭제되지 않은 메시지 광고그룹 ID를 등록하여 친구그룹을 등록할 수 있습니다.
이 API는 사용자 계정, 광고계정마다 5초에 한 번씩 요청 가능하도록 제한되어 있습니다.
주의: 개인정보 처리에 따른 의무사항
카카오 광고 통합서비스 이용을 위해 이용자의 개인 정보를 카카오에 위탁하는 경우 광고주는 이 사실을 이용자에게 안내해야 합니다. 또한, 광고주는 관련된 법률에 따라 이용자에게 동의 받은 목적으로만 개인 정보를 이용해야 합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 POST로 요청하며, 등록할 친구그룹 정보를 필수 파라미터로 전달해야 합니다.
성공 시, 등록된 친구그룹 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${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[] |
메시지 광고그룹 IDfileType이 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 ${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 |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
친구그룹 이름을 수정할 수 있습니다. 친구그룹은 카카오톡 채널 X 도달 캠페인에서만 사용 가능합니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청하며, 대상 친구그룹과 수정할 친구그룹 이름을 필수 파라미터로 전달해야 합니다. 성공 시 수정된 친구그룹 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${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 ${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} |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
친구그룹을 삭제할 수 있습니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 |
O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID |
O |
경로 변수
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ID | Long |
친구그룹 ID | O |
예제
요청
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/${ID}" \
-H "Authorization: Bearer ${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 |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
복수의 친구그룹을 한 번에 삭제할 삭제할 수 있습니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 |
O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID |
O |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ids | String |
친구그룹 ID 여러 개의 친구그룹 ID를 쉼표(,)로 구분한 하나의 문자열로 전달 |
O |
예제
요청
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles?ids=${ID},${ID}" \
-H "Authorization: Bearer ${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} |
액세스 토큰 |
| 권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
|---|---|---|---|
| 필요 | 플랫폼 등록 카카오 로그인 활성화 비즈 앱 |
필요 | - |
친구그룹을 사용 중인 광고 그룹을 조회할 수 있습니다.
액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 광고 계정 번호 및 친구그룹 번호를 필수 파라미터로 전달해야 합니다. 성공 시 친구그룹을 사용 중인 광고 그룹 정보의 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 |
O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID |
O |
경로 변수
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ID | Long |
친구그룹 ID | O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| - | AdgroupAndCampaign[] |
친구그룹을 사용 중인 광고 그룹 |
AdgroupAndCampaign
| 이름 | 타입 | 설명 |
|---|---|---|
| campaign | Campaign |
캠페인 |
| adGroup | AdGroup |
광고그룹 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/${ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{
"adGroup": {
"id": 5678,
"name": "첫번째_광고그룹",
"adGroupStatus": [
"READY"
],
"adGroupType": "DIRECT_MESSAGE"
},
"campaign": {
"id": 9012,
"name": "첫번째_캠페인",
"campaignTypeGoal": {
"campaignType": "TALK_CHANNEL",
"goal": "REACH"
}
}
}
]