Kakao Moment

Friend group management (End of support scheduled)

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

End of support scheduled

The Friend group management APIs are scheduled to end support. Register a new target with customer data.

For details about the end of support for friend groups and the launch of customer data, see Kakao Moment notice.

View list of Friend groups

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/talkChannelGroupFiles`	Business token

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns a list of Friend groups.

Using Friend groups

Upload customer identifiers, such as phone numbers and service user IDs, for multiple ad campaigns and brands.
Registered Friend groups can only be used for Kakao Talk Channel X Reach campaigns.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_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	`Enum`	Friend group's type. `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	`Enum`	Status. `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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Registers customer identifiers obtained from running and operating ads, or previous message recipients, as a Friend group.

Friend group registration conditions

Friend groups are only allowed for a campaign with 'Kakao Talk Channel 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. For the file format, refer to the guide and sample.

When you register friend 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.

Rate limit

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	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_ID}`	O

Body

Name	Type	Description	Required
name	`String`	Friend group's name (Maximum: 50 characters). Allowed characters: Korean, English, special characters, space	O
profileId	`String`	Kakao Talk Channel's profile ID. Use the IDs retrieved through the View list of Kakao Talk Channel profiles API.	O
fileType	`Enum`	Friend group's type. `APP_USER_ID`: Service user ID `PHONE_NUMBER`: Phone number `MESSAGE_RETARGET`: Message recipients	O
files	`Multipart File[]`	Friend group file. Important: Required if `fileType` is set to `APP_USER_ID` or `PHONE_NUMBER`.	X
adGroupIds	`Long[]`	Message ad group ID. Important: Required if `fileType` is set to `MESSAGE_RETARGET`.	X

Response

Body

Name	Type	Description
adAccountId	`Long`	Ad account's ID.
id	`Long`	Friend group' ID.
name	`String`	Friend group's name.
fileType	`Enum`	Friend group's type. `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	`Enum`	Status. `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.

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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Edits the name of a Friend group.

You can use the registered Friend group only for the 'Kakao Talk Channel X Reach(도달)' type of campaign.

Request

Header

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

Body

Name	Type	Description	Required
id	`Long`	Friend group's ID.	O
name	`String`	Friend group's name (Maximum: 50 characters). Allowed characters: Korean, English, special characters, space	O

Response

Body

Name	Type	Description
id	`Long`	Friend group's ID.
name	`String`	Friend group's name.
fileType	`Enum`	Friend group's type. `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	`Enum`	Status. `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 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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Deletes a Friend group.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Deletes multiple Friend groups at once.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns the list of ad groups that use the designated Friend group.

Request

Header

Name	Description	Required
Authorization	Business token as a type of user authentication. `Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}`	O
adAccountId	Ad account's ID. `adAccountId: ${AD_ACCOUNT_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 API Reference

사이드 메뉴

Getting started

Kakao Developers

Login

Communication

Map

Navigation

Advertisement

Search

More

Friend group management (End of support scheduled)

View list of Friend groups

Basic information

Using Friend groups

Request

Header

Response

Body

TalkChannelGroupFile

Sample

Request

Response

Register Friend group

Basic information

Friend group registration conditions

Rate limit

Request

Header

Body

Response

Body

Sample

Request

Response

Edit Friend group name

Basic information

Request

Header

Body

Response

Body

Sample

Request

Response

Delete Friend group

Basic information

Request

Header

Path variable

Sample

Request

Response

Delete multiple Friend groups

Basic information

Request

Header

Query parameter

Sample

Request

Response

View usage of Friend group

Basic information

Request

Header

Path variable

Response

Body

AdGroupAndCampaign

Sample

Request

Response

See more

Was this helpful?

Friend group management (End of support scheduled)