페이지 이동경로
  • 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

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

In [타겟 관리(Target management)] > [친구그룹 관리(Friend group management)] in Kakao Moment Admin Center, you can manually upload the customer identifiers — phone numbers or service user IDs — obtained while operating your ads and services. 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 access 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
URL
GET /openapi/v4/talkChannelGroupFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Response
Name Type Description
- FriendGroup[] List of Friend group information.
FriendGroup
Name Type Description
id Long Friend group's ID.
profileId String Kakao Talk Channel's profile ID.
plusFriendProfileName String Kakao Talk Channel's profile name.
fileType String File type.
Either APP_USER_ID (Service user ID) or PHONE_NUMBER (Phone number).
name String Friend group's name.
friendCount Long Number of friends.
talkChannelGroupFileStatus String File 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.
lastModifiedDate String Date and time of modification 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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
    {
        "id": 1,
        "plusFriendProfileId": 1,
        "name": "first_friend",
        "tlakChannelGroupFileStatus": "COMPLETE",
        "plusFriendProfileName": "first_friend",
        "fileType": "APP_USER_ID",
        "groupKey": "2067836d9750480ab67e823e107a2c31",
        "createdDate": "2020-01-01 00:00:00",
        "lastModifiedDate": "2020-01-01 00:00:00"
    }
]

Edit Friend group name

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 access 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
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 Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
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
Name Type Description
id Long Friend group's ID.
name String Friend group's name.
fileType String File type.
Either APP_USER_ID (Service user ID) or PHONE_NUMBER (Phone number).
profileId String Kakao Talk Channel's profile ID.
plusFriendProfileName String Kakao Talk Channel's profile name.
talkChannelGroupFileStatus String File 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 ${ACCESS_TOKEN}" \
    -H "adAccountId: {adAccountId}" \
    -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,
    "plusFriendProfileId": 1,
    "name": "edit_name_of_first_friend_group",
    "tlakChannelGroupFileStatus": "COMPLETE",
    "plusFriendProfileName": "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

This API enables you to delete a Friend group.

Send a DELETE request with the issued access 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
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 Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
id Long Friend group's 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 multiple Friend groups

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

Send a DELETE request with the issued access 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
URL
DELETE /openapi/v4/talkChannelGroupFiles?plusFriendGroupFileIds=${plusFriendGroupFileIds} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Type Description Required
Authorization String Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
plusFriendGroupFileIds String Friend group's ID.
To pass multiple Friend group IDs, separate them with a comma(,).
O
Sample
Request
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles?plusFriendGroupFileIds= ${plusFriendGroupFileIds},${plusFriendGroupFileIds}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "successCount": 1,
    "failCount": 1,
    "errorMessages": [
        "타겟을 사용 중인 오디언스가 있습니다."
    ]
}

View usage of Friend group

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

Send a GET request with the issued access 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 that use the corresponding Friend group in JSON format. If failed, refer to Error code to figure out its failure cause.

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 Pass an access token in Bearer ${ACCESS_TOKEN} format. O
adAccountId Long Ad account's ID. O
Parameter
Name Type Description Required
id Long Friend group's ID. O
Response
Name Type Description
- AdGroupAndCampaign[] List of ad groups and campaigns using the Friend group.
AdGroupAndCampaign
Name Type Description
id Long Friend group's ID.
campaign Campaign Information of the campaign.
adGroup AdGroup Information of the ad group.
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": "first_ad_group",
            "adGroupStatus": [
                "READY"
            ]
        },
        "campaign": {
            "id": 9012,
            "name": "first_campaign",
            "campaignTypeGoal": {
                "campaignType": "TALK_CHANNEL",
                "goal": "REACH"
            }
        }
    }
]

See more