Kakao Moment

Friend group management

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

View list of Friend groups

Basic information

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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Body

Name	Type	Description	Required
name	`String`	Friend group's name. Allowed characters: Korean, English, special characters, space Character limits: 50 characters	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	`String`	Friend group's type. One of the followings: `APP_USER_ID`: Service user ID `PHONE_NUMBER`: Phone number `MESSAGE_RETARGET`: Message recipients	O
files	`MultipartFile`	Friend group file. Only required if `fileType` is set to `APP_USER_ID` or `PHONE_NUMBER`.	O*
adGroupIds	`Long[]`	Message ad group ID. Only required if `fileType` is set to `MESSAGE_RETARGET`.	O*

Response

Body

Name	Type	Description
adAccountId	`Long`	Ad account's ID.
id	`Long`	Friend group' ID.
name	`String`	Friend group's name.
fileType	`String`	Friend group's type. One of the followings: `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	`String`	Status. One of the followings: `WAITING` (Pending), `COMPLETE`, `DELETE`, `ERROR`
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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Body

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

Body

Name	Type	Description
id	`Long`	Friend group's ID.
name	`String`	Friend group's name.
fileType	`String`	Friend group's type. One of the followings: `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	`String`	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 ${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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes a Friend group.

Request

Header

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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Deletes multiple Friend groups at once.

Request

Header

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

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

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

Request

Header

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

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