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

Retrieves a list of Friend groups.

In [타겟 관리(Target management)] > [친구그룹 관리(Friend group management)] in Kakao Moment Partner 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.

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": "first_friend",
        "talkChannelGroupFileStatus": "COMPLETE",
        "talkChannelProfileName": "first_friend",
        "fileType": "APP_USER_ID",
        "groupKey": "2067836d9750480ab67e823e107a2c31",
        "createdDate": "2020-01-01 00:00:00"
    }
]

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.

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.

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"

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"
}

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.

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"
        }'

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"
}

Deletes 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.

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

Deletes 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.

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
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

Retrieves 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.

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"]
        }
    }
]

• Kakao Moment API Reference