페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Friend group management

Kakao Moment

Friend group management

This document describes how to use the Friend group management APIs.

View list of Friend groups

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to retrieve a list of Friend groups.

In [타겟 관리(Target management)] > [친구그룹 관리(Friend group management)] in Kakao Moment Admin Center, you can create Friend groups by uploading the customer identifiers (phone numbers or service user IDs) or registering Message ad group IDs that are sent with the same ad account. You can use the registered Friend group only for the 'Kakao Talk Channel X Reach(도달)' type of campaign.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. If the request is successful, this API returns the list of each Friend group's detailed information in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O

Response

Body
Name Type Description
- TalkChannelGroupFile[] List of Friend group information.
TalkChannelGroupFile
Name Type Description
id Long Friend group's ID.
profileId String Kakao Talk Channel's profile ID.
talkChannelProfileName String Kakao Talk Channel's profile name.
fileType String Friend group's type.
One of the followings:
- APP_USER_ID: Service user ID
- PHONE_NUMBER: Phone number
- MESSAGE_RETARGET: Message recipients
groupKey String Friend group file's group key.
name String Friend group's name.
friendCount Long Number of friends.
talkChannelGroupFileStatus String Status.
One of the followings:
WAITING: Waiting for creating Friend group
COMPLETE: Creating Friend group has been completed
DELETE: Deleted or deleting
ERROR: Other abnormal cases
createdDate String Date and time of creation in yyyy-MM-dd'T'HH:mm:ss format.

Sample

Request
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": 1,
        "profileId": 1,
        "name": "first_friend",
        "talkChannelGroupFileStatus": "COMPLETE",
        "talkChannelProfileName": "first_friend",
        "fileType": "APP_USER_ID",
        "groupKey": "2067836d9750480ab67e823e107a2c31",
        "createdDate": "2020-01-01 00:00:00"
    }
]

Register Friend group

Basic information
Method URL Authorization
POST https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to register customer identifiers obtained while excecuting and operating ads, or message recipients as a Friend group.

Friends groups are only allowed for a campaign with 'Kakao Bizboard X Reach(도달)' type. You can upload up to 50 friend groups per ad account.

For the type of message recipients, you can register a Friend group by registering message ad group IDs whose messages should be sent with the same ad account within 30 days and not been deleted.

For the customer identifiers such as phone numbers and service user IDs, you can upload up to 10 CSV files with a total size of 200 MB or less to register Friend groups. You can add users' phone numbers and service user IDs only to a Friend group file in a CSV file format. To see the sample of the CSV file, download the template.

You can also download the template and register a Friend group file by referring to the teamplate in [Kakao Moment] > [Ad account] > [Target management] > [Friend group management] on the Kakao Business website. To see how to upload a Friend group file in detail, read Kakao Business Guide > Kakao Moment.

When you register Friends groups, you must comply with the following obligations.

Obligations for handling personal information

- If a user's personal information is entrusted to Kakao to use the Kakao's integrated advertising service, the advertiser must inform the user of this fact. - Advertisers must use personal information only for the purpose that users have consented in accordance with related laws.

Send a POST request with the issued business token and an ad account ID (adAccountId) in the request header. You must also pass the friend group information when you request. If the request is successful, this API returns the detailed information of the created friend group in JSON format. If failed, refer to Error code to figure out its failure cause.

This API limits the number of calls you can make to every five seconds per user account and ad account.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Body
Name Type Description Required
name String Friend group's name.
Allowed characters: Korean, English, special characters, space
Character limits: 50 characters		 O
profileId String Kakao Talk Channel's profile ID.
Use the IDs retrieved through the Viewing list of Kakao Talk Channel profiles API.		 O
fileType String Friend group's type.
One of the followings:
- APP_USER_ID: Service user ID
- PHONE_NUMBER: Phone number
- MESSAGE_RETARGET: Message recipients		 O
files MultipartFile Friend group file.
Only required if fileType is set to APP_USER_ID or PHONE_NUMBER.		 O*
adGroupIds Long[] Message ad group ID.
Only required if fileType is set to MESSAGE_RETARGET.		 O*

Response

Body
Name Type Description
adAccountId Long Ad account's ID.
id Long Friend group' ID.
name String Friend group's name.
fileType String Friend group's type.
One of the followings:
- APP_USER_ID: Service user ID
- PHONE_NUMBER: Phone number
- MESSAGE_RETARGET: Message recipients
adGroupIds Long Message ad group ID.
successCount Integer Number of identifiers that are successfully uploaded in the uploaded Friend group files.
failedFileUrl String File URL that contains the identifiers that are failed to be uploaded.
failedCount Integer Number of identifiers failed to be uploaded in the uploaded Friend group files.
status String Status.
One of the followings:
WAITING (Pending), COMPLETE, DELETE, ERROR
createdDate String Date and time of creation in yyyy-MM-dd'T'HH:mm:ss format.

Sample

Request
curl -X POST "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -H "adAccountId: ${AD_ACCOUNT_ID}" \      
    -F "name=friend_group1" \ 
    -F "profileId=12345" \  
    -F "fileType=APP_USER_ID" \ 
    -F "adGroupIds=12345" \  
    -F "files=@local/friend_group_file.csv"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
    "adAccountId" : 1234,
    "id" : 645645,
    "name" : "${FRIEND_GROUP_TARGET_NAME}",
    "fileType" : "APP_USER_ID",
    "adGroupIds" : 12345,
    "successCount" : 20,
    "failedCount" : 1,
    "failedFileUrl" : "${FAILED_FILES_LIST_URL}",
    "status" : "WAITING",
    "createdDate" : "2022-01-01 00:00:00"
}

Edit Friend group name

Basic information
Method URL Authorization
PUT https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/name Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to edit the name of the Friend group. You can use the registered Friend group only for the 'Kakao Talk Channel X Reach(도달)' type of campaign.

Send a PUT request with the issued business token and an ad account ID (adAccountId) in the request header. You must also pass the Friend group's ID and a new name to be changed to when you request. If the request is successful, this API returns the detailed information of the modified Friend group in JSON format. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Body
Name Type Description Required
id Long Friend group's ID. O
name String Friend group's name.
Allowed characters: Korean, English, special characters, space
Character limits: 50 characters		 O

Response

Body
Name Type Description
id Long Friend group's ID.
name String Friend group's name.
fileType String Friend group's type.
One of the followings:
- APP_USER_ID: Service user ID
- PHONE_NUMBER: Phone number
- MESSAGE_RETARGET: Message recipients
groupKey String Friend group file's group key.
profileId String Kakao Talk Channel's profile ID.
talkChannelProfileName String Kakao Talk Channel's profile name.
talkChannelGroupFileStatus String Status.
One of the followings:
WAITING: Pending
COMPLETE: Completed
DELETE: Deleted
ERROR: Failed to create
createdDate String Date and time of creation in yyyy-MM-dd'T'HH:mm:ss format.
lastModifiedDate String Date and time of modification in yyyy-MM-dd'T'HH:mm:ss format.

Sample

Request
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": "edit_name_of_first_friend_group"
        }'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": 1,
    "profileId": 1,
    "name": "edit_name_of_first_friend_group",
    "talkChannelGroupFileStatus": "COMPLETE",
    "talkChannelProfileName": "edit_name_of_first_friend_group",
    "fileType": "APP_USER_ID",
    "groupKey": "9c2754153bc64b3f8df9783f6fe6d4c5",
    "createdDate": "2020-01-01 00:00:00",
    "lastModifiedDate": "2020-01-01 15:00:00"
}

Delete Friend group

Basic information
Method URL Authorization
DELETE https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/${ID} Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to delete a Friend group.

Send a DELETE request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the Friend group's ID as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Long Friend group's ID. O

Sample

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

Delete multiple Friend groups

Basic information
Method URL Authorization
DELETE https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to delete multiple Friend groups at once.

Send a DELETE request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the Friend group's IDs as a parameter when you request. If the request is successful, this API returns the HTTP status code 200 without the response body. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Query parameter
Name Type Description Required
ids String Friend group's ID.
To pass multiple Friend group IDs, separate them with a comma(,).		 O

Sample

Request
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}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

View usage of Friend group

Basic information
Method URL Authorization
GET https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/${ID} Business token
Permission Prerequisite Business Authentication Business consent items
Required:
Request permission		 Switch to a Biz app
Set Business redirect URI
Business consent items		 Required Required

This API enables you to retrieve the list of ad groups that use the designated Friend group.

Send a GET request with the issued business token and an ad account ID (adAccountId) in the request header. You must pass the Friend group's ID as a parameter when you request. If the request is successful, this API returns the list of ad groups and message that use the corresponding Friend group. If failed, refer to Error code to figure out its failure cause.

Request

Header
Name Description Required
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
Business token as a type of user authentication.		 O
adAccountId adAccountId: ${AD_ACCOUNT_ID}
Ad account's ID.		 O
Path variable
Name Type Description Required
ID Long Friend group's ID. O

Response

Body
Name Type Description
- AdGroupAndCampaign[] List of ad groups and campaigns using the Friend group.
AdGroupAndCampaign
Name Type Description
campaign Campaign Information of the campaign.
adGroup AdGroup Information of the ad group.
messageAd MessageAd Information of the message.

Sample

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

See more

Kakao Moment> Friend group management