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

카카오모먼트

친구그룹 관리

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

친구그룹 목록 보기

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

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

Request
URL
GET /openapi/v4/talkChannelGroupFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
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 친구그룹 번호
profileId String 카카오톡 채널 프로필 ID
plusFriendProfileName String 카카오톡 채널 프로필 이름
fileType String 파일 유형
APP_USER_ID (앱유저아이디),
PHONE_NUMBER (전화번호) 중 하나
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,
        "plusFriendProfileId": 1,
        "name": "첫번째_친구",
        "tlakChannelGroupFileStatus": "COMPLETE",
        "plusFriendProfileName": "첫번째_친구",
        "fileType": "APP_USER_ID",
        "groupKey": "2067836d9750480ab67e823e107a2c31",
        "createdDate": "2020-01-01 00:00:00",
        "lastModifiedDate": "2020-01-01 00:00:00"
    }
]

친구그룹 이름 수정하기

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

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

Request
URL
PUT /openapi/v4/talkChannelGroupFiles/name HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer {ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 번호 O
name String 친구그룹 이름
한글, 영문, 특수문자, 공백을 허용하며
50자를 넘을 수 없음
O
Response
Name Type Description
id Long 친구그룹 번호
name String 친구그룹 이름
fileType String 파일 유형
APP_USER_ID (앱유저아이디),
PHONE_NUMBER (전화번호) 중 하나
profileId String 카카오톡 채널 프로필 ID
plusFriendProfileName 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,
    "plusFriendProfileId": 1,
    "name": "첫번째_친구그룹_이름수정",
    "tlakChannelGroupFileStatus": "COMPLETE",
    "plusFriendProfileName": "첫번째_친구그룹_이름수정",
    "fileType": "APP_USER_ID",
    "groupKey": "9c2754153bc64b3f8df9783f6fe6d4c5",
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 15:00:00"
}

친구그룹 삭제하기

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

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

Request
URL
DELETE /openapi/v4/talkChannelGroupFiles/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer {ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 번호 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

친구그룹 사용 현황 보기

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

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

Request
URL
GET /openapi/v4/talkChannelGroupFiles/usages/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String 액세스 토큰
Bearer {ACCESS_TOKEN} 형식으로 전달
O
adAccountId Long 광고계정 ID O
Parameter
Name Type Description Required
id Long 친구그룹 번호 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"
            }
        }
    }
]

더보기