This document describes how to use the Friend group management APIs.
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.
GET /openapi/v4/talkChannelGroupFiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
Pass an access token in Bearer ${ACCESS_TOKEN} format. |
O |
adAccountId | Long |
Ad account's ID. | O |
Name | Type | Description |
---|---|---|
- | FriendGroup[] |
List of Friend group information. |
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 groupCOMPLETE : Creating Friend group has been completedDELETE : Deleted or deletingERROR : 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. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
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"
}
]
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.
PUT /openapi/v4/talkChannelGroupFiles/name HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
Pass an access token in Bearer ${ACCESS_TOKEN} format. |
O |
adAccountId | Long |
Ad account's ID. | O |
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 |
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 : PendingCOMPLETE : CompletedDELETE : DeletedERROR : 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. |
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"
}'
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"
}
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.
DELETE /openapi/v4/talkChannelGroupFiles/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
Pass an access token in Bearer ${ACCESS_TOKEN} format. |
O |
adAccountId | Long |
Ad account's ID. | O |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Friend group's ID. | O |
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/{id}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
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.
DELETE /openapi/v4/talkChannelGroupFiles?plusFriendGroupFileIds=${plusFriendGroupFileIds} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
Pass an access token in Bearer ${ACCESS_TOKEN} format. |
O |
adAccountId | Long |
Ad account's ID. | O |
Name | Type | Description | Required |
---|---|---|---|
plusFriendGroupFileIds | String |
Friend group's ID. To pass multiple Friend group IDs, separate them with a comma(,). |
O |
curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles?plusFriendGroupFileIds= ${plusFriendGroupFileIds},${plusFriendGroupFileIds}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${adAccountId}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"successCount": 1,
"failCount": 1,
"errorMessages": [
"타겟을 사용 중인 오디언스가 있습니다."
]
}
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.
GET /openapi/v4/talkChannelGroupFiles/usages/{id} HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Name | Type | Description | Required |
---|---|---|---|
Authorization | String |
Pass an access token in Bearer ${ACCESS_TOKEN} format. |
O |
adAccountId | Long |
Ad account's ID. | O |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Friend group's ID. | O |
Name | Type | Description |
---|---|---|
- | AdGroupAndCampaign[] |
List of ad groups and campaigns using the Friend group. |
Name | Type | Description |
---|---|---|
id | Long |
Friend group's ID. |
campaign | Campaign |
Information of the campaign. |
adGroup | AdGroup |
Information of the ad group. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles/usages/{id}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: {adAccountId}"
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"
}
}
}
]