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

카카오모먼트

친구그룹 관리

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

친구그룹 목록 보기

기본 정보

GET /openapi/v4/talkChannelGroupFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

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

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O

Response

Name Type Description
- TalkChannelGroupFile[] 친구그룹 목록
TalkChannelGroupFile
Name Type Description
id Long 친구그룹 ID
profileId String 카카오톡 채널 프로필 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 형식

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"
Response
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"
    }
]

친구그룹 등록하기

기본 정보

POST /openapi/v4/talkChannelGroupFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

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

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

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

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

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

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

성공 시, 등록된 친구그룹 정보를 받습니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
name String 친구그룹 이름
한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음
O
profileId String 카카오톡 채널 프로필 ID
카카오톡 채널 프로필 목록 보기 API를 통해 조회한 ID 값
O
fileType String 친구그룹 유형
다음 중 하나
APP_USER_ID(앱유저아이디)
PHONE_NUMBER(전화번호), MESSAGE_RETARGET(메시지 발송 대상자)
O
files Multipart File[] 친구그룹 파일
fileTypeAPP_USER_ID, PHONE_NUMBER인 경우 필수
O*
adGroupIds Long[] 메시지 광고그룹 ID
fileTypeMESSAGE_RETARGET인 경우 필수
O*

Response

Name Type Description
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

Sample

Request
curl -X POST "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}" \      
    -F "name=친구그룹타겟이름" \ 
    -F "profileId=12345" \  
    -F "fileType=APP_USER_ID" \ 
    -F "adGroupIds=12345" \  
    -F "files=@local/친구그룹파일.csv" 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "adAccountId" : ${adAccountId},
    "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"
}

친구그룹 이름 수정하기

기본 정보

PUT /openapi/v4/talkChannelGroupFiles/name HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

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

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 ID O
name String 친구그룹 이름
한글, 영문, 특수문자, 공백을 허용하며 50자를 넘을 수 없음
O

Response

Name Type Description
id Long 친구그룹 ID
name String 친구그룹 이름
fileType String 친구그룹 유형
다음 중 하나
APP_USER_ID(앱유저아이디),
PHONE_NUMBER(전화번호)
MESSAGE_RETARGET(메시지 발송 대상자)
groupKey String 친구그룹 파일의 그룹 키
profileId String 카카오톡 채널 프로필 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 형식

Sample

Request
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/name" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}" \
    -d '{
            "id": 1234,
            "name": "첫번째_친구그룹_이름수정"
        }'
Response
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"
}

친구그룹 삭제하기

기본 정보

DELETE /openapi/v4/talkChannelGroupFiles/${id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 바디는 없습니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 ID O

Sample

Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/${id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

친구그룹 여러 개 삭제하기

기본 정보

DELETE /openapi/v4/talkChannelGroupFiles?ids=${ids} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 바디는 없습니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
ids String 친구그룹 ID
여러 개의 친구그룹 ID를 쉼표(,)로 구분한 하나의 문자열로 전달
O

Sample

Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles?ids=${id},${id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

친구그룹 사용 현황 보기

기본 정보

GET /openapi/v4/talkChannelGroupFiles/usages/${id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

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

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

Request

Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer ${ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 ID O

Response

Name Type Description
- AdgroupAndCampaign[] 친구그룹을 사용 중인 광고 그룹
AdgroupAndCampaign
Name Type Description
campaign Campaign 캠페인
adGroup AdGroup 광고그룹

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/${id}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"
Response
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"
            }
        }
    }
]

더보기