Kakao Developers

페이지 이동경로

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

kakao developers

menu

Kakao Moment

Friend group management

View list of Friend groups

URL

Header

FriendGroup

Request

Response

Edit Friend group name

URL

Header

Parameter

Request

Response

Delete Friend group

URL

Header

Parameter

Request

Response

Delete multiple Friend groups

URL

Header

Parameter

Request

Response

View usage of Friend group

URL

Header

Parameter

AdGroupAndCampaign

Request

Response

See more

Service usage information

Service usage information